Pages/GettingStarted.md

Go to the documentation of this file.

\addtogroup getting-started

\brief Guides through the most significant 
parts of the Handler's architecture.

\details The OnixS::CME::MDH namespace encapsulates the SDK API.
The master `OnixS/CME/MDH.h` header file collects all header files 
for more convenience.

Following sections guide through the major steps to be done 
to succeed with market data processing.

\section specifying-license Initializing and Licensing SDK

The SDK needs a valid license for successful execution. If 
the licensing subsystem is not able to find a valid license, 
it throws an exception at the initialization stage when the 
OnixS::CME::MDH::initialize is called. Also, a license is 
verified each time an attempt to start market data processing 
is done using the OnixS::CME::MDH::Handler::start member.

The OnixS::CME::MDH::InitializationSettings class exposes the 
OnixS::CME::MDH::InitializationSettings::licenseStore member which 
must be used to instruct the SDK where to look for a valid license. 
By default, the licensing services look for a license in the current 
directory of the application. However, by using noted parameter, it 
is possible to specify another folder anywhere on file system. 

\note The licensing subsystem looks for a valid license in the 
specified folder and selects the best one. If multiple licenses 
are available, it selects the most significant one (for example, 
a production license is selected instead of a trial one if both 
are available).

The following example demonstrates how to perform one-time SDK initialization:

~~~{.cpp}

// Parameters for one-time initialization.
InitializationSettings settings;

// The folder in which the license is stored.
settings.licenseStore("license");

// Initializes all Handler services explicitly.
OnixS::CME::MDH::initialize(settings);

~~~

\section constructing-handler-instance Configuring and Constructing the Handler

The OnixS::CME::MDH::Handler class incapsulates a market data processing 
machinery. A single instance of the OnixS::CME::MDH::Handler processes 
market data for a single CME channel.

The users must define settings affecting market data processing behavior 
before constructing an instance of the OnixS::CME::MDH::Handler class.

The OnixS::CME::MDH::HandlerSettings class contains all parameters 
controlling various aspects of market data processing including 
the behavior of the OnixS::CME::MDH::Handler. 

In the most cases, default values are set for parameters defining 
the most likely behavior of the OnixS::CME::MDH::Handler instance. 
However, some parameters must be set explicitly before constructing 
an instance of the OnixS::CME::MDH::Handler class.

~~~{.cpp}

HandlerSettings settings;

settings.channel(310);

settings.
    feeds().
    connectivityConfigurationFile("config.xml");

Handler handler(settings);

~~~

See [Handler's Settings](\ref handler-settings) for more
information on adjusting behavior of the Handler.

\section binding-feedengine-to-handler Binding Feed Engine to the Handler

The OnixS::CME::MDH::FeedEngine class encapsulates a layer responsible for 
receiving market data which is transmitted by the CME MDP. Therefore, to have
successful processing of market data, it is necessary to construct an instance 
of the Feed Engine and to bind it to the previously constructed instance of 
the OnixS::CME::MDH::Handler class:

~~~{.cpp}

FeedEngineSettings feSettings;

FeedEngine feedEngine(feSettings);

handler.bindFeedEngine(feedEngine);

~~~

See [Feed Engine](\ref feed-engine) for more details on Feed Engine.

\note An instance of the OnixS::CME::MDH::Handler does not manage 
lifetime of a bound OnixS::CME::MDH::FeedEngine instance. Therefore, 
user responsibility is to keep an instance of the OnixS::CME::MDH::FeedEngine 
class valid while it is bound to an instance of OnixS::CME::MDH::Handler class.

\section binding-logger-to-handler Logging Market Data and Other Events (Optional)

The Handler may log market data it processes for further use by 
replay feature or analysis as well as other important events which 
may take place during regular market data processing.

The OnixS::CME::MDH::Logger abstract class encapsulates the 
logging subsystem. The SDK provides various implementations 
of logging for different purposes. File-based logging is 
satisfactory choise for the most cases.

Below is an example of how file based logging can be established:

~~~{.cpp}

FileLoggerSettings loggerSettings;

// Sets filename of log as it was used by older Handlers.
loggerSettings.filename(makeLogFilename(310));

// Varies which events are to be logged.
loggerSettings.severityLevel(LogSeverity::Debug);

FileLogger logger(loggerSettings);

handler.bindLogger(logger);

~~~

\note An instance of the OnixS::CME::MDH::Handler does not manage 
lifetime of a bound OnixS::CME::MDH::Logger instance. Therefore, 
user responsibility is to keep an instance of the OnixS::CME::MDH::Logger 
class valid while it is bound to an instance of OnixS::CME::MDH::Handler class.

\section registering-listeners-with-handler Subscribing to Market Data Events

Once an instance of the OnixS::CME::MDH::Handler is constructed 
and bound to an instance of the OnixS::CME::MDH::FeedEngine, market 
data processing can be started. However, it's necessary to subscribe 
to corresponding events to get the results of market data processing 
like updated order books.

See the [Event Listeners](\ref event-listeners) topic concerning which 
events are exposed by the Handler and how to subscribe to a particular 
event.

\section spawning-md-processing Spawning Market Data Processing

As soon as an instance of the OnixS::CME::MDH::Handler is configured, 
bound to a valid instance of the OnixS::CME::MDH::FeedEngine and listeners 
for events are registered, market data processing can be initiated.

Market data processing is initiated by invoking the OnixS::CME::MDH::Handler::start 
member, which accepts an instance of OnixS::CME::MDH::SessionSettings class defining
the behavior of the Handler for the session.

For the most common processing scenarios, the SDK exposes ready-to-use
presets of session settings: OnixS::CME::MDH::AccurateLateJoinSession(),
OnixS::CME::MDH::AccuratePreopeningSession, OnixS::CME::MDH::NaturalRefreshSession,
etc. See documentation for noted classes for more details.

~~~{.cpp}

handler.start(AccurateLateJoinSession());

~~~

The OnixS::CME::MDH::Handler::stop member must be 
called to accomplish live market data processing:

~~~{.cpp}

handler.stop();

~~~

\note For more and up-to-date information on getting started aspects,
see __GettingStarted__ sample from the samples collection available in
distributive package.