Elektron SDK - Java

API Family: Elektron

EMA NI Provider - Connecting to the ADH

Download tutorial source code

Click here to download

Last update January 2017
Compilers

JDK 1.7.x, JDK 1.8.x

Prerequisites

EMA NI Provider - A barebones EMA NIP application shell

Declare the NI_PUB and TEST_NI_PUB services in your TREP (see Before you start).

Tutorial purpose

In this tutorial we will see how to use EMA to connect a NI Provider application to the Enterprise Platform (TREP). We will also describe the multiple actions EMA executes under the hood to simplify programmers’ life. Finally we will teach you how to properly disconnect your application from the TREP.  

To this aim we will go through the following sections:

Introduction



Non Interactive Provider Point to Point connection to the ADH

Non Interactive Providers publish information that is cached and re-distributed by the TREP infrastructure. This enables the implementation of very simple provider applications that do not have to go through the hassle of handling requests from consuming applications. NI Providers just publish the data they have and the TREP infrastructure does all the hard work: TREP caches the data, manages the interactions with the consumer applications and distributes the requested data.

In this context, the general process of a NI Provider is the following:

  1. Establish network communication with the TREP.
  2. Perform the login process.
  3. Acquire field dictionaries

    Note: This step is optional and must be implemented by the provider application if it actually needs fields dictionaries - See the Publishing our first Market Price tutorial for more.
  4. Provide the source directory information.
  5. Provide content.
  6. Log out and shut down.

In this tutorial we will see a very simple way to implement a NI Provider that performs steps 1, 2, 3 and 6 with very few EMA calls.

Connect to the ADH

The very first step a NI Provider must perform is to connect to the TREP infrastructure, or more precisely to the ADH (Advanced Data Hub) that is the TREP component provider applications are connected to. As shown in the diagram above, the ADH is also in charge of caching the data published by NI Providers.  This connection can be done either via a point-to-point TCP connection or via a multicast connection. In this tutorial we will demonstrate how to use the default connection mode, which is the TCP connection.

The ADH is a network component installed in your corporate area network. In order to connect to this ADH, you need its IP address, a port number and a user name your application will use to perform the login process just after the connection. If you do not have this information, it can usually be provided by the TREP administration team of your company. 

The simplest way to connect your EMA NI Provider to the ADH is to create an OmmProvider object with an OmmNiProviderConfig object that holds the ADH IP address, the port number and the user name.

    

This is what we have done in the following connect() method that we added to the NIProvider class of this tutorial.

public void connect()
{
    // Exit the method if already connected
    if (provider != null)
        return;

    String host = "YOUR_ADH_IP_ADDRESS:14003";
    String userName = "YOUR_PROVIDER_USER_NAME";

    System.out.println("  Connecting Provider to ADH " + host + " as " + userName);

    // Connect to the infrastructure using hardcoded parameters
    provider = EmaFactory.createOmmProvider(
                                    EmaFactory.createOmmNiProviderConfig()
                                        .host(host)
                                        .username(userName));
}



As you can see, the ADH IP address, the port number and the user name are hardcoded. This is something we will improve on in the next tutorials. But, for the sake of simplicity, we keep them hardcoded for now. Obviously, before you build and run this tutorial you will have to change the tutorial source code with your own ADH IP, port number and user name. Let us say your ADH IP is 10.2.43.49 and your provider user name is nip-user, then  the host and userName variables should be set this way: 

    String host = "10.2.43.49:14003";
    String userName = "nip-user";

Note: The ADH IP address is followed by a colon and the port number the provider should connect to. In this example the port number is set to 14003, which is the default port number for Non Interactive Providers. Unless told otherwise by your TREP Administrator, this is the port number you should use.

Once the OmmProvider object is created with these parameters, the EMA library connects to the ADH and logs in using the user name you provided. If the connection and login are successful, the NI Provider application can eventually publish data for the TREP consuming applications. We will see how to publish data in the next tutorials. 

The OmmProvider object is preserved in the provider class member for later use.

Understanding what happens under the hood

Within the introduction, we explained the general process of a NI Provider, which is:

  1. Establish network communication with the TREP.
  2. Perform the login process.
  3. Provide the source directory information.
  4. Acquire field dictionaries

    Note: This step is optional and must be implemented by the provider application if it actually needs fields dictionaries - See the Publishing our first Market Price tutorial for more.
  5. Provide content.
  6. Log out and shut down.

The first 3 steps of this process are actually executed under the hood by the EMA library when you create the OmmProvider object. Steps 1 and 2 are more obvious as we provided the ADH IP address, port number and login user name when creating the OmmProvider object. This is less obvious for step 3 because we do not provide any source directory information such as the service name, or any RDM models supported by our Ni Provider application. Instead, EMA provides default settings for this information on behalf of the user.  For example, even if our NI Provider application does not provide any source directory information, it declares a service named NI_PUB, as you will see when we will run and test our application in the Build and run the application section.  

Disconnect from the ADH

In order to logout and disconnect from the ADH, you just have to uninitialize the OmmProvider object created at the time of the connection. This is what we implemented in the disconnect() method that we added to the NiProvider class.

public void disconnect()
{
    // Exit the method if already disconnected
    if (provider == null)
        return;

    System.out.println("  Disconnecting...");

    // Disconnect from the infrastructure
    provider.uninitialize();
    provider = null;
}  

The main workflow

The main workflow leverages these two new connect() and disconnect() methods to implement the following:

  • It creates a NiProvider,
  • It connects the provider to the infrastructure and waits for 60 seconds, so that you have time to verify that the NI_PUB service goes up.
  • Then, it disconnects, it waits for 10 seconds and exits the application.
public static void main(String[] args)
{
    .
    .
    .
        NiProvider provider = new NiProvider(); 

        provider.connect();

        waitFor(60);

        provider.disconnect();

        waitFor(10);
    .
    .
    .
} 

Build and run the application

Build the application and start it. Please refer to the Build and Run section within the first tutorial of this series (A barebones EMA NIP application shell) for detailed instructions.

This is what you should get: 

  1. The application should display something like:
-------------------------------------------------------------------------------
|                    Non Interactive Provider EMA Tutorial                    |
|                                                                             |
|                     Tutorial 2 - Connecting to the ADH                      |
-------------------------------------------------------------------------------
  Provider created
  Connecting Provider to ADH 10.2.43.49:14003 as nip-user
  Waiting for 60 seconds...
  Disconnecting...
  Waiting for 10 seconds...
  Exiting the application
Press any key to continue . . .
  1. During the 60 seconds wait, open a TREP consuming application that displays the services available on the infrastructure. After a short while, the NI_PUB service should go up.

    Note: As we didn’t indicate which service our provider application should serve, the EMA library used its hardcoded default service name NI_PUB.

    As an example, this is a screenshot of the Eikon About box that displays the status of its Data Feeds (aka Services).



    Note: In order to have the NI_PUB service visible in Eikon, you must declare this service name in the TR Eikon Configuration Manager (Feed/Add More Feeds).
  2. After the 60 seconds wait, the NI_PUB service should go down and the application should exit.

Troubleshooting

Q: When I build or run the tutorial, it fails with an error like:

The system cannot find the path specified

A: The JAVA_HOME environment variable is not set, or set to the wrong path. See Setup the development environment section of the first tutorial.

 

Q: When I build the tutorial, I get ”<path>/javac: No such file or directory” or when I run the tutorial, I get  ”<path>/java: No such file or directory” error like

line 59: /home/user/jdk/bin/javac: No such file or directory

A: The JAVA_HOME environment variable is not set, or set to the wrong path. See Setup the development environment.

 

Q: When I build or run the tutorial, I get "Finding Jar files in <path>” and “The system cannot find the path specified.” errors like

Build the NIP application with Elektron SDK Java version 1.2.x or higher.

Finding Jar files in C:\Elektron-SDK\Java\Ema\Libs\
The system cannot find the path specified.

A: There are 2 possible causes:

 

Q: When I build or run the tutorial, I get "<path to /*jar> : No such file or directory” error like

/home/user/Elektron-SDK1.1.1.E2.java.eload/Java/Ema/Libs/*.jar: No such file or directory

A: There are 2 possible causes:

 

Q: When I build the tutorial, I get "package ... does not exist" and "cannot find symbol" errors like:

Main.java:20: error: package com.thomsonreuters.ema.access does not exist
import com.thomsonreuters.ema.access.OmmException;
                                    ^
Main.java:56: error: cannot find symbol
                catch (OmmException exception)
                       ^
  symbol:   class OmmException
  location: class Main

A: The ELEKTRON_JAVA_HOME environment variable is not set, or set to the wrong path. See Setup the development environment section of the first tutorial.

 

Q: When I run the tutorial, I get a JNI error with a NoClassDefFoundError exception like:

Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.NoClassDefFoundError: com/thomsonreuters/ema/access/OmmException
        at java.lang.Class.getDeclaredMethods0(Native Method)
        at java.lang.Class.privateGetDeclaredMethods(Class.java:2701)
        at java.lang.Class.privateGetMethodRecursive(Class.java:3048)
        at java.lang.Class.getMethod0(Class.java:3018)
        at java.lang.Class.getMethod(Class.java:1784)
        at sun.launcher.LauncherHelper.validateMainClass(LauncherHelper.java:544)
        at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:526)
Caused by: java.lang.ClassNotFoundException: com.thomsonreuters.ema.access.OmmException
        at java.net.URLClassLoader.findClass(URLClassLoader.java:381)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:424)
        at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:331)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:357)
        ... 7 more

A: The ELEKTRON_JAVA_HOME environment variable is not set, or set to the wrong path. See Setup the development environment section of the first tutorial.

 

Q: The application is stuck after the "Connecting Provider to ADH…" message is displayed.

After a while the application displays an error like: 

login failed (timed out after waiting 45000 milliseconds) for 10.2.43.149:14003)

A: Verify that the ADH of your TREP infrastructure is up, and that you properly set the host variable of the connect() method. You can also use the telnet command tool to verify that your NIP application machine can connect to the ADH (telnet <ADH host> <port>). If the telnet succeeds but you still can’t connect, verify that you don’t have any firewall blocking the messages sent/received by the application.  

Ultimately, ask your TREP administrator to help you to investigate with TREP monitoring tools like adhmon.

 

Tutorial Group: 
EMA NI Provider