Books Building Bricks

As it was said in previous topic, Handler builds and maintains books for each security by itself and notifies client code once book update takes place.

Sometimes there's a need to build and maintain books by own forces (for example, if there's no need in information of the lowest price-levels). For this purpose, Handler provides advanced events which contain detailed information about the changes needed to be applied to a book to bring it into an actual state.

To get notified about detailed changes into a direct book for a particular security, implement OnixS::CME::MarketData::DirectBookChangeListener interface and register it in the Handler via OnixS::CME::MarketData::Handler::registerDirectBookChangeListener member.

To get notified about detailed changes into an implied book for a particular security, implement OnixS::CME::MarketData::ImpliedBookChangeListener interface and register it in the Handler via OnixS::CME::MarketData::Handler::registerImpliedBookChangeListener member.

Both events expose detailed information of elementary change into book's bids and asks. For more details see the description and members of OnixS::CME::MarketData::DirectBookChange class which encapsulates a concept of a change for direct book and OnixS::CME::MarketData::ImpliedBookChange for implied book change respectively.

Note: There's no ability to listen to changes for consolidated books because these books are derived from direct and implied ones.

Book Change Machinery and Relation with 'Book Updated' Event

Book Updated and Book Changed events are not mutually exclusive ones. It's possible to subscribe to both types of events. Book changes represent more elementary (atomic) updates of a book. Therefore, Book Changed events may occur more frequently in compare to Book Updated event occasions. In fact, series of Book Changed events occur before single occasion of Book Updated event.

When order book is delivered via Book Updated callbacks, it's always in a valid and up-to-date state. In contrast, book change is an elementary action over the book and usually there're multiple changes inside single snapshot and/or incremental refresh. For this reason, book may not be in a valid state between two changes. Only when all the changes are processed from the single network packet (a message like snapshot and incremental refresh), book can be considered as valid. Book Updated callbacks are called exactly at a time when all changes are processed and book appears to be valid and up-to-date.

To build an order book properly, it's necessary also to listen to Hander State changes. When the Handler falls into OnixS::CME::MarketData::BooksResynchronizationStarted all books must be empty. Afterwards, changes reported via Book Changed callbacks must be applied to build a correct order book. An important aspect is that Handler doesn't differ changes from snapshots and incremental refreshes. From the API perspective all the changes reported through callbacks are of same structure. To detect the source of a change (e.g. snapshot and/or incremental refresh) as well as to determine the bounds of changes transaction it's necessary to subscribe to Message Processing events (Raw Market Data Processing).

Note: Handler exposes additional members in listening interfaces like OnixS::CME::MarketData::DirectBookChangeListener::onDirectBooksReset and . These members can be used to reset all books instead of using Handler state listening.

Checking Whether Books Are Up To Date

Due to multicast unreliability network data delivery may be delayed or completely lost. If the Handler detects data absence for a certain period of time, it will raise new event (like OnixS::CME::MarketData::DirectBookChangeListener::onDirectBookChangesOutOfDate) which will temporarily invalidate data stored in all order books. Since the moment of event invocation it's reasonable to consider all information in all order books as outdated. Once data delivery will be restored, valid changes will be provided through appropriate callbacks like OnixS::CME::MarketData::DirectBookChangeListener::onDirectBookChange.