ARTICLE

A simple MarketPrice object for EMA - Part 2

Olivier Davant

Overview

In this second article I present a simple MarketPrice class that implements the concepts explained in the A simple MarketPrice object for EMA – Part1 article. The MarketPrice class presented here is a component of an abstraction layer built on top of the Enterprise Message API (EMA) Java edition and implemented in the ValueAddObjectsForEMA example library (read the Simplifying Content Access in EMA article to learn more about this set of value add objects).

More specifically, this second part presents:

The basic usage of MarketPrice objects.
An example application that demonstrates the different features exposed by the MarketPrice class.
A command line tool one can use to retrieve and output market prices in a human readable format or in a JSON format. This tool is a concrete example that leverages the MarketPrice class.
Some of the implementation details of the MarketPrice class and of the ValueAddObjectsForEMA example library.

Before you continue reading, I recommend you read the first part of this article and make sure you are familiar with the concepts explained in the 10 important things you need to know before you write a Real Time application article.

Disclaimer

The MarketPrice class and the ValueAddObjectsForEMA example library have been written by Refinitiv for the only purpose of illustrating a series of articles published on the Refinitiv Developer. The MarketPrice class and the ValueAddObjectsForEMA example library have not been tested for usage in production environments. Refinitiv cannot be held responsible for any issues that may happen if these objects or the related source code is used in production or any other client environment.

Content

About the MarketPrice class

How to use MarketPrice objects

Find out more in the example application

Experiment market prices with the ready to use MarketPriceSubscriber command line tool

Design notes and other implementation details

About the MarketPrice class

The MarketPrice class is an abstraction layer implemented on top of the EMA. Its purpose is to simplify the usage of this API for retrieving market price data items (MMT_MARKET_PRICE (6) domain type). The MarketPrice class implements the following features:

Synchronous and asynchronous item subscription
Partial subscription by field names or field IDs (EMA Views)
Item completion detection
Asynchronous notifications for Item completion, Images, Updates and Statuses.
In memory data cache (fields and states)
Random access (by name or by ID) to cached field values and field descriptions (dictionaries)
Partial updates management for partially updatable fields (e.g. ROW80_n fields)
Thread safety

The MarketPrice class and the ValueAddObjectsForEMA example library are not a replacement layer for EMA, but must be used in conjunction with EMA. As you will see many EMA interfaces are used and exposed by the value add objects.

How to use MarketPrice objects

How to build a MarketPrice object for a particular instrument

MarketPrice objects are created using a builder class. This class allows you to set the different properties of a MarketPrice like the instrument name, the subscription mode or the functions that must be called for asynchronous notifications. MarketPrice objects have no setter methods.
Note: As the builder is the only way to set their properties, they can be considered as immutable objects – from the objects creation perspective at least. However, it is important to note that MarketPrice objects are not pure immutables because their logical state changes when they receive EMA events.

The following code snippet builds a MarketPrice for the AIRBUS stock traded on Euronext:

    	
                OmmConsumer ommConsumer = ...
    ...
    MarketPrice theMarketPrice = new MarketPrice.Builder()
                                          .withOmmConsumer(ommConsumer)
                                          .withName("AIR.PA")
                                          .withServiceName("ELEKTRON_DD")
                                          .build();

As you can see, MarketPrice properties are set by calling the different methods of the builder. In the above example these method calls are chained and organized in a block of several lines. This is done that way to ensure a better code readability. Once the properties are set in the builder, the MarketPrice object is created by a simple call of the build() method.
Note: A new object is created each time the build() method is called. Builder properties can be changed between these calls. That way you can use the same builder to build different MarketPrice objects.

Most of the properties are optional except for the OmmConsumer and the MarketPrice name. The OmmConsumer is used by the MarketPrice to send and receive messages from the real time platform. The name is obviously the name to the instrument to open (to subscribe to). If you do not set these properties, the build() method throws an IllegalStateException exception. The other properties have default values. You do not have to set these properties if you are fine with their default values.

Once the object built, nothing special happens. Indeed, at that stage the MarketPrice object is not yet opened. No subscription request has been issued yet to the platform.

Other builder calls are described in the sections below. The complete list is available in the ValueAddObjectForEMA reference guide.

How to open a MarketPrice synchronously?

The MarketPrice opening mode (a.k.a. subscription mode) must be indicated to the builder before the object creation. So, to use the MarketPrice class synchronously you must first create a synchronous MarketPrice object and then call its open() method. Like this:

    	
               MarketPrice theMarketPrice = new MarketPrice.Builder()
                                         .withOmmConsumer(ommConsumer)
                                         .withName("AIR.PA")
                                         .withSynchronousMode()
                                         .build();
   theMarketPrice.open();

It is important to note that for synchronous MarketPrice objects the open() method doesn’t return control to the calling tread before the MarketPrice is complete. This means that this method is blocking and may take a short while before returning. This also means that your application can use the data cached by the MarketPrice (fields and/or state) just after the open() method has returned control to your application thread.

In the above example, OmmConsumer events are supposed to be dispatched from another thread; either by an EMA thread (API_DISPATCH operation model) or by another thread of the application. If in the design of your application OmmConsumer events are dispatched from the current thread, you must call the withSynchronousMode() builder method with the autoDispatch parameter set to true, like this:

    	
                boolean autoDispatch = true;
    MarketPrice theMarketPrice = new MarketPrice.Builder()
                                         .withOmmConsumer(ommConsumer)
                                         .withName("AIR.PA")
                                         .withSynchronousMode(autoDispatch)
                                         .build();
    theMarketPrice.open();

When the autoDispatch parameter is set to true, the open() method dispatches events of the OmmConsumer until the is MarketPrice complete.

Once the MarketPrice is opened, if you indicated an interest for updates and if the events of the OmmConsumer are properly dispatched, the cached image is automatically updated with the latest events received from the real time platform.

How to open a MarketPrice asynchronously?

By default MarketPrice objects use the asynchronous opening mode. So, you don’t need to do anything special to open a MarketPrice asynchronously. Just call the open() method once the object is created. Like this:

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
                                         .withOmmConsumer(ommConsumer)
                                         .withName("AIR.PA")
                                         .build();
    theMarketPrice.open();

It is important to note that when the open() method of an asynchronous MarketPrice object returns, the internal cache is not yet populated. This is because at this stage no message has been received from the platform yet. With the asynchronous mode, the open() method returns with no delay. This means that the getFields(), getField(String), getField(int) and getState() methods will probably return a null value if you call them just after the open() method has returned control to the calling thread.

How to close a MarketPrice?

In order to close a MarketPrice, just call the close() method. This closes the subscription to the instrument.

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
                                         .withOmmConsumer(ommConsumer)
                                         .withName("AIR.PA")
                                         .build();
    theMarketPrice.open();
 ...
    theMarketPrice.close();

Once closed, the MarketPrice stops receiving events from EMA. The cached image and item state are cleared out.

When is my MarketPrice complete?

A MarketPrice is said complete after it received the required elements that allows your application to use it. In other words, it is complete after it received either a first image or a closed status (that could be caused by an error, for example).

You have 3 different ways to know if the MarketPrice is complete:

Either you subscribed with the synchronous mode. In that case the MarkePrice is complete as soon as the open() method returns. Then, you can call the getField(String), getField(int), getFields() or getStatus() methods to retrieve the items fields or the status.
Or you subscribed with the asynchronous mode and registered an OnCompleteFunction. In that case the function is called as soon as the MarketPrice is complete.
Or you subscribed with the asynchronous mode but did not register any OnCompleteFunction. In that case you must poll the isComplete() method to determine if the MarketPrice is complete or not.

The code snippets below illustrate these three different methods:

Synchronous mode

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
                                         .withOmmConsumer(ommConsumer)
                                         .withName("AIR.PA")
                                         .withSynchronousMode()
                                         .build();
    theMarketPrice.open();
    out.println("BID = " + theMarketPrice.getField("BID").value());
    out.println("ASK = " + theMarketPrice.getField("ASK").value());

Asynchronous mode with OnCompleteFunction set

    	
                // Lambda expression that will be called when the MarketPrice is complete
    MarketPrice.OnCompleteFunction printBidAndAsk = (marketPrice) -> 
    {
        out.println("BID = " + marketPrice.getField("BID").value());
        out.println("ASK = " + marketPrice.getField("ASK").value());
    };
        
    MarketPrice theMarketPrice = new MarketPrice.Builder()
        .withOmmConsumer(ommConsumer)
        .withName("EUR=")
        .onComplete(printBidAndAsk)                
        .build();
    theMarketPrice.open();                                    
    ...

Asynchronous mode without OnCompleteFunction

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
        .withOmmConsumer(ommConsumer)
        .withName("EUR=")
        .build();
    theMarketPrice.open();                                    
    do{
        try{
            Thread.sleep(WAITING_LOOP_TIMEOUT_IN_MS);
        } 
        catch (InterruptedException exception) {}
    }while (!theMarketPrice.isComplete());
    out.println("BID = " + theMarketPrice.getField("BID").value());
    out.println("ASK = " + theMarketPrice.getField("ASK").value());

How to retrieve the cached fields?

Once your MarketPrice is complete, it is automatically kept up-to-date with the latest values received from the real time platform (except if you did not register an interest for updates). You can retrieve the MarketPrice cached image at any moment. To this aim you can call either the getFields() method that returns the complete fields list (the image), or the getField(String) to retrieve a specific field by its name, or the getField(int) to retrieve a field by its ID. The following code snippets illustrate these three options:

Full image retrieval

    	
               ... 
Collection<Field> fields = theMarketPrice.getFields(); 
fields.forEach( 
        (field) -> 
            out.println( 
                   field.description().acronym() 
                   + " (" + field.description().fid()+ ") = " + 
                   field.value() 
          ) 
);

Field by name retrieval

    	
                ... 
out.println("BID (22) = " + theMarketPrice.getField("BID").value()); 
out.println("ASK (25) = " + theMarketPrice.getField("ASK").value());

Field by ID retrieval

    	
                 ... 
out.println("BID (22) = " + theMarketPrice.getField(22).value()); 
out.println("ASK (25) = " + theMarketPrice.getField(25).value());

It is important to note that these methods return a null value if the MarketPrice cache has not been populated yet.

How to be notified asynchronously of new images, updates and statuses

If the purpose of your application is to use the MarketPrice real time data as soon as it changes on the platform, then you need to be notified of these changes. To this aim you must indicate to the MarketPrice builder the functions or lambda expressions that you want to be called asynchronously when new images, updates or statuses are received. The following code snippet demonstrates how to do it:

    	
            // Lambda expression that prints an image
    MarketPrice.OnImageFunction printImage = (marketPrice, image, state) -> 
    {
        out.println("New image received.");
        out.println("Image: ");
      image.forEach(
            (field) -> out.println(field)
        );
 out.println("State: " + state);
    };
 
    // Lambda expression that prints an update
    MarketPrice.OnUpdateFunction printUpdate = (marketPrice, update) -> 
    {
        out.println("New update received: ");
        out.println("Update: ");
      update.forEach(
        (field) -> out.println(field)
        );
 out.println("State: " + state);
    };
 
    // Lambda expression that prints a status
    MarketPrice.OnStatusFunction printStatus = (marketPrice, state) -> 
        out.println("New Status received: " + state);
 
    // MarktePrice that uses the lambdas defined above
    MarketPrice theMarketPrice = new MarketPrice.Builder()
        .withOmmConsumer(ommConsumer)
        .withName("EUR=")
        .onImage(printAllFields)  // Indicates that printAllFields must be called on new images
        .onUpdate(printBidAndAsk) // Indicates that printBidAndAsk must be called on new updates
        .onStatus(printStatus)    // Indicates that printStatus must be called on new statuses
        .build();
    theMarketPrice.open();                                    
        ...

In the above example, the printAllFields(), printBidAndAsk() and printStatus() lambdas will respectively be called when new images, updates and statuses are received from the platform.

How to open a MarketPrice in snapshot mode?

If you are only interested by the image of a MarketPrice at a specific moment in time but do not want to receive subsequent images, updates or statuses, you can use the snapshot mode. That way, you only receive the first image of the instrument after open() is called. The MarketPrice will not be maintained up-to-date by other images and updates. Here is how to open a MarketPrice in snapshot mode:

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
        .withOmmConsumer(ommConsumer)
        .withName("EUR=")
        . withUpdates(false)
        .build();
    theMarketPrice.open();  
        ...

How to specify the fields you want to receive?

If you are only interested in a limited list of fields, you have the option to specify these fields to the MarketPrice builder. As a result, the built MarketPrice will only receive these fields. It will also consume less memory and less processing time because it will receive less events and smaller messages from the real time platform.

The following code snippet creates and opens a MarketPrice object for BID and ASK fields only:

    	
                MarketPrice theMarketPrice = new MarketPrice.Builder()
        .withOmmConsumer(ommConsumer)
        .withName("EUR=")
        .withField("BID")
        .withField("ASK")
        .build();
    theMarketPrice.open();

After open() is called the MarketPrice object only receives images and updates for the BID and ASK fields. The cached image is made of these two fields only.

Find out more with the example application

The above section explained the basic usage of the MarketPrice class. If you want to find out more, please refer to the reference guide and the MarketPriceStepByStep example application that comes with the ValueAddObjectsForEMA example library . This application demonstrates the different capabilities implemented by the MarketPrice class in 17 individual steps. Before each step, explanatory text is displayed to explain what will be demonstrated. You are then prompted to press <Enter> to start the step.

The source code of this application is a good resource to understand how to use MarketPrice objects as well as other value add objects (e.g. Dispatcher).

Building and running instructions are provided in the README.md file that comes with the ValueAddObjectsForEMA GitHub project.

Experiment market prices with the ready to use MarketPriceSubscriber command line tool

The MarketPriceSubscriber is a command line tool you can use to retrieve market prices in text or JSON format. This is a good example of a simple but real application that relies on the ValueAddObjectsForEMA example library and the MarketPrice class.

The source code of the tool is provided in the Article.EMA.Java.MarketPriceSubscriber GitHub repository. Building and running instructions are provided in the README.md file of this project.

The tool is also provided as a ready to use binary pack available for download at the bottom of this article.

Design notes and other implementation details

This section contains design notes and other details that should help you to understand, reuse, maintain or enhance the MarketPrice implementation classes provided by the ValueAddObjectsForEMA example library.

General comment

MarketPrice objects and the ValueAddObjectsForEMA example library in general have been designed as a set of objects and interfaces to be used in conjunction with EMA. These objects and interfaces provide a higher level of abstraction where it is needed, but they also rely on existing EMA interfaces and objects as much as possible. No need to reinvent the wheel. For example, MarketPrice images are made of Field objects defined by ValueAddObjectsForEMA example library. However, each Field exposes a description and a value made of interfaces and objects (ema.rdm.DictionaryEntry and ema.access.Data) defined within the EMA space.

objects.marketprice.MarketPrice

This is the interface of MarketPrice objects. This is the main interface used by client applications to manipulate market prices. This interface is implemented by the MarketPriceImpl class that encapsulates all the implementation details with the exception of the builder.

objects.marketprice.MarketPrice.Builder

The MarketPrice builder is the only exposed part of the MarketPrice implementation. This builder is implemented as an inner class of the MarketPrice interface. It contains a very basic logic that mainly consists of:

Holding the different properties of the MarketPrice object to be built
Providing default values for the unset properties
Checking that the mandatory parameters are set before building MarketPrice objects

The builder has been exposed that way, in inner class, to enable simple code writing that clearly links the builder to the interface of the objects it builds. Like this:

    	
                MarketPrice mp = new MarketPrice.Builder()
            ...
        .build();

This makes code writing more elegant but also limits MarketPrices to a single implementation which is not really an issue in our case.

objects.marketprice.MarketPriceImpl

This class implements the MarketPrice interface and contain the main logic of MarketPrice objects:

Interface with EMA
Completion detection
Synchronous mode
Cached image management

This class also relies on the Field interface and FieldImpl class for holding field descriptions, values and managing partial updates.

objects.data.Field

This interface is used to the represent the individual fields of a MarketPrice. A Field exposes a description and a value:

The field description is represented by an ema.rdm.DictionaryEntry that fully describes the field based on the information contained in the fields’ dictionary used by the platform and EMA.
The field value is contained in a sub-type of the ema.access.Data as defined within the EMA space (e.g. OmmDate, OmmReal, OmmInt, OmmRmtes).

objects.data.FieldImpl

This class is the implementation of the Field interface. This class holds the field description, the field value and implements the logic to manage partial updates using the ema.access.RmtesBuffer interface.

This class is used to build the internal representation of the MarketPrice image. To this aim it preserves the Omm.Data received from EMA. This is done by cloning the received Omm.Data in a local and very basic implementation of the Omm.Data sub-types (OmmDateImpl, OmmRealImpl, OmmIntImpl, OmmRmtesImpl, etc). These classes have been re-implemented in the ValueAddObjectsForEMA example librarybecause the EMA implementations cannot be duplicated without an underlying message from the platform.

objects.data.Util

This helper class contains the logic for cloning the Omm.Data received from EMA into their in-memory representation used by MarketPrice images.

SOURCE CODE

A simple MarketPrice object for EMA

Explore all Refinitiv API Samples on GitHub

Articles

Developer Tools

Use Cases

Upcoming Events

Past Events

About Us

A simple MarketPrice object for EMA - Part 2

Overview

Disclaimer

Content

About the MarketPrice class

How to use MarketPrice objects

How to build a MarketPrice object for a particular instrument

How to open a MarketPrice synchronously?

How to open a MarketPrice asynchronously?

How to close a MarketPrice?

When is my MarketPrice complete?

How to retrieve the cached fields?

How to be notified asynchronously of new images, updates and statuses

How to open a MarketPrice in snapshot mode?

How to specify the fields you want to receive?

Find out more with the example application

Experiment market prices with the ready to use MarketPriceSubscriber command line tool

Design notes and other implementation details

General comment

objects.marketprice.MarketPrice

objects.marketprice.MarketPrice.Builder

objects.marketprice.MarketPriceImpl

objects.data.Field

objects.data.FieldImpl

objects.data.Util