...

...

Purpose

This page provides a high level overview of how X Platform components are configured. It also serves as a reference for the configuration properties supported by the various components.

Overview

Image Added

Configuration Repository

The diagram above provides a high level depiction of the X Platform's configuration architecture. Salient aspects of this architecture are:

• Each X application process contains an instance of the X Platform Configuration Repository. The repository stores configuration information in a proprietary format keyed by hierarchical names. The repository implements the com.neeve.config API for programmatic access to the repository
• X Platform components, such as AEP Engines, SMA Buses and ODS Stores/Persisters, are uniquely identified in the system via a hierarchical name comprised of their type and a name that is unique within the type. For example an AEP engine named StockTicker is uniquely named as /aep/engines/StockTicker in the repository. It uses this hierarchical name to fetch its configuration from the repository.

Application Lifecycle

The configuration of X Platform components is tied very closely to the application's lifecycle. 

• Configure Phase: From X's standpoint, when an application is launched, the first task at hand is to populate the configuration repository with the configuration of the various platform components that are going to be used by the application. This needs to be done before any of the platform's runtime machinery is invoked to ensure that the runtime machinery picks up the correct configuration intended for it. This population can be done in variety of ways (as documented below) depending on (1) whether X is being used in an embedded or non-embedded fashion and (2) how an application distributes and manages its and the platform's configuration. 
• Run Phase: Once the configuration repository is populated, the application can then commence the use of platform components e.g. create/start an AEP engine, launch a server etc. As mentioned above, an application configures components via their companion descriptors. The following are the general steps used by an application when creating a platform component:
  • Create an instance of the component descriptor
  • Load the contents of the descriptor from the configuration repository. Each descriptor provides a load() method using which the descriptor can initialize itself using configuration information in the repository keyed by the name of the component that the descriptor represents.
  • Create the component using the descriptor to supply the component configuration.

This document is only concerned with the Configure Phase. 

Populating the Repository

X supports different ways to populate a configuration repository depending on whether X is being used in an embedded or non-embedded manner and, if embedded, how the configuration information is distributed and managed. 

Embedded Use

X is considered to be used in an embedded manner when the application's main entry point is in the application code. When used in this manner, the following are the supported mechanisms by which the configuration repository can be populated:

• XML Descriptor: The platform allows an application to describe an application's entire configuration in XML form and programmatically initialize a repository using the XML descriptor. XML Configuration is defined by the Domain Descriptor Language schema, x-ddl.xsd. This is the recommended mechanism if an application can store the platform configuration in XML form or convert the configuration from its own form to XML to be supplied to the platform for configuration. 
  • The application should use the com.neeve.VMConfigurer class to configure the platform using an XML descriptor
  • The XML Descriptor is described by its corresponding x-ddl.xsd schema. Usage of XML is described below, and in even greated detail in the DDL Schema Reference documentation.

• Component Descriptors: Each platform component is accompanied by a companion configuration descriptor that is used to programmatically configure the component. In addition to implementing setters and getters to set and get configuration attributes, descriptors also implement the ability to save configuration  properties to the repository. This allows for application code to programmatically seed configuration information into the repository. This mechanism is suited for use when platform related configuration cannot be easily transformed to XML form. The following are the various descriptor classes:
  
  

  Project	Component Name	Descriptor Class
  Talon	SMA Bus	com.neeve.sma.MessageBusDescriptor
  Talon	SMA Channel	com.neeve.sma.MessageChannelDescriptor
  Talon	ODS Persister	com.neeve.ods.StorePersisterDescriptor
  Talon	ODS ICR Descriptor	com.neeve.ods.StoreInterClusterReplicatorDescriptor
  Talon	ODS Store Descriptor	com.neeve.ods.StoreDescriptor
  Talon	AEP Engine	com.neeve.aep,AepEngineDescriptor

• Configuration Script: X supports an internal scripting format using which the configuration repository can be populated.

  Note
  This mechanism is used internally by X and is not recommended for external use. It is only listed here for information purpose to avoid confusion when script related trace appear in X's trace logs

Non-Embedded Use

The X Platform is considered to be used in a non-embedded manner when the application's main entry point is in a Talon Server. When used in this manner, the configuration repository is initialized from external storage via the configured persistence plugin. It is recommended that Robin be used for the configuration, deployment and management of X applications when X is used in a non-embedded manner. The Robin framework uses the same XML descriptor as described above to configure the platform. However, processes the XML descriptor is a manner that allows for the platform configuration and application code to be deployed using independent channels such that the configuration materializes in the Talon server from external storage when the server is launched. Refer to the Robin documentation for further information on how to use the X Platform in a non-embedded manner.

The XML Configuration Descriptor

X supports describing and initializing platform configuration using XML via its Domain Descriptor Language schema (x-ddl.xsd). This section describes commonly used DDL configuration elements, more detail can be found in DDL Schema Reference, which discusses all of the attributes in more detail. 

Overview

The XML document above is a sample configuration document. The document describes a multi-agent application scenario. 

<?xml version="1.0"?>
<model xmlns="http://www.neeveresearch.com/schema/x-ddl" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <buses>
        <bus name="frontoffice" descriptor="${FRONTOFFICE_BUSDESCRIPTOR::falcon://fastmachine:8040}">
            <channels>
                <channel id="1" name="orders">
                    <qos>Guaranteed</qos>
                </channel>
                <channel id="3" name="events">
                    <qos>BestEffort</qos>
                </channel>
            </channels>
        </bus>
    </buses>
    <apps>
        <app name="forwarder" mainClass="com.neeve.samples.Forwarder">
            <messaging>
                <bus name="frontoffice">
                    <channels>
                        <channel name="orders" join="true"/>
                        <channel name="events" join="false"/>
                    </channels>
                    <detachedSend enabled="${FORWARDER_FRONTOFFICEDETACHEDSEND::true}">
                        <queueDepth>1024</queueDepth>
                        <queueOfferStrategy>SingleThreaded</queueOfferStrategy>
                        <queueWaitStrategy>BusySpin</queueWaitStrategy>
                        <queueDrainerCpuAffinityMask>${FORWARDER_FRONTOFFICEDETACHEDSENDCPUAFFMASK::0}</queueDrainerCpuAffinityMask>
                    </detachedSend>
                </bus>
            </messaging>
            <storage descriptor="${FORWARDER_STOREDESCRIPTOR::native://.}">
                <persistence>
                    <pageSize>16384</pageSize>
                    <detachedPersist enabled="false"/>
                </persistence>
            </storage>
        </app>

        <app name="receiver" mainClass="com.neeve.samples.Receiver">
            <messaging>
                <bus name="frontoffice">
                    <channels>
                        <channel name="orders" join="true"/>
                    </channels>
                </bus>
            </messaging>
        </app>

        <app name="sender" mainClass="com.neeve.samples.Sender">
            <messaging>
                <bus name="frontoffice">
                    <channels>
                        <channel name="orders" join="false"/>
                        <channel name="events" join="true"/>
                    </channels>
                </bus>
            </messaging>
        </app>
    </apps>

    <servers>
        <server name="forwarder1">
            <apps>
                <app name="forwarder" autoStart="true"/>
            </apps>
        </server>

        <server name="forwarder2">
            <apps>
                <app name="forwarder" autoStart="true"/>
            </apps>
        </server>

        <server name="receiver">
            <apps>
                <app name="receiver" autoStart="true"/>
            </apps>
        </server>

        <server name="sender">
            <apps>
                <app name="sender" autoStart="true"/>
            </apps>
        </server>
    </servers>
</model>

Messaging Buses & Connection Descriptors

<bus name="frontoffice" descriptor="${FRONTOFFICE_BUSDESCRIPTOR::falcon://fastmachine:8040}">
    <channels>
        <channel id="1" name="orders">
            <qos>Guaranteed</qos>
        </channel>
        <channel id="3" name="events">
            <qos>BestEffort</qos>
        </channel>
    </channels>
</bus>

The 'buses' section configures the various messaging buses in use in the scenario. For example, the above configures a messaging bus named 'frontoffice' that 

• Uses a Falcon publish-subscribe bus for message transport between application agents
  • The bus to use can be overridden from the environment via the FRONTOFFICE_BUSDESCRIPTOR variable
• Contains two channels 
  • 'orders' channel with guaranteed quality of delivery
  • 'event's channel with best effort quality of delivery

<apps>
    <app name="forwarder" mainClass="com.neeve.samples.Forwarder">
        <messaging>
            <bus name="frontoffice">
                <channels>
                    <channel name="orders" join="true"/>
                    <channel name="events" join="false/">
                </channels>
                <detachedSend enabled="${FORWARDER_FRONTOFFICEDETACHEDSEND::true}">
                    <queueDepth>1024</queueDepth>
                    <queueOfferStrategy>SingleThreaded</queueOfferStrategy>
                    <queueWaitStrategy>BusySpin</queueWaitStrategy>
                    <queueDrainerCpuAffinityMask>${FORWARDER_FRONTOFFICEDETACHEDSENDCPUAFFMASK::0}</queueDrainerCpuAffinityMask>
                </detachedSend>
            </bus>
        </messaging>
        <storage descriptor="${FORWARDER_STOREDESCRIPTOR::native://.}">
            <persistence>
                <pageSize>16384</pageSize>
                <detachedPersist enabled="false"/>
            </persistence>
        </storage>
    </app>

    <app name="receiver" mainClass="com.neeve.samples.Receiver">
       .
       .
       .
    </app>

    <app name="sender" mainClass="com.neeve.samples.Sender">
       .
       .
       .
    </app>
</apps>

<servers>
    <server name="forwarder1">
        <apps>
            <app name="forwarder" autoStart="true"/>
        </apps>
    </server>

    <server name="forwarder2">
        <apps>
            <app name="forwarder" autoStart="true"/>
        </apps>
    </server>

    <server name="receiver">
        <apps>
            <app name="receiver" autoStart="true"/>
        </apps>
    </server>

    <server name="sender">
        <apps>
            <app name="sender" autoStart="true"/>
        </apps>
    </server>
</servers>