Pages/MigrationGuide.md

Go to the documentation of this file.

\addtogroup migration-guide

\brief Covers aspects on migrating from previous releases.

Although given release is based on the same processing core as a previous major 
version release, a lot of aspects have been principally redesigned and improved. 
Given section covers major differences for painless migration from previous releases. 

\section migrate-listener-consolidation Consolidated Listeners

In previous generations of SDK, listeners were designed to cover smallest 
aspects of market data processingand thus API contained bunch of listeners 
to be used to get market-related events handled in a regular application. 
For example, there was a `OnixS::CME::MDP3::SecurityDefinitionListener` whose
members were involved once instrument definition was received and updated. 
For each type of book there was corresponding listener exposing books after
updates. Atomic book changes could be accessed through another set of listeners. 

To reduce overhead caused by necessity of using wide range of listeners and 
to bring more clarity, most of listeners have been consolidated.

Primary principle was to consolidated Handler, Market Data (message) and Security
related events. Table below depicts basic correspondence between old and new listeners.

<table>
  <tr>
    <th>Old Listeners</th>
    <th>New Listener</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>
      `OnixS::CME::MDP3::HandlerStateChangeListener`
      `OnixS::CME::MDP3::WarningListener`
      `OnixS::CME::MDP3::ErrorListener`
    </td>
    <td>
      `OnixS::CME::MDH::HandlerListener`
    </td>
    <td>
      State change and issue (warning, error) events were merged into the new 
      listener containing callbacks which are invoked to notify users on various 
      aspects of market data processing by Handler. 
    </td>
  </tr>
  <tr>
    <td>
      `OnixS::CME::MDP3::MessageProcessingListener`
      `OnixS::CME::MDP3::EventMessageListener`
      `OnixS::CME::MDP3::EventListener`
    </td>
    <td>
      `OnixS::CME::MDH::MarketDataListener`
    </td>
    <td>
      OnixS::CME::MDH::MarketDataListener represents adoptation of 
      `OnixS::CME::MDP3::MessageProcessingListener` to the new messaging 
      subsystem. Since unified FIX message container was substituted with
      typified SBE messages as they are defined in CME specification, 
      listener was enhanced with overloads for each type of new message.

      Also, new members defining bounds of packet processing have been 
      added. For this reason old `EventMessageListener` and `EventListener`
      listeners were removed from API as the improved market data listener
      allows to implement given event in easy way. 
    </td>
  </tr>
  <tr>
    <td>
      `OnixS::CME::MDP3::SecurityDefinitionListener`

      `OnixS::CME::MDP3::MboBookUpdateListener`
      `OnixS::CME::MDP3::DirectBookUpdateListener`
      `OnixS::CME::MDP3::ImpliedBookUpdateListener`
      `OnixS::CME::MDP3::ConsolidatedBookUpdateListener`

      `OnixS::CME::MDP3::MboBookChangeListener`
      `OnixS::CME::MDP3::DirectBookChangeListener`
      `OnixS::CME::MDP3::ImpliedBookChangeListener`

      `OnixS::CME::MDP3::TradeListener`
      `OnixS::CME::MDP3::OrderIdListener`
      `OnixS::CME::MDP3::ElectronicVolumeListener`

      `OnixS::CME::MDP3::StatisticsListener`

      `OnixS::CME::MDP3::SecurityStatusListener`
      
      `OnixS::CME::MDP3::RequestForQuoteListener`
    </td>
    <td>
      `OnixS::CME::MDH::SecurityListener`
    </td>
    <td>
      Security-related events are now consolidated into single listener.

      Following important changes were done in the how particular cases
      are handled:

      - Unknown security definitions are now exposed through the 
        OnixS::CME::MDH::SecurityListener::onUndefined member which 
        also allows to update security attributes like security group, 
        asset, etc. Previously, unknown securities were not exposed 
        through security definition listeners. Instead, Handler raised
        a warning on absence of definition. 

      - Trade summary processing has been reworked. Previously, SDK exposed 
        separate listeners for trades and order identifiers providing special 
        indexing for linking order ids with the trades. Now, trades are always 
        reported through the same OnixS::CME::MDH::SecurityListener::onTrade 
        callback. Order ids refering to a particular trade summary can be 
        gathered by the Handler and delivered together with a trade summary 
        instance depending on a trade summary handling strategy controlled by 
        OnixS::CME::MDH::HandlerSettings::tradeProcessing parameter value. 
        See \ref trade-order-details for more information. 

      - Previously, maintenance of books of a particular type was enabled by Handler
        basing on registering instance of listener for that kind of books. Now, as Book
        update callbacks consolidated into single listener together with the other events
        maintenance is explicitly defined by corresponding parameters which define whether
        particular overload of OnixS::CME::MDH::SecurityListener::onBookUpdate will be
        invoked by the Handler or not. 
    </td>
  </tr>
</table>

\section  migrate-book-management Book Management

Previously, maitenance of books of particular type (MBO, direct, implied, 
consolidated) was automatically enabled by Handler if either corresponding 
listener was associated with an instance of OnixS::CME::MDH::Handler or
book maintenance was forcibly enabled through Handler's settings. 

Also, depending on which listeners are registered (for example, listener for atomic 
changes in direct order book), Handler selected appropriate source of recovery data 
to catch-up up-to-date market state during late join or after detecting gap in incremental 
data. For example, if user was interested in receiving MBO book updates without subscribing 
to MBP book updates, Handler listened to recovery data on MBO snapshot feed only without 
joining snapshot feed for MBP books. 

In given release, Handler's behavior has been improved to be more clear for the users. 

Book updates are now exposed through OnixS::CME::MDH::SecurityListener::onBookUpdate 
members of consolidated listener for security-related data. However, overriding noted 
virtual member doesn't mean subscribing to a book updates. Book maintenance is explicitly 
defined by corresponding parameter from OnixS::CME::MDH::HandlerSettings::bookManagement() 
section:

| Parameter Path                                                               | Description                                        |
|------------------------------------------------------------------------------|----------------------------------------------------|
| `handlerSettings.bookManagement().mboBooks().maintain(bool status)`          | Enables or disables MBO books maintenance          |
| `handlerSettings.bookManagement().directBooks().maintain(bool status)`       | Enables or disables direct books maintenance       |
| `handlerSettings.bookManagement().impliedBooks().maintain(bool status)`      | Enables or disables implied books maintenance      |
| `handlerSettings.bookManagement().consolidatedBooks().maintain(bool status)` | Enables or disables consolidated books maintenance |

Once parameter is turned on, Handler invokes OnixS::CME::MDH::SecurityListener::onBookUpdate 
overload corresponding to the type of book. 

Also, behavior of the Handler in case of market recovery is now controlled by 
OnixS::CME::MDH::SessionSettings::marketRecovery parameter. It allows to define 
explicitly whether Handler must listen and process data from either MBO snapshot 
feed or MBP snapshot feed or both feeds. 

Given improvement in behavior of the Handler allows users to obtain desired 
processing behavior without involving book maintenance. 

\section migrate-books Book Classes

Book classes have been cleaned up. OnixS::CME::MDP3::BookBase::securityId and 
OnixS::CME::MDP3::BookBase::lastAppliedSecurityLevelSeqNumber members have been 
removed. 

Data exposed by eliminated members is now consolidated into a new OnixS::CME::MDH::Security 
class, containing all security-related attributes. Instances of given class are exposed in 
all callbacks of OnixS::CME::MDH::SecurityListener listener. Therefore, security identifier
and instrument-level sequence number are now available for trade and statistics events. 

| Old Member | New Member | Description |
|---|---|---|
| `OnixS::CME::MDP3::BookBase::securityId` | `OnixS::CME::MDH::Security::id` | Security id relocated from book to security instance |
| `OnixS::CME::MDP3::BookBase::lastAppliedSecurityLevelSeqNumber` | `OnixS::CME::MDH::Security::seqNumber` | Now available in other security-related callbacks |

\section migrate-feed-engine Feed Engine

Concept of \ref feed-engine was introduced in previous major release of the SDK
and given release inherits given concept. However, a few important changes have
been made. 

Previosly, to provide backward compatibility with older minor releases, feed engine
could be constructed explicitly and bound with OnixS::CME::MDH::Handler instances.
If no instance of OnixS::CME::MDH::FeedEngine was associated with an instance of
OnixS::CME::MDH::Handler, then Handler constructed private instance of the feed engine. 

In given release, implicit construction has been eliminated to provide better clarity
on Handler behavior and use of system resources. Therefore, to make live market data
processing happen, instance of OnixS::CME::MDH::FeedEngine must be constructed and 
bound to the instance of OnixS::CME::MDH::Handler. 

\note There's no limitation on number of feed engine instances constructed. 
Therefore, having single instance of OnixS::CME::MDH::FeedEngine for each 
instance of OnixS::CME::MDH::Handler can be easy be achieved by constructing
and binding pair of instances. 

\section migrate-feed-events Feed Events

Feed-related events have been redesigned. First of all, direct access to sockets 
used to listen to multicast data has been eliminated. OnixS::CME::MDP3::FeedSocket 
class is not available any more. Feed identification in events have been improved 
and now feed is identified by OnixS::CME::MDH::NetFeed class containing primary 
attributes of the feed which caused an event. 

Event listener was enhanced with a new member OnixS::CME::MDH::FeedListener::onFeedPacket
allowing to trace market data received by the Handler on a particular feed. An important
difference between this callback and the one in OnixS::CME::MDH::MarketDataListener is that 
given callback is invoked by Handler every time data is received no matter whether this is 
duplicated or out-of-order data. Given enhancement allows to implement various tracing 
facilities to determine issues in data reception or its sequencing. 

OnixS::CME::MDP3::FeedListener::onFeedSequenceIssues event and related with it functionality 
was removed from the Handler. Instead, OnixS::CME::MDH::FeedListener::onFeedPacket can be used
to trace feeds for the issues.

\section migrate-instrument-cache Instrument Definition Cache

Handler exposes ability to cache instrument definitions received on live instrument 
feed for further reuse at late join. Previously, Handler used predefined filename and
stored cache in a certain location. Therefore, settings exposed boolean parameter 
OnixS::CME::MDP3::HandlerSettings::cacheSecurityDefinitions which allowed to either
enable or disable instrument definition caching. 

In given release, behavior was been improved and now Handler allows to specify arbitrary 
filename and location. Instrument definition caching is enabled while  non-empty path to 
the cache is specified through OnixS::CME::MDH::HandlerSettings::instrumentCache parameter. 

\section migrate-message-processing Message Processing

One of major improvements done in given release is redesigned message subsystem. 
In previous releases, market data was exposed through the OnixS::CME::MDP3::Message
class representing an unified container of FIX fields. In given release message
subsystem has been redesigned. Now market data messages are exposed to the users
as they are defined in XML-based specification published by CME. Given approach
gives more clarity on data structure and use and increases robustness.

| 3.X Release | 4.X Release |
|-------------|-------------|
| `OnixS::CME::MDP3::Message` | `OnixS::CME::MDH::ChannelReset` | 
| | `OnixS::CME::MDH::AdminLogin` |
| | `OnixS::CME::MDH::AdminLogout` |
| | `OnixS::CME::MDH::InstrumentDefinitionFuture` |
| | `OnixS::CME::MDH::InstrumentDefinitionSpread` |
| | `OnixS::CME::MDH::InstrumentDefinitionOption` |
| | `OnixS::CME::MDH::SecurityStatus` |
| | `OnixS::CME::MDH::IncrementalRefreshBook` |
| | `OnixS::CME::MDH::IncrementalRefreshOrderBook` |
| | `OnixS::CME::MDH::IncrementalRefreshTrade` |
| | `OnixS::CME::MDH::IncrementalRefreshTradeSummary` |
| | `OnixS::CME::MDH::IncrementalRefreshVolume` |
| | `OnixS::CME::MDH::IncrementalRefreshSessionStatistics` |
| | `OnixS::CME::MDH::IncrementalRefreshDailyStatistics` |
| | `OnixS::CME::MDH::IncrementalRefreshLimitsBanding` |
| | `OnixS::CME::MDH::SnapshotFullRefresh` |
| | `OnixS::CME::MDH::SnapshotFullRefreshOrderBook` |
| | `OnixS::CME::MDH::QuoteRequest` |

OnixS::CME::MDH::MarketDataListener as the listener for the received 
market data was enhanced with overloads for each type of SBE message. 

Additionaly, since given release original network packets received on live feeds are exposed to the 
users through OnixS::CME::MDH::MarketDataListener interface as instances of OnixS::CME::MDH::Packet 
class. Correspondently, listener was enhanced with OnixS::CME::MDH::MarketDataListener::onPacket and 
OnixS::CME::MDH::MarketDataListener::onEndOfPacket allowing to determine bounds of packet processing. 

\section migrate-logger Event And Data Logging 

Logging layer was significantly reworked and abstraction of logging service was introduced. Now 
users can implement their logging service including memory-based ones. SDK offers ready-to-use 
implementation for logging events into a file. 

Following examples depict how to enable file-based logging for the Handler in previous and current releases:

\subsection migrate-logger-v3-sample Enabling logging in previous generations of SDK

~~~{.cpp}

HandlerSettings handlerSettings;

handlerSettings.logDirectory("logs");
handlerSettings.logMode(LogModes::Debug);
handlerSettings.advancedLogOptions(AdvancedLogOptions::LogEverything);

Handler handler(handlerSettings);

~~~

\subsection migrate-logger-v4-sample Enabling logging in latest generation of SDK

~~~{.cpp}

HandlerSettings handlerSettings;
..
Handler handler(handlerSettings);

//

FileLoggerSettings loggerSettings;

loggerSettings.filename("LogFile.txt");
loggerSettings.severityLevel(LogSeverity::Debug);

FileLogger logger(loggerSettings);

handler.bindLogger(logger);

~~~

For more information see \ref logging-options.

\section migrate-replay Log File Replay

The behavior of the Handler in case of replaying a log file has been changed. 
In previous releases, the replay was performed asynchronously. When a user invoked 
the OnixS::CME::MDH::Handler::start overload, the Handler spawned a new thread. 
The actual log replay was done in the body of that thread. Therefore, the 
OnixS::CME::MDH::Handler::start overload returned control to its caller as 
soon as a new thread was launched. Also, the end of replay could be detected 
only by using a special listener designed for that purpose. 

In the given major release, log file replay is a synchronous operation. 
Therefore, OnixS::CME::MDH::Handler::replay member does not return unless 
a log file is replayed. The new behavior simplifies user’s interaction with 
the replay and reduces the use of the system resources. 

However, the previous behavior of the replay functionality can be achieved. 
Users may launch additional threads and invoke the OnixS::CME::MDH::Handler::replay 
in the bodies of those threads. The previous behavior is achieved in such way. 

\section migrate-filtering Filtering

Starting from given release, SDK exposes improved filtering to the users. Previously,
market data filtering was managed by set of routines exposed by the OnixS::CME::MDH::Handler
class like `OnixS::CME::MDP3::Handler::addSecurityIdFilter`. Also, there were inconsistency
related with filtering security definitions which consisted in the fact security definitions
were not filtered no matter users were interested in them or not. 

In given release filtering was been redesigned and eliminates existent albiguities and inconsistencies 
available in previous releases. According to new concept, filtering is applied to security-related events 
consolidated into OnixS::CME::MDH::SecurityListener listener. Filtering is not used by the Handler on a 
market data level, therefore members of OnixS::CME::MDH::MarketDataListener are always invoked under 
same conditions and filtering has no influence on their invocation. 

For more information on how security-related events can be filtered, see \ref security-selection.