Onix Solutions Logo

ICE iMpact Multicast Price Feed Handler — Programming Guide

Version 1.15.0

TOC

Introduction

The Onix Solutions Java ICE iMpact Multicast Price Feed Handler is a Java library that provides an access to the ICE iMpact market data using multicast feed protocol. It provides a high-level Java API that enables developers to efficiently build and maintain applications without spending time and effort supporting the raw low level API protocol.

Below are the key features of the ICE iMpact Market Data Feed Handler:

Note
To understand the core concepts of the ICE iMpact Market Data System, we recommend reading the "ICE iMpact Multicast Feed Technical Specification" documentation before reading this Guide. Also, you should review the source code of the sample project which is included as a part of the library distribution package

System Requirements

Getting Started

The typical usage of the Handler is as follows:

Advanced Programming

Handler State Transition Graph

The following diagram illustrates how the Handler can change its states.

Handler State Graph

Connectivity Configuration Structure

All Handler options are combined in the biz.onixs.ice.impact.handler.HandlerOptions class that contains a path to the connectivity configuration file. This file contains definitions of multicast groups and network addresses of corresponding servers to which the Handler has to connect so as to receive market data. There are three major sections which make up the configuration: the TCP connection information, Multicast groups and Market types.

TCP Connection Information

TCP connection information section defines the attributes of the remote system to which a server connects to request primary information like product definitions for selected markets. This section also defines logon information like username and password which are mandatory for the Handler connection.
Typical TCP connection information section looks as follows:
<tcp ip="63.247.113.163" port="3000" userName="username from ICE" password="Password from ICE"/>
Values of IP and port attributes define the connection to remote system. The userName and password are the logon-related attributes.

Switch off order book processing

The order book processing is disabled if OrderBookListener is not registered via biz.onixs.ice.impact.handler.Handler#registerOrderBookListener. Otherwise it is enabled.

Incremental updates processing

The Handler provides the ability to receive and process order book incremental updates.

To process incremental updates of the Full Order Depth (FOD) Book, a client should implement an interface of FullOrderDepthBookChangeListener and register a listener using Handler#registerFullOrderDepthBookChangeListener.

To process incremental updates of the Price Level (PL) Book, a client should implement an interface of PriceLevelBookChangeListener and register a listener using Handler#registerPriceLevelBookChangeListener.

The table below shows the BookChangeType enum values and corresponding ICE iMpact messages for FOD with their short description.

BookChangeType Full Order Depth message Description
UNKNOWN n\a Default value
SNAPSHOT Market Snapshot Order Message This message is for orders in snapshot only. It is different from the order message for incremental updates.
ADD Add/Modify Order Message Both add and modify order notifications use one message format. A client should add the order to book if it is not already there. Otherwise, just overwrite the existing order.
CHANGE Add/Modify Order Message Both add and modify order notifications use one message format. A client should add the order to book if it is not already there. Otherwise, just overwrite the existing order.
REMOVE Delete Order Message Upon receipt of this message, a client should remove the order from it local book. Under certain scenarios, the message could be sent from the backend with an OrderID that does not exist on the client's book, in which case the client can just ignore it.

The table below shows the BookChangeType enum values ​​and corresponding ICE iMpact messages for PL with their short description.

BookChangeType Price Level message Description
UNKNOWN n\a Default value
SNAPSHOT Market Snapshot Price Level Message This message is for price level in snapshot only. For a given market, these messages follow right after Market Snapshot Message.
ADD Add Price Level Message Upon receipt of this message, a client should add/insert a price level at the specified position in the book for the given market, and push down the price levels that were previously at or below that position. After that, if the total number of levels exceeds what is supported (e.g. Top 5), the client should remove the bottom level. The system doesn't send out Delete Price Level message in that scenario.
CHANGE Change Price Level Message Upon receipt of this message, a client should update the price level at the specified position in its book for the given market.
REMOVE Delete Price Level Message Upon receipt of this message, a client should remove the price level at the specified position in its book for the given market. And it should pull up all the levels that were below that position.

Feed identification

For each subscription the Handler starts two feeds - a snapshot and a live. This pair of feeds has a unique integer identifier - feedId. Some messages (like a BundleMarkerMessage) can be identified only by feedId. To get feedId, a client should implement the FeedStateChangeListener interface. If the client wants to know that the message is received by some feedId, it should check MessageInfo#getFeedId().

Controlling Logging

By default, the Handler logs all important aspects of its activity while processing market data. The SLF4J (Simple Logging Facade for Java) is used internally by the Handler. The SLF4J detects and uses the concrete logging implementation configured by user. By default, the Logback logging implementation is recommended.

The Logback (or any other logging implementation) must be configured at the beginning of the application. The examples of Logback configuration can be found in the Handler samples. The details of Logback configuration can be found here.

Listening to Handler's events

Events in the Handler

There're five major events exposed by the Handler:

Once the Handler is started, it listens to a market data from the network, processes it (decodes messages, validates message order, updates order books) and invokes the client's code for further processing.

The Handler processes market data asynchronously and uses a concept of events and event listeners to notify the client code about particular activity such as the reception of security definition or direct book update.

Listening for a particular Event

For each event like the Error Occurred the Handler provides an interface like biz.onixs.ice.impact.handler.event.ErrorListener. The client's code must implement this interface to be able to handle events of a particular type. The Handler also exposes a member like a biz.onixs.ice.impact.handler.Handler#registerErrorListener which allows to associate an instance of the event handler with a appropriate event in bounds of a particular instance of the biz.onixs.ice.impact.handler.Handler class.

Note
Associating a listener for a particular event with an instance of the biz.onixs.ice.impact.handler.Handler class must be performed while the Handler is in stopped stated. Once the Handler is started, the changing of listener-event associations is not allowed, because it may lead to unpredictable behavior as well as cause unexpected errors.

An associating event listener with an instance of the biz.onixs.ice.impact.handler.Handler class is also called subscribing to an event.

All listener interfaces are in the biz.onixs.ice.impact.handler.event namespace.

Event Listener interface to be implemented Handler member to register listener Description
Futures/OTC Product Definition Received FuturesProductDefinitionListener registerFuturesProductDefinitionListener Fired by the Handler when subscription is started. The Handler calls an associated listener (an event handler) for each product definition it receives. Invocation of the event handler is performed in the same thread in which the Handler#start member was called. Once the subscription is successfully started, the event of this type will not be fired for subscribed markets any more (until the next start).
Strip Info Received StripInfoListener registerStripInfoListener Fired by the Handler when subscription is started. The Handler calls an associated listener (an event handler) for each strip info messages it receives. Invocation of the event handler is performed in the different threads.
Options Product Definition Received OptionsProductDefinitionListener registerOptionsProductDefinitionListener Fired by the Handler when subscription is started. The Handler calls an associated listener (an event handler) for each product definition it receives. Invocation of the event handler is performed in the same thread in which Handler#start member was called. Once the subscription is successfully started, the event of this type will not be fired for subscribed markets any more (until the next start).
Options Strategy Definition Received OptionsStrategyDefinitionListener registerOptionsStrategyDefinitionListener Fired by the Handler when subscription is started. The Handler calls an associated listener (an event handler) for each product definition it receives. Invocation of the event handler is performed in the same thread in which Handler#start member was called. Once the subscription is successfully started, the event of this type will not be fired for subscribed markets any more (until the next start).
Order Book Changed OrderBookListener registerOrderBookListener Fired by the Handler when order book is changed. Invocation of the event handler is performed in different threads.
Price Level Book Change Received PriceLevelBookChangeListener registerPriceLevelBookChangeListener Fired by the Handler when PL order book change is received. Invocation of the event handler is performed in different threads.
Full Order Depth Book Change Received FullOrderDepthBookChangeListener registerFullOrderDepthBookChangeListener Fired by the Handler when FOD order book change is received. Invocation of the event handler is performed in different threads.
Market State Changed MarketStateListener registerMarketStateListener Fired by the Handler when market state is changed. Invocation of the event handler is performed in different threads.
Trade Occurred TradeListener registerTradeListener Fired by the Handler when trade occurred. Invocation of the event handler is performed in different threads.
End of Day Market Summary Message Received EndOfDayMarketSummaryListener registerEndOfDayMarketSummaryListener Fired by the Handler when End of Day Market Summary message is received. Invocation of the event handler is performed in different threads.
RFQ Message Received RfqListener registerRfqListener Fired by the Handler when RFQ message is received. Invocation of the event handler is performed in different threads.
Interval Price Limit Notification Message Received IntervalPriceLimitNotificationListener registerIntervalPriceLimitNotificationListener Fired by the Handler when IPL Notification message is received. Invocation of the event handler is performed in different threads.
System Text Message Received SystemTextListener registerSystemTextListener Fired by the Handler when System Text message is received. Invocation of the event handler is performed in different threads.
Handler State Changed HandlerStateListener registerHandlerStateListener Fired by the Handler when it's state is changed. Invocation of the event handler is performed in different threads.
Error Occured ErrorListener registerErrorListener Fired by the Handler when error occurred. Invocation of the event handler is performed in different threads.
Warning Occured WarningListener registerWarningListener Fired by the Handler when warning occurred. Invocation of the event handler is performed in different threads.
Log-replay Error Occured LogReplayListener registerLogReplayListener Fired by the Handler when log-replay error occurred. Invocation of the event handler is performed in different threads.
Log-replay Finished LogReplayListener registerLogReplayListener Fired by the Handler when replay log is finished. Invocation of the event handler is performed in different threads.

Example

The following sample demonstrates how to listen to notifications about security definition receipt.
public class MyListener implements FuturesProductDefinitionListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyListener.class);

    public void onFuturesProductDefinition(FuturesProductDefinitionEventArgs args) {
        LOG.debug("onFuturesProductDefinition(): {}", args);
    }
}

public class Sample {
    private void run() throws Exception {
      final HandlerOptions handlerOptions = new HandlerOptions();
        final Handler handler = new Handler(handlerOptions);
        // ...
        final MyListener listener = new MyListener();
        handler.registerFuturesProductDefinitionListener(listener);
    }
}

Error Handling

Error Handling Concept

Being a Java library, the Handler uses exceptions to report errors occurred while performing certain action. For example, the Handler will raise a regular exception to report the inability to find a current license for the product. However, the Handler processes market data asynchronously therefore is not able to report any further errors after market data processing is started. For this reason, the Handler exposes the biz.onixs.ice.impact.handler.event.ErrorListener interface and the biz.onixs.ice.impact.handler.Handler#registerErrorListener member to be able to subscribe to and handle errors.

Once an instance of the biz.onixs.ice.impact.handler.event.ErrorListener is assigned to the Handler, it will invoke the biz.onixs.ice.impact.handler.event.ErrorListener#onError member each time error occurs. The biz.onixs.ice.impact.handler.event.ErrorListener#onError member has several incoming parameters one of which defines a human-readable explanation (description) of the error.

An important aspect of the Handler behavior is that in normal use there is nothing special required to handle errors. In particular, once the subscription to market data is successfully started, the Handler will process incoming market data and handle all recovery failures without any additional user actions beung required. This means that there is no need to restart a subscription for market data manually as the Handler recovery logic is designed for optimal recovery and will address non-fatal errors. Also, the Handler performs recovering from errors in the optimal way. For example, in a case of network-related issues, the Handler will rebuild only those books and market states which are based on market data from a problematic multicast feed channel. It will not invalidate and rebuild entire subscription for non-impacted channels.

Example

The following sample demonstrates how to receive error notifications.

public class MyListener implements ErrorListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyListener.class);

    public void onError(ErrorEventArgs args) {
        LOG.debug("onError(): {}", args);
    }
}

public class Sample {
    private void run() throws Exception {
    final HandlerOptions handlerOptions = new HandlerOptions();
        final Handler handler = new Handler(handlerOptions);
        // ...
        final MyListener listener = new MyListener();
        handler.registerErrorListener(listener);
    }
}

FAQ

What's the difference between "Book Changed" and "Book Change Received" events?

If you subscribe to Order Book Changed, you will always have a consistent book. Price Level Book Change Received and Full Order Depth Book Change Received callbacks are designed for those who want to build and maintain books by themselves. Order Book Changed is an elementary action over the order book. As a rule there are multiple changes inside single snapshot and/or incremental refresh. For this reason, a book may not be valid between two changes. Only when all the changes are processed from the single network data (message like a snapshot and incremental refresh), the book is considered as valid. Book Change Received callbacks are called exactly at a time when all changes are processed and a book appears to be valid and up-to-date.


© Onix Solutions