Apama Capital Markets Foundation  10.3.0.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Session Manager Library

Market Data adapter advertise themselves as datasource using one or more Sessions. The Session Manager Library takes care of session and status handling and provides "C" interfaces to:-

  • add and remove sessions
  • add and remove what capabilities a session has
  • add what parameters a session expect
  • success and failure callbacks for adapter requests
  • generate adapter status information

Session Adapter Interface

The Session Manager Library communicates with your adapter via the AP_SESSION_AdapterInterface structure. You must initialize an AP_SESSION_AdapterInterface structure with working functions before the library is initialized.

Session Manager Library Initialization

The Session Manager Library is initialized by a call to AP_SESSION_Init() in the event transport constructor of the adapter, where you provide an AP_SESSION_AdapterInterface and a pointer to the transport internals. This will initialize a AP_SESSION_Interface which is then used in all subsequent Session Manager API calls. During the event transport destructor, call AP_SESSION_DeInit().

See also
Session Initialization and Cleanup API

Session Registration

The adapter should find out the sources it wishes to advertise upon start-up, either programmatically or they can be hard coded. Once the sources are identified, they need to be registered with the correlator instance. Sources can be added dynamically.

Sessions are added using AP_SESSION_AddSession() and their parameters using AP_SESSION_AddSessionParams(). By default every session has this parameter:-

Parameter Description Type Allowed Values Default
HEARTBEAT_TIMEOUT Correlator heartbeat timeout in seconds float - 20

Once all the Sessions have been added with their parameters and capabilities, the adapter calls AP_SESSION_RegisterSessions() or AP_SESSION_RegisterSession() and the library will attempt the register them with the MDA Session Manager running in the correlator. If a Session is successfully registered, the transport registered onSessionRegistrationSuccess will be called that was provided in the AP_SESSION_AdapterInterface structure. If a Session fails to register, the transport registered AP_SESSION_AdapterInterface::onSessionRegistrationError() is called.

See also
Session and Parameter addition API
Session Register API

Session Capabilities

Session Capabilities are the MDA data types that a session can provide, the Market Data Library offers APIs for:-

Type Description API
STREAMTYPE_BBA Best Bid and Ask BBA Processing API
STREAMTYPE_TRADE Trade Trade Processing API
STREAMTYPE_MBP Market by Price / Depth Depth Processing API
STREAMTYPE_MBO Market by Order / Orderbook Orderbook Processing API
STREAMTYPE_QUOTEBOOK Quotebook Quotebook Processing API
STREAMTYPE_NEWS News News Processing API
STREAMTYPE_EP Extra Parameters Extra Params Processing API

also see Session Capabilities. A adapter however can add it's own capabilities, such as OHLC or Market Phase.

Once a Session has been added, all its capabilities are then provided to the Session Manager Library using the AP_SESSION_AddCapabilities() or AP_SESSION_AddCapabilitiesById() API calls. Then each of the capabilities should have its parameters set using AP_SESSION_AddCapabilityParams() or AP_SESSION_AddCapabilityParamsById() API calls.

By default every capability has these parameter:-

Parameter Description Type Allowed Values Default
TRANSFER_MODE The mode which updates are sent string 'COMPOUND_DELTA' or 'SNAPSHOT_ONLY' 'COMPOUND_DELTA'
NUM_LEVELS The maximum number of levels a book data type will send (applies to Depth, Orderbook and Quotebook) integer - 5
DISABLE_EP Whether to disable Extra Parameter output boolean true/false false
INCLUDE_INDICATIVE_PRICES Whether to include indicative prices in the Quotebook boolean true/false true
See also
Supported Capabilities
Session Capabilities API

Session Start, Stop and Configuration

When a user wants to start a session, the transport registered AP_SESSION_AdapterInterface::onSessionStart() is called and the adapter should connect to the external source. Once connected, set the Session state to SESSION_CONNECTED using AP_SESSION_SetSessionStateByName() or AP_SESSION_SetSessionStateById() and then call the Session start success callback AP_SESSION_SessionStartSuccess(). If the Session fails to start, call AP_SESSION_SessionStartError().

User configuration for the session is provided in the configParams in the transport registered AP_SESSION_AdapterInterface::onSessionStart().

The the transport registered AP_SESSION_AdapterInterface::onSessionReconfigure will be called when a user wants a Session to be reconfigured with the supplied configParams. If the reconfiguration is successful call AP_SESSION_SessionReconfigureSuccess(), else call AP_SESSION_SessionReconfigureError().

When a user wants to stop a session, the transport registered AP_SESSION_AdapterInterface::onSessionStop is called and the adapter should disconnect from the external source. Once disconnected, set the Session state to SESSION_DISCONNECTED using AP_SESSION_SetSessionStateByName() or AP_SESSION_SetSessionStateById() and then call the Session stop success callback AP_SESSION_SessionStopSuccess(). If the Session fails to stop, call AP_SESSION_SessionStopError().

There are some other states that a Session can be set to depending on the complexity of the adapter (such as Logged In), see AP_SESSION_State.

See also
Session Callbacks API
Session State API
AP_SESSION_State

Session Reset and Heartbeats

Heartbeat events are passed between the correlator and adapter so each component knows about the continued existence of the other. If the correlator does not receive a heartbeat response, which could be due to unavailability of the adapter or network delay, the transport registered AP_SESSION_AdapterInterface::onSessionReset is called. The adapter should then clean up it's subscriptions and return to an initial state. The correlator will then attempt to re-start the Session and re-subscribe to symbols. The transport registered AP_SESSION_AdapterInterface::onCorrelatorWatchDogTimedOut() is called when the library fails to receive heartbeats from the correlator. The adapter should then:-

  • Stop processing any messages from external sources.
  • Clear all subscriptions.
  • Clear all Sessions.
  • Disconnect all sources.

The adapter can update the heartbeat timeout interval that the library waits by using the AP_SESSION_SetCorrelatorHBTimeout().