EMA Consumer - Creating a barebones EMA consumer application

Download tutorial source code

Click here to download
Last update Sept 2021
Environment Windows, Linux
Compilers JDK 1.7 or greater
Prerequisite Quick Start Guides

Introduction

The goal of this tutorial is to define a basic EMA shell interface outlining the core structure to consume real-time market data. Based on this shell interface, we will walk through the general steps within subsequent tutorials to demonstrate the ability to request market data and to process and parse the real-time responses. To support these goals, we must first establish an appropriate build environment to successfully build and run our series of tutorials.

Description

For these tutorials, it is helpful to familiarize yourself with the contents of the EMA package. The EMA components are packaged as part of the Real-Time SDK stack providing ease-of-use capabilities with a number of value-added features simplifying application development.  To demonstrate this, EMA includes a number of examples focusing on multiple capabilities geared towards simplicity. These tutorials are based on specific features related to the streaming of market data items.

Tutorial Steps

The following steps will outline how to define a build environment, implement a shell interface that defines the structure of a basic EMA Consumer, build and run the example successfully.  Refer to the Enterprise Message API Consumer Architecture section defined within the EMA Developers' Guide for more details.

Establish an EMA build environment

The series of tutorials come packaged with 2 convenient scripts: buildConsumer and runConsumer - see Build and Run below for more details. Because EMA can be installed anywhere within your environment, our build and run scripts make an assumption about how to resolve the location of the JAR packages. While there are multiple ways to configure the setup, this project assumes the following:

  • Real-Time SDK for Java Home directory
    The environment variable RTSDK_JAVA_HOME is used within the build and run scripts to resolve the location of your Real-Time SDK installation. Defined for both the Windows and Linux scripts, this will allow developers to easily copy/duplicate projects to other members without having to re-define directory locations within their own projects. Eg: /home/RTSDK-2.2.0.L1.java.rrg
  • Java build environment
    The environment variable JAVA_HOME is used within the build and run scripts to resolve the location of your Java environment required to compile and run the tutorials.

Within both the buildConsumer and runConsumer scripts, you will need to also set the VERSION variable defined at the top of the file.  The VERSION details can be found within the RTSDK_JAVA_HOME/Java/Ema/Readme.md file.  The VERSION details are part of the Library Name (Eg: ema-3.6.2.0.jar) defined within the EMA Java Library and Version Information section.

Eg: VERSION=3.6.2.0

Alternatively, you can modify the scripts to refer to your installation if you choose not to define environment variables.  The scripts refer to these references at the top of the files.  Once set up, future tutorials will work without further configuration.

 

Implementation Overview - Shell code for EMA setup

The basic shell utilizes a single source file basicConsumer.java containing the basicConsumer class.  EMA utilizes an event-driven, asynchronous model when communicating with a streaming server. To support this event-driven communication, consumer applications must define a class that implements the OmmConsumerClient EMA interface. This interface declares a number of methods, or callbacks used to handle the different types of communication events coming from the streaming server.

At this stage of the tutorial, the basicConsumer class, is just a shell framework that defines empty callback methods. They will be implemented in subsequent tutorials:

    	
            
public class basicConsumer implements OmmConsumerClient


{


 //*************************************************************************************************


 // Callback methods required by the OmmConsumerClient Interface.


 //


 // The following methods allow us to capture realtime events such as status and data events.  The


 // relevant events will be implemented and described in subsequent tutorials.


 //*************************************************************************************************


 public void onRefreshMsg(RefreshMsg refreshMsg, OmmConsumerEvent event){}


 public void onUpdateMsg(UpdateMsg updateMsg, OmmConsumerEvent event){}


 public void onStatusMsg(StatusMsg statusMsg, OmmConsumerEvent event){} 


public void onAllMsg(Msg msg, OmmConsumerEvent consumerEvent){}


 public void onAckMsg(AckMsg ackMsg, OmmConsumerEvent consumerEvent){}


 public void onGenericMsg(GenericMsg genericMsg, OmmConsumerEvent consumerEvent){}


   


    ...


}

The above structure outlines the 6 mandatory callbacks required by the OmmConsumerClient interface. Each callback will be described in subsequent tutorials but all serve the purpose of capturing real-time events such as changes in the market, based on the requested data of interest. 

 

Build and run

The package includes convenient scripts to build and run the tutorials.

For this series of tutorials:

To Build a specific tutorial:

  • Windows: 
    • > buildConsumer.bat [<1|2|3|4|5>] 
  • Linux
    • > sh buildConsumer.ksh [<1|2|3|4|5>]
    	
            
Building tutorial 1...


 


Done.

To Run a specific tutorial:

  • Windows
    • > runConsumer.bat <1|2|3|4|5> [connection parameters]
  • Linux
    • > sh runConsumer.ksh <1|2|3|4|5> [connection parameters]
    	
            
# For example, on Windows:


 


> runConsumer 1


Running tutorial 1...


Processing complete

Running this tutorial will simply echo a start and complete message indicating success.  

In subsequent tutorials, we set up an EMA Consumer to allow us to request a market data instrument and display the results and build on the basics of adding additional functionality. 

Depending on your access, whether you plan to retrieve streaming content from a deployed RTDS or content from the cloud via Real-Time -- Optimized, the run script will support the necessary parameters to connect and access streaming data.  Aside from this shell tutorial, each subsequent example will support required parameters to choose where you wish to connect and other required credentials to access data.  To understand the required parameters for tutorials 2 to 5, execute the following:

    	
            
# For example, on Windows


 


> runConsumer 2


 

The listing provides the available command-line parameters, depending on how you wish to access, including the default values, in square brackets, for some of them.  You can refer to subsequent tutorials demonstrating usage.

References

To learn more about EMA please refer to the