Elektron SDK - Java

API Family: Elektron

Elektron Message API Java Quick Start - To be deleted

Last update July 2016
Environment Windows, Linux
Compilers JDK 1.7 or greater
Prerequisite Access to an existing TREP or Elektron platform to retrieve content

Introduction

The goal of this Getting Started tutorial is to download the Elektron Message API (EMA) for Java, build and run an example application that retrieves content from an existing Enterprise Platform (TREP) or Elektron environment.

Description

In this tutorial, we will cover the following areas:

Download the EMA package

The EMA package is included as part of the Elektron SDK bundle. To access this bundle, ensure you are logged in and granted access to download the Elektron SDK.  Once logged in, navigate to the Elektron SDK - Java API page within the Developer Portal. Under the Downloads tab, choose the latest version of the Elektron SDK - Java, download and uncompress the bundle to a directory of your choosing.

Review the package

Within the main Elektron SDK bundle, navigate to the Ema subfolder.  Within this folder contains the Src/examples sub-directory where we will find a number of examples within the java subfolder demonstrating EMA functionality.



The samples are neatly organized into different directories in order of increasing complexity. For our purposes, we will be building the simplest example, example100_MarketPrice_Streaming, demonstrating the retrieval and display of realtime market data.

Setup and Configuration

Before we build and run our example, we must properly configure our environment to successfully connect and retrieve data. The EMA examples directory comes packaged with the run scripts example100_MarketPrice_Streaming.bat and example100_MarketPrice_Streaming.ksh. To compile this example, you can create you own build instructions by utilizing the configuration details within these run scripts.  Alternatively, we've included a convenient build script for your use.

All scripts utilize an environment variable called JAVA_HOME representing your Java development environment. You can either create this environment variable or simply modify the scripts to refer to your java environment.

To successfully run the example, we must be able to connect into a Refinitiv Market Data system. Your market data administrator can provide the necessary connection details for your environment.  To set this up, within the examples sub-directory, you will need to modify the Consumer.java within the example100_MarketPrice_Streaming folder:

 The Consumer.java source file contains the following hard-coded details that may need modifications for your setup:

...

try
{
	AppClient appClient = new AppClient();
			
	OmmConsumerConfig config = EmaFactory.createOmmConsumerConfig();
			
	consumer  = EmaFactory.createOmmConsumer(config.host("localhost:14002").username("user"));
			
	ReqMsg reqMsg = EmaFactory.createReqMsg();
			
	consumer.registerClient(reqMsg.serviceName("DIRECT_FEED").name("IBM.N"), appClient);
			
	Thread.sleep(60000);			// API calls onRefreshMsg(), onUpdateMsg() and onStatusMsg()
} 

...

There are key pieces of data within the above code segment that may need to be modified in order for you to successfully execute the example. Your market data administrator can provide connection details about the server hostname and RSSL port, presently set to localhost:14002.  In addition, you would likely need to set the Service Name, presently set to DIRECT_FEED and a DACS Username required to entitle you to request for market data.

Build and run the example

Once you have setup and configured your environment, you can build your example. Note: we are using the convenient build scripts provided which are copied to the same directory as the run scripts, i.e. Src/examples. To build:

  • > build_example100__MarketPrice__Streaming.bat  (Windows)
  • > sh build_example100__MarketPrice__Streaming.ksh  (Linux)

To run the example, execute the packaged scripts:

  • > example100__MarketPrice__Streaming.bat  (Windows)
  • > sh example100__MarketPrice__Streaming.ksh  (Linux)

Upon execution, we are presented with some initial connection results followed by our initial image called a RefreshMsg. The RefreshMsg or initial image contains all fields for the requested instrument representing the latest up-to-date market values. Following this image, we will begin to see UpdateMsgs or realtime updates reflecting changes in the market.

The example application will automatically exit after ~1 minute.  Alternatively, you can (Ctrl+C) to exit at any time.


INFO: loggerMsg
    ClientName: EmaConfig
    Severity: Info
    Text:    reading configuration file [EmaConfig.xml] from [c:\Users\u8007876\Downloads\ema\Java\Elektron-SDK1
amples]
loggerMsgEnd


Jun 23, 2016 12:29:25 PM com.thomsonreuters.ema.access.ChannelCallbackClient reactorChannelEventCallback
INFO: loggerMsg
    ClientName: ChannelCallbackClient
    Severity: Info
    Text:    Received ChannelUp event on channel Channel_1
        Consumer Name Consumer_1_1
loggerMsgEnd


RefreshMsg
    streamId="5"
    domain="MarketPrice Domain"
    solicited
    RefreshComplete
    state="Open / Ok / None / 'All is well'"
    itemGroup="00 05"
    permissionData="03 01 64 62 c0"
    name="IBM.N"
    nameType="1"
    serviceId="356"
    serviceName="ELEKTRON_AD"
    Payload dataType="FieldList"
        FieldList FieldListNum="79" DictionaryId="1"
            FieldEntry fid="1" name="PROD_PERM" dataType="UInt" value="62"
            FieldEntry fid="2" name="RDNDISPLAY" dataType="UInt" value="64"
            FieldEntry fid="3" name="DSPLY_NAME" dataType="Rmtes" value="INTL BUS MACHINE"
            FieldEntry fid="4" name="RDN_EXCHID" dataType="Enum" value="2"
            FieldEntry fid="6" name="TRDPRC_1" dataType="Real" value="154.38"
            FieldEntry fid="7" name="TRDPRC_2" dataType="Real" value="154.38"
            FieldEntry fid="8" name="TRDPRC_3" dataType="Real" value="154.39"
            FieldEntry fid="9" name="TRDPRC_4" dataType="Real" value="154.39"
            FieldEntry fid="10" name="TRDPRC_5" dataType="Real" value="154.4"
            FieldEntry fid="11" name="NETCHNG_1" dataType="Real" value="1.46"
            FieldEntry fid="12" name="HIGH_1" dataType="Real" value="154.44"
            FieldEntry fid="13" name="LOW_1" dataType="Real" value="152.61"
            FieldEntry fid="14" name="PRCTCK_1" dataType="Enum" value="2"
            FieldEntry fid="15" name="CURRENCY" dataType="Enum" value="840"
            FieldEntry fid="16" name="TRADE_DATE" dataType="Date" value="23 JUN 2016 "
            FieldEntry fid="18" name="TRDTIM_1" dataType="Time" value="16:28:00:000:000:000"
            FieldEntry fid="19" name="OPEN_PRC" dataType="Real" value="153.45"
            FieldEntry fid="21" name="HST_CLOSE" dataType="Real" value="152.92"
            FieldEntry fid="22" name="BID" dataType="Real" value="154.39"
            FieldEntry fid="23" name="BID_1" dataType="Real" value="154.39"
            FieldEntry fid="24" name="BID_2" dataType="Real" value="154.39"
            FieldEntry fid="25" name="ASK" dataType="Real" value="154.42"
            FieldEntry fid="26" name="ASK_1" dataType="Real" value="154.42"
            FieldEntry fid="27" name="ASK_2" dataType="Real" value="154.42"
            FieldEntry fid="28" name="NEWS" dataType="Rmtes" value="YYYY"
            FieldEntry fid="29" name="NEWS_TIME" dataType="Time" value="13:00:06:000:000:000"
            FieldEntry fid="30" name="BIDSIZE" dataType="Real" value="2.0"
            FieldEntry fid="31" name="ASKSIZE" dataType="Real" value="1.0"
            FieldEntry fid="32" name="ACVOL_1" dataType="Real" value="386398.0"
            FieldEntry fid="34" name="EARNINGS" dataType="Real" value="13.2768"
            FieldEntry fid="35" name="YIELD" dataType="Real" value="3.662"
            FieldEntry fid="36" name="PERATIO" dataType="Real" value="11.5178"
            
			...
			
            FieldEntry fid="32741" name="TRNOVR_UNS" dataType="Real" value="5.9310904866E7"
            FieldEntry fid="32743" name="ACVOL_UNS" dataType="UInt" value="386398"
        FieldListEnd
    PayloadEnd
RefreshMsgEnd

UpdateMsg
    streamId="5"
    domain="MarketPrice Domain"
    updateTypeNum="0"
    name="IBM.N"
    serviceId="356"
    serviceName="ELEKTRON_AD"
    Payload dataType="FieldList"
        FieldList
            FieldEntry fid="75" name="UPLIMIT" dataType="Real" value="161.12"
            FieldEntry fid="998" name="GEN_VAL3" dataType="Real" value="161.12"
            FieldEntry fid="76" name="LOLIMIT" dataType="Real" value="145.78"
            FieldEntry fid="999" name="GEN_VAL4" dataType="Real" value="145.78"
            FieldEntry fid="8406" name="QTE_ORIGIN" dataType="Rmtes" value="E"
            FieldEntry fid="1041" name="GV1_FLAG" dataType="Rmtes" value="E"
            FieldEntry fid="118" name="PRC_QL_CD" dataType="Enum" value="0"
            FieldEntry fid="3264" name="PRC_QL3" dataType="Enum" value="332"
            FieldEntry fid="9060" name="LULD_TM_MS" dataType="UInt" value="59370029"
        FieldListEnd
    PayloadEnd
UpdateMsgEnd

UpdateMsg
    streamId="5"
    domain="MarketPrice Domain"
    updateTypeNum="0"
    name="IBM.N"
    serviceId="356"
    serviceName="ELEKTRON_AD"
    Payload dataType="FieldList"
        FieldList
            FieldEntry fid="75" name="UPLIMIT" dataType="Real" value="161.12"
            FieldEntry fid="998" name="GEN_VAL3" dataType="Real" value="161.12"
            FieldEntry fid="76" name="LOLIMIT" dataType="Real" value="145.78"
            FieldEntry fid="999" name="GEN_VAL4" dataType="Real" value="145.78"
            FieldEntry fid="3132" name="IRGVAL" dataType="Real" value="4.0"
            FieldEntry fid="8936" name="LIMIT_IND2" dataType="Enum" value="4"
            FieldEntry fid="9060" name="LULD_TM_MS" dataType="UInt" value="59370051"
            FieldEntry fid="11685" name="SECUR_ST" dataType="Rmtes" value="F"
            FieldEntry fid="12766" name="DTRS_IND" dataType="Enum" value="0"
            FieldEntry fid="12767" name="IVOC_IND" dataType="Enum" value="0"
            FieldEntry fid="13403" name="STATUS_IND" dataType="Enum" value="0"
            FieldEntry fid="3888" name="FIN_STATUS" dataType="Rmtes" value="N"
        FieldListEnd
    PayloadEnd
UpdateMsgEnd

We have successfully completed setup of our EMA environmnent.

Troubleshooting

In the event you are unable to build or run the example, ensure you have covered the following steps.

Compiling

  1. Ensure you have the correct version of the Java compiler.  See the prerequisite section at the top of this guide.
  2. As outlined within the Setup and Configuration section, the convenient build scripts use the JAVA_HOME environment variable to locate your Java compiler.  Ensure this environment variable is defined or modify the build script to point to your Java environment.

Running

If you are unable to run, you will need to confirm with your market data adminstrator you have all the correct details regarding your market data server, the service providing your market data and proper login credentials.  Specifically:

  1. Connection details

    The example defaults the connection details as localhost:14002 which means your market data server is running on your localhost on port 14002.

  2. Service Name

    A market data server can host multiple services of data.  You will need to ensure you have the one that provides your market data.

  3. User

    Depending on your environment, you may need to provide a valid user name, also called a DACS user name, which is used to entitle you to retrieve the market data you requested.








  4.  

  5.  
  6.  

You will typically see some type of StatusMsg returned indicating the issue(s) you may encounter.  For example, if an invalid service name is provided, the resulting status may look like this:

StatusMsg
    streamId="0"
    domain="MarketPrice Domain"
    state="Closed / Suspect / None / 'Service name of 'JUNK' is not found.'"
    name="IBM.N"
    serviceName="JUNK"
StatusMsgEnd

To Learn More

Refer to the tutorials section which will walk through the detailed steps to build EMA Applications.

References

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