Introduction​

The goal of this tutorial is to extend Tutorial 3 to request and retrieve level 1 (MarketPrice) data from the OMM-based data Provider. To support level 1 content, new class modules have been added to this tutorial to enforce a modular environment allowing easier management, and support for additional functionality.

Description

In this tutorial, we introduce two new classes that will both play a role in decoding the level 1 data responses from the OMM-based data Provider.

• basicDictionaryHandler
  Data messages received from the OMM-based Provider are packaged as RWF (Reuters Wire Format) messages. The RWF is a low-level, compact protocol that requires specific decoding in order to be properly interpreted and used within an application. To support this decoding, an application is expected to load a dictionary of field definitions and utilize these definitions, via ETA method calls, to decode RWF messages.
• basicMsgHandler
  The RDM (Reuters Domain Messages) defines multiple message models that are typically used within a Consumer application. Within this tutorial, we will be requesting for the level 1 MarketPrice message model which contains a well-defined message structure. Because our RDM models utilize well-defined structures such as FieldLists, Maps, etc., our handler only needs to understand the structure to properly process the message.

Implementation Overview - Preparing, requesting, and parsing level 1 data

Prior to requesting for level 1 data, we must ensure we can properly decode the RWF messages provided by the OMM-based Provider by first loading a dictionary. As previously mentioned, the dictionary represents the field definitions. Once loaded, we can safely interpret and decode the fields of data we receive upon market data updates from the Provider.

Dictionary

A Consumer application has two choices to load a dictionary. Either choice has its advantages but once a dictionary is loaded, we can achieve the functionality of decoding RWF messages.  The two choices are:

• Loading the dictionary from local files
• Downloading the dictionary from the OMM-based Provider

Refer to the Load or Download Necessary Dictionary Information section defined within the Developers Guide for more information. 

The following code snippet outlines the logic to handle both mechanisms of loading a dictionary:

From the above code segment, we instruct the reactor to determine how we want to load the data dictionary.  

Loading the dictionary from local files

The above method call loadLocalDictionary will return a value of true if the dictionary files are available within the local file system.  If so, this method will load the dictionary files and the enumeration value NONE is assigned to the dictionaryDownloadMode which instructs the reactor to not request the dictionary from the Provider. This logic will be demonstrated within ETA Tutorial 5 - Retrieving and decoding level 2 content.

Note: the tutorial will be looking for the local dictionary files within the current directory where you run the application.

Downloading the dictionary from the Provider

The above method call loadLocalDictionary will return a value of false if the dictionary files are not available within the local file system. As a result, the enumeration value FIRST_AVAILABLE is assigned to the dictionaryDownloadMode which instructs the reactor to request the dictionary from the Provider. This logic will be demonstrated in this tutorial.

Note: The dictionary download procedure is mostly handled via the ETA Reactor. In this case, the dictionary download is completely dependent on the success of the Directory response we utilized in ETA Tutorial 3 - Establishing a session with a Provider.  The Directory response contains the details of the dictionary details sent down to the Provider.

As outlined above, the decision to download or load locally is driven by the loadLocalDictionary method defined within basicDictionaryHandler.java.

There are 2 local files that make up the dictionary, i.e.

• RDMFieldDictionary
  Contains all the known fields, types and sizes required to decode.
• enumtype.def
  Contains enumeration definitions for those fields with an Enum type defined withing the RDMFieldDictionary file.

If the local dictionary files are available, the ETA methods loadFieldDictionary and loadEnumTypeDictionary will perform the action of loading the dictionary. If no local dictionaries are available, we return no success, or false, and within the calling method, we instruct the ETA Reactor to attempt to download from the OMM-based Provider.

In the event where we instruct the reactor to fetch the dictionary files from the Provider, this will result in dictionary events.  These events define the details for the complete dictionary downloaded from the Provider.  Upon a dictionary event, we handle the event processing within the following callback:

The callback above instructs a dictionary processing action via the processDictionaryResponse method. Although we could have housed the entire processing within the basicConsumer.java module, the intention was to offload the functionality into the separate class basicDictionaryHandler for purposes of modularity.

While the processing details are important, the codebase and the decoding of dictionary definition elements are beyond the scope of this tutorial. The basic processing was derived from the ValueAdd example consumer which will act as a good reference for additional processing requirements and explanation.

Level 1 data - MarketPrice

Once we have established our dictionary, we are ready to request for data, in this example for instrument code BB.TO (Blackberry on the Toronto exchange). In the first tutorial, we had setup our series of event callbacks based on the ConsumerCallback interface requirements. Now that we plan on requesting for data, we can put in place the processing logic required to handle data events within these callbacks. At startup, the ValueAdd components will run through a cycle to determine when we are ready to request for data from our Provider. Once the consumer role successfully connects, establishes a session and loads a dictionary, we will be presented with a CHANNEL_READY event within our reactorChannelEventCallback:

Within the existing callback reactorChannelEventCallback, we are using the CHANNEL_READY event to trigger the action of requesting for our data. The request of data in our example is to open a subscription or specify a streaming request. A streaming request will result in an initial image (REFRESH) and optionally followed by 1 or more update (UPDATE) messages, depending on the time of day and the current market conditions. Based on the REFRESH event, the initial image contains the latest up-to-date values known for the specified item. The updates represent only those fields that result from changes within the market.

To issue our streaming request, we are calling the newly defined method sendItemRequest. Defined within the file basicMsgHandler.java, this method is designed as a generic item request function that requires 3 key pieces of data, i.e.

• itemNames
  A list of data items to request. Eg: BB.TO (Blackberry on the Toronto exchange)
• serviceInfo
  The serviceInfo corresponds to a specific entity contained within the Directory Service received from the Provider.  While the entity contains many service attributes such as the name and ID, it is the ETA libraries that require this ID on all subsequent requests to that service.  The serviceInfo name was utilized to identify which service, ELEKTRON_AD, we are interested in.
• domainType
  The RDM domain type. In this tutorial we request for the level 1 data MARKET_PRICE but future tutorials will utilize additional models. The RDM domain types supported by the Provider were provided within the Directory response we covered within Tutorial 3.

To process our message response:

The basicMsgHandler.java file contains many processing functions to manage message encoding, decoding and parsing. In the above code segment, we are executing the generalMsgProcessing method which is designed to handle the decoding of many message types. As mentioned in the Description section above, the message processing within this application intends to keep processing generic based on the structure of the messages, i.e. FieldLists, Maps, etc. as opposed to the model type of the message, i.e. MarketPrice, Symbol List, MarketByPrice, etc. In doing so, we can simplify the processing and reduce the codebase to process multiple message models. The following function outlines the general structure:

In the code segment above, our level 1 Market Price data is delivered within a FIELD_LIST message structure. As such, we walk through the list and extract the elements and decode the fields, using our loaded dictionary. The fields are simply echoed to the display to verify processing. As we encounter new message structures, we include that logic in the above to expand the processing. While this processing is important, it is beyond the scope of this tutorial. The basic processing was derived from the ValueAdd example consumer which will act as a good reference for additional processing requirements.

Setup and Configuration

Refer to Setup and Configuration section within the ETA Tutorial 2 - Establishing a connection to a Provider prior to building and running this tutorial.

Build and run

Refer to the Build and run section within the ETA Tutorial 1 - Creating a starter consumer application for instructions to successfully execute this tutorial.

Eg (Windows):

> buildConsumer 4
> runConsumer 4

In our execution, we are downloading the dictionaries from the OMM-based Provider. You can see the receipt of the dictionaries; our request to subscribe to the item BB.TO and the corresponding response.

Note: We issued a streaming request which will result in an initial refresh followed by updates showing change based on market events.

References

For more information, refer to the ETA Java Development Guides.