Elektron SDK - Java

API Family: Elektron

EMA NI Provider - Introducing the EMA configuration file

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 - Listening to the connection state

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

Tutorial purpose

In the previous tutorials we used hardcoded values for the connection parameters of our NI Provider application. In this tutorial you will learn how to leverage the EMA configuration file to store these parameters. This tutorial is focused on connection parameters. 

In this tutorial we will go through the following sections:

Introduction

For the sake of simplicity, the NIProvider.connect() method of previous tutorials used hardcoded parameter values for the ADH IP address and port number. Obviously this solution is not very flexible and requires rebuilding the application every time you want to change these parameters. In this tutorial we will see that the EMA library uses a configuration file that is automatically loaded, and that you can leverage to store your connection parameters.

The EMA configuration file

EMA fosters convention over configuration, meaning that many default behaviors are hardcoded into the EMA library, and globally enforced. That way, as long as they follow the EMA conventions, EMA applications can work with a very small set of parameters.  For example, you don’t have to tell EMA the port number of the ADH your NI Provider must connect to, because, by convention, the EMA library assumes this port is 14003. You can change it if you want, but then you will have to tell EMA what the port number is, either programmatically or by using a configuration parameter.

The same way, by convention, the EMA configuration file should be named EmaConfig.xml and located in the working directory of the application. The EMA configuration file uses a simple XML schema. Here is the one we will use in this tutorial:

<?xml version="1.0" encoding="UTF-8"?>
<EmaConfig>

    <NiProviderGroup>
        <DefaultNiProvider value="NiProvider_1" />
        <NiProviderList>
            <NiProvider>
                <Name value="NiProvider_1" />
                <Channel value="Channel_1" />
            </NiProvider>
        </NiProviderList>
    </NiProviderGroup>

    <ChannelGroup>
        <ChannelList>
            <Channel>
                <Name value="Channel_1" />
                <ChannelType value="ChannelType::RSSL_SOCKET" />
                <Host value="YOUR_ADH_IP_ADDRESS" />
                <Port value="14003" />
            </Channel>
        </ChannelList>
    </ChannelGroup>

</EmaConfig>

In this schema the EMA configuration parameters are contained in the <EmaConfig> root node. This node may contain a number of sub-nodes, each of them grouping parameters for a specific domain. For example, connection parameters are contained in the <ChannelGroup> node. As explained above, most of these groups and parameters are optional. For an exhaustive list, please consult the EMA Java Configuration Guide in References.

Our first EMA configuration file uses just two groups, described below:

The <NiProviderGroup>

This is where you define the parameters of the NI Providers created by your application. The <NiProviderGroup> may declare one or several providers contained in the <NiProviderList>. In our case we only declare one. When the list declares several providers, the <DefaultNiProvider> parameter identifies the provider that must be used when the NiProvider application does not specify it (that is the case for this tutorial series).

Each provider of the <NiProviderList>. is defined in a <NiProvider> node which defines 2 parameters:

  • <Name>: This is the name of the provider.
  • <Channel>: This parameter identifies the communication channel used by this provider.

In our case we defined a provider called NiProvider_1. This name is totally arbitrary; you can use any name you want. Then, we declared that this provider uses a communication channel named Channel_1.

Notes:

  • <NiProvider> nodes may have other parameters that we do not use in this tutorial. They are described in the EMA Java Configuration Guide (see References)
  • In a more complex configuration file, you may decide to declare several providers. In that case, EMA would use the first provider of the <NiProviderList> as the default provider. If you want to use another provider as the default, you must specify it using the <DefaultNiProvider> parameter. As in our case we have only one provider, the <DefaultNiProvider> parameter is useless. But we kept it anyway to be more explicit.

The <ChannelGroup>

This is the group where connection parameters are defined. The <ChannelGroup> may declare one or several channels contained in the <ChannelList>. In our case we only have Channel_1 that is used by NiProvider_1Channel_1 defines 3 parameters:

  • <ChannelType>: this parameter defines the type of connection (RSSL_SOCKET in our case).
  • <Host>: this parameter defines the IP address of the ADH to connect to (you must set the IP of your ADH here).
  • <Port>: this parameter defines the ADH port number to connect to (14003 in our case).

As the <ChannelType> default value is RSSL_SOCKET and as the Port default value is 14003 , we could just get rid of these parameters for NiProvider. We kept them anyway in order to be more explicit.

Below is a simplified version that relies on the default values for the <DefaultNiProvider>, <ChannelType> and <Port> parameters:

<?xml version="1.0" encoding="UTF-8"?>
<EmaConfig>

    <NiProviderGroup>
        <NiProviderList>
            <NiProvider>
                <Name value="NiProvider_1" />
                <Channel value="Channel_1" />
            </NiProvider>
        </NiProviderList>
    </NiProviderGroup>

    <ChannelGroup>
        <ChannelList>
            <Channel>
                <Name value="Channel_1" />
                <Host value="YOUR_ADH_IP_ADDRESS" />
            </Channel>
        </ChannelList>
    </ChannelGroup>

</EmaConfig>

NI Provider refactoring

Now that the connection parameters are stored in the EmaConfig.xml configuration file, we can refactor our code to get rid of the hardcoded values. To this aim we removed the host variable (it contained both the ADH IP and port number) and also removed the .host() call to the OmmNiProviderConfig object.

The user name is the one connection parameter that we cannot move to the EMA configuration file. For more flexibility, we decided to move it to the main() static method at the application level. It is still hardcoded in the main() but you can easily turn it into a parameter of the application. We also renamed the NiProvider.connect() method to connectAs(username) so that the main() method can call it with the user name as a parameter.

Here is the new NiProvider connection method:

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

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

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

    // Register the _connectionStateListener to receive login messages from EMA
    connectionStateListener = new ConnectionStateListener();
    provider.registerClient(
                    EmaFactory.createReqMsg()
                        .domainType(EmaRdm.MMT_LOGIN)
                        .name(userName), 
                    connectionStateListener);
}

The main workflow

The main workflow is still the same. As described above, we just replaced the connect() call of the provider by connectAs() with the user name as parameter.

public static void main(String[] args)
{
    .
    .
    .
        NiProvider provider = new NiProvider(); 

        provider.connectAs("YOUR_PROVIDER_USER_NAME");

        waitFor(60);

        provider.disconnect();
    .
    .
    .
} 

Build and run the application

Edit the EmaConfig.xml and set the Host parameter with the IP of your ADH.

Then, 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.

The application should display something like:

-------------------------------------------------------------------------------
|                    Non Interactive Provider EMA Tutorial                    |
|                                                                             |
|             Tutorial 4 - Introducing the EMA configuration file             |
-------------------------------------------------------------------------------
  Provider created
  Connecting Provider to ADH as nip-user
  Waiting for 60 seconds...
  Provider is connected. OmmState:Open / Ok / None / 'Refresh Completed'
  Disconnecting...
  Exiting the application

The behavior of the application should be the same as that for the previous tutorial.

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 parameter in the EmaConfig.xml file. 

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