In This Section

Overview

This section 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.

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 the application will use. 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 configuration 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 an application uses 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 should 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 can 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:

Component Name	Descriptor Class	Description
SMA Bus	com.neeve.sma.MessageBusDescriptor	Configures a Bus
SMA Channel	com.neeve.sma.MessageChannelDescriptor	Configures a Bus Channel
ODS Store Descriptor	com.neeve.ods.StoreDescriptor	Configures the Store for an Engine (providing HA)
ODS Store Replicator Descriptor	com.neeve.ods.StoreReplicatorDescriptor	Configures store replication to backup members
ODS Persister	com.neeve.ods.StorePersisterDescriptor	Configures store disk persistence
ODS ICR Descriptor	com.neeve.ods.StoreInterClusterReplicatorDescriptor	Configures store inter cluster replication (e.g. remote data center)
AEP Engine	com.neeve.aep,AepEngineDescriptor	Configures the applications AepEngine
XVM (Talon Server)	com.neeve.server.config.SrvConfigDescriptor	Configures an XVM

Note, that with the exception of the SrvConfigDescriptor, it is possible for an application to augment configuration seeded by the XML configuration descriptor programattically with the component descriptor:

@AppInjectionPoint
public void setAepEngineDescriptor(AepEngineDescriptor appDescriptor) {
   appDescriptor.setAppExceptionHandlingPolicy(LogExceptionAndContinue);
   appDescriptor.save();

   if(appDescriptor.getStore() != null) {
	   StoreDescriptor storeDescriptor = StoreDescriptor.load(appDescriptor.getStore());
       storeDescriptor.setPersistenceQuorum(1);
       storeDescriptor.save(); 
   }
}

Configuration Script: X supports an internal scripting format using which the configuration repository can be populated.
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, it processes the XML descriptor in 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.

Note: It is possible to materialize configuration into the repository from external storage even when operating in embedded mode. However, that puts the burden of responsibility of managing, distributing and storing the platform configuration in the appropriate format and location external to the process so that the configuration is picked up correctly from the external storage. This responsibility is picked up by Robin when operating in non-embedded mode.

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>
                <buses> 
                  <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>
                </buses>
            </messaging>
            <storage>
            	<clustering>
            	   <localIfAddr>${FORWARDER_REPLICATION_INTERFACE::localhost}</localIfAddr>
	       	       <localPort>12000</localPort>
       		    </clustering>
                <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.

When configuring the platform using the VMConfigurer class, the environment is the composition of the user property table, process environment, and Java system properties, in that order of precedence.

Applications (AEP Engines)

<apps>
    <app name="forwarder" mainClass="com.neeve.samples.Forwarder">
        <messaging>
          <buses> 
            <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>
          </buses> 
        </messaging>
        <storage>
            <clustering>
               <localIfAddr>${FORWARDER_REPLICATION_INTERFACE::localhost}</localIfAddr>
	           <localPort>12000</localPort>
            </clustering>
            <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>

The 'app's section configures the various applications in the scenario. An application is synonymous with an AEP engine. For example, the above configures three applications (i.e. engines).

An engine named 'forwarder',
- whose main entry point is "com.neeve.samples.Forwarder".
- who is interested in receiving messages (i.e. subscribing to) on the 'orders' channel.
- who sends messages over the 'events' channel.
- who operates its 'frontoffice' bus connection manager in a detached send manner i.e. message serialization happens in a thread different from the business logic thread.
- who performs store persistence in an attached manner with a page size of 16K.
- .
- .
- .
An engine named 'receiver',
- whose main entry point is "com.neeve.samples.Receiver".
- .
- .
- .
An engine named 'sender',
- whose main entry point is "com.neeve.samples.Sender".
- .
- .
- .

An application's entry point is used by a Talon Server as the main application class to load.

Messages associated with channels indicate the default channel over which a message is sent and which forms part of messaging ROE between application agents.

Talon Servers (XVMs)

<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>

The 'servers' sections configures the various Talon servers in the scenario. For example, the above configures four Talon Servers.

The 'forwarder1' and 'forwarder2' servers are configured to manage the clustered 'forwarder' application.
- All applications of the same name will join to form a cluster.
The 'receiver' server configured to manage the standalone 'receiver' application.
The 'sender' server configured to manage the standalone 'sender' application.