Overview

This document contains description of the main features of JMS Transport Adaptor for FixEdge and common steps required to install JMS Transport Adaptor (JMS TA) for the FIX Edge.

Concept

The JMS Adaptor for FIX Server (hereinafter JMS Adaptor) is intended for communication with FIX Server from third-part applications via JMS. JMS TA is a library that exposes a set of methods for communicating with FixEdge's Transport Layer. Also, JMS TA gives a transport, which implements JMS protocol for transmitting/receiving data to/from JMS provider(s):

• JMS TA performs packaging of FIX(ML) messages to JMS Messages (Binary or Text) with further sending to appropriate JMS provider(s);
• JMS TA performs extracting of FIX(ML) messages from received JMS Messages with further sending it to Transport Layer;

Operation Scenarios

During FIX server start-up Transport Layer creates JMS connection for each Client Name listed in configuration ClientNames property with specified Session Type, Topic, Ack mode and other properties created.

• After success creation of Connection to JMS Provider - notification to Transport Layer is sent via onLogon() with ClientName as parameter;
• After success disconnect from JMS Provider - notification to Transport Layer is sent via onLogout() with ClientName as parameter;
• After successfull registration in Transport Layer, JMS TA starts processing incoming messages from JMS Provider(s) and routing outgoing messages from TL to JMS provider(s).

Prerequisites

Path to jvm libraries should be specified in PATH variable if installation goes in Linux (E.g.: /home/user/work/environment/jdk1.7.0/jre/lib/amd64/server).

For FIXEdge prior to v5.7:

• Java Runtime Environment 1.6 or higher
• Path to jvm libraries should be specified in PATH variable if installation goes in Windows . (E.g.: C:\Program Files (x86)\Java\jre7\bin\server)
  
  

Installation and run steps

Configuration for ActiveMQ

Installation and run steps (after rev. 66518)

1. Install FIXEdge for Windows (use "tar xvf" commands for Linux/Solaris)

2. Add path to appropriate activemq*.jar to java classpath in FIXEdge1/conf/jms-ta-distribution/etc/JVM_Options.jvmopts file e.g.:
   

   JVM_Options.jvmopts

   Windows: -Djava.class.path=(...);FixEdge1/conf/jms-ta-distribution/tool/lib/activemq-all-5.3.2.jar;
   Linux: -Djava.class.path=(...);../FixEdge1/conf/jms-ta-distribution/tool/lib/activemq-all-5.3.2.jar;

   Note

   The ActiveMQ library could be found at activemq.apache.org
   Download original package and extract "activemq-all-x.x.x.jar" into ../FixEdge1/conf/jms-ta-distribution/tool/lib/

3. Configure paths to logs in FIXEdge1/conf/jms-ta-distribution/etc/log4j.properties. Paths to logs directory must be absolute.

4. Configure JMS adapter in FIXEdge.properties.
   Add TransportLayer.JMSTA to TransportLayer.TransportAdapters, so as a result you should get "TransportLayer.TransportAdapters = TransportLayer.JMSTA"
   And add JMS session parameters, for example:

   FIXEdge.properties

   # Transport Layer Section
   TransportLayer.TransportAdapters = TransportLayer.JMSTA
   TransportLayer.JMSTA.Description = JMS Transport Adaptor
   TransportLayer.JMSTA.DllName = bin/jmsTADll-vc10-MD-x64.dll     // Use libJMSTA.so for Linux
   TransportLayer.JMSTA.JVMOptionsFile = FixEdge1/conf/JVM_Options.jvmopts     // Use ../FixEdge1/conf/JVM_Options.jvmopts for Linux
   TransportLayer.JMSTA.ConnectionNames = Connection1
   TransportLayer.JMSTA.ClientNames = ProducerSession, ConsumerSession
   
   TransportLayer.JMSTA.Connection.Connection1.InitialContextFactory = org.apache.activemq.jndi.ActiveMQInitialContextFactory
   TransportLayer.JMSTA.Connection.Connection1.ProviderURI = tcp://10.17.12.244:61616
   TransportLayer.JMSTA.Connection.Connection1.User = test
   TransportLayer.JMSTA.Connection.Connection1.Password = test
   TransportLayer.JMSTA.Connection.Connection1.ConnectionFactory = queueConnectionFactory
   TransportLayer.JMSTA.Connection.Connection1.Reconnect = false
   TransportLayer.JMSTA.Connection.Connection1.ReconnectTries = 3
   TransportLayer.JMSTA.Connection.Connection1.ReconnectInterval = 500
   
   TransportLayer.JMSTA.Client.ProducerSession.ConnectionName = Connection1
   TransportLayer.JMSTA.Client.ProducerSession.StorageDir = ../FixEdge1/log
   TransportLayer.JMSTA.Client.ProducerSession.SessionType = Producer
   TransportLayer.JMSTA.Client.ProducerSession.MessagingMode = Queue
   TransportLayer.JMSTA.Client.ProducerSession.DestinationURI = MyQueue 
   TransportLayer.JMSTA.Client.ProducerSession.DeliveryMode = NoPersist
   TransportLayer.JMSTA.Client.ProducerSession.TimeToLive = 100000
   TransportLayer.JMSTA.Client.ProducerSession.SessionAckMode = Auto
   TransportLayer.JMSTA.Client.ProducerSession.MessageType = Text
   TransportLayer.JMSTA.Client.ProducerSession.Transacted = true
   TransportLayer.JMSTA.Client.ProducerSession.DurableSubscription = false
   TransportLayer.JMSTA.Client.ProducerSession.DurableSubscriptionName = DurableTest
    
   TransportLayer.JMSTA.Client.ConsumerSession.ConnectionName = Connection1
   TransportLayer.JMSTA.Client.ConsumerSession.StorageDir = ../FixEdge1/log
   TransportLayer.JMSTA.Client.ConsumerSession.SessionType = Consumer
   TransportLayer.JMSTA.Client.ConsumerSession.MessagingMode = Queue
   TransportLayer.JMSTA.Client.ConsumerSession.DestinationURI = MyQueue
   TransportLayer.JMSTA.Client.ConsumerSession.DeliveryMode = NoPersist
   TransportLayer.JMSTA.Client.ConsumerSession.TimeToLive = 100000
   TransportLayer.JMSTA.Client.ConsumerSession.SessionAckMode = Auto
   TransportLayer.JMSTA.Client.ConsumerSession.MessageType = Text
   TransportLayer.JMSTA.Client.ConsumerSession.Transacted = false
   TransportLayer.JMSTA.Client.ConsumerSession.DurableSubscription = false
   TransportLayer.JMSTA.Client.ConsumerSession.DurableSubscriptionName = DurableTest
   

   Note: TransportLayer.JMSTA.Connection.Connection1.ProviderURI = tcp://10.17.12.244:61616 - host:port of Apache ActiveMQ Message Broker.
   
   

   According to this configuration, FIXEdge will establish connection (Connection1) with ActiveMQ on 10.17.12.244:61616. This connection will be used by two JMS sessions: ProducerSession will receive FIX messages and send converted messages into MyQueue queue of ActiveMQ (producer session), ConsumerSession will receive JMS messages from MyQueue queue of ActiveMQ and convert them into FIX (consumer session).

5. Use FixEdge1/conf/BL_Config.xml as Business Layer Rules configuration file.
   According to that BL rule and to JMS adapter configuration: FIX messages from FIXCLIENT1 will be converted into JMS and sent to ActiveMQ using producer session JMSPTestSession, then consumers session JMSPTestSession2 will get these JMS messages from ActiveMQ, convert it back to FIX and send messages to FIXCLIENT2.

6. ActiveMQ configuration (You can get it from official site).

   1. In conf/activemq.xml add <destination> to <broker> section:

      conf/activemq.xml

      <destinations>
      	<queue physicalName="MyQueue" />
      </destinations>

   2. Start ActiveMQ using bin/activemq.bat

7. Enable UnregisteredAcceptors in  FixEdge1/conf/engine.properties (UnregisteredAcceptor.CreateSession = true)

8. Start FIXEdge

9. Start, for example, SimpleClient (or HSBC tool) and establish FIXCLIENT1-FIXEDGE, FIXCLIENT2-FIXEDGE sessions with FIXEdge

10. Send FIX messages to FIXCLIENT1-FIXEDGE session

11. Messages from FIXCLIENT1-FIXEDGE session should be received in FIXCLIENT2-FIXEDGE Session

12. Open ActiveMQ admin console. Messages Enqueued and Messages Dequeued counters on Queues and Topics page should be changing with each sent message.

Installation and run steps (prior rev. 66518)

...
3. Unpack jms-ta-distribution*.zip to FixEdge1/conf/
4-5. In FixEdge1/conf directory create JVM_Options.jvmopts file with:

-Xms232m
-Xmx512m
-Xrs
-Djava.class.path=FixEdge1/conf/jms-ta-distribution/lib/jms-ta-jni-1.2.2.jar;FixEdge1/conf/jms-ta-distribution/lib/jms-ta-core-1.2.2.jar;FixEdge1/conf/jms-distribution-1.2.2/lib/activemq-all-A.B.C.jar;FixEdge1/conf/;

Where 1.2.2 - numbers in version of jms-distribution.
A.B.C -  numbers in version of activemq jar-file.

6. Copy log4j.properties file (on older version it is logback.xml) from FixEdge1/conf/jms-distribution/etc to FixEdge1/conf
7. ...
8. Configure BL_Config.xml as:

<?xml version="1.0" encoding="UTF-8" ?>
<FIXEdge>
<BusinessLayer>
     <Rule>
          <Source>
               <FixSession SenderCompID="FIXCLIENT1" TargetCompID="FIXEDGE"/>
          </Source>
               <Action>
                    <Send Name="ProducerSession" />
               </Action>
     </Rule>
     <Rule>
          <Source Name="ConsumerSession" />
               <Action>
                    <Send>
                         <FixSession SenderCompID="FIXEDGE" TargetCompID="FIXCLIENT2"/>
                    </Send>
              </Action>
     </Rule>
     <DefaultRule>
          <Action>
               <DoNothing/>
          </Action>
     </DefaultRule>
</BusinessLayer>
</FIXEdge>

Configuration for TIBCO EMS

On TIBCO EMS side

1. In C:\ProgramData\TIBCO_HOME\tibco\cfgmgmt\ems\data\tibemsd.conf file set

                 authorization = enabled

                 user_auth = local  // Not sure if this is required 

                 client_heartbeat_server =  <interval>  // in seconds

     2. Using TIBCO EMS admin tool og GEMS create user "fixedge_dev" with password "fixedge_dev"

     3.  Using TIBCO EMS admin tool og GEMS create TOPIC "fixedge.deals"

     4. In "fixedge.deals" topic set isSecure property to "true"

     5. Assign "Subscribe To Topic", "Create Durable" and "Use Durable" permissions for "fixedge_dev" user

     6. There is no need in manual creation of DURABLE. FIXEdge will create it automatically.

On FIXEdge side

1. Install FIXEdge for Windows (use "tar xvf" commands for Linux/Solaris)

2. Put jmsTADll-xx.dll (libjmsTADll-xx.so and symlink libjmsTA.so  for Linux/Solaris) file from JMSAdaptor package into bin directory of FIXEdge

3. Copy "jms-ta-distribution" directory to FIXEdge's configuration directory (e.g FixEdge1/conf/)

4. Copy JVM_Options.jvmopts from Package/DOC/ to FixEdge1/conf/ 

5. Copy appropriate tibjms.jar library from TIBCO EMS (for example, it can be located into C:/tibco/ems/6.3/lib/) to, for example, jms-ta-distribution/tool/lib/ folder and add path to this library to classpath in JVM_Options.jvmopts, e.g.:

   JVM_Options.jvmopts

   -Djava.class.path=(...);FixEdge1/conf/jms-ta-distribution/tool/lib/tibjms.jar;

6. Configure consumer connection parameters in the FIXEdge.properties, e.g.:

   FIXEdge.properties

   TransportLayer.TransportAdapters = TransportLayer.JMSTA
   
   TransportLayer.JMSTA.Description = JMS Transport Adaptor
   TransportLayer.JMSTA.DllName = bin/jmsTADll-vc10-MD-x64.dll 
   TransportLayer.JMSTA.JVMOptionsFile = FixEdge1/conf/JVM_Options.jvmopts 
   TransportLayer.JMSTA.ConnectionNames = Connection1
   TransportLayer.JMSTA.ClientNames = fixedge_recv_dev   // This will be used as ClientID of durable
   
   TransportLayer.JMSTA.Connection.Connection1.InitialContextFactory = com.tibco.tibjms.naming.TibjmsInitialContextFactory
   TransportLayer.JMSTA.Connection.Connection1.ProviderURI = tcp://epuakyiw1476:7222
   TransportLayer.JMSTA.Connection.Connection1.User = fixedge_dev
   TransportLayer.JMSTA.Connection.Connection1.Password = fixedge_dev
   TransportLayer.JMSTA.Connection.Connection1.ConnectionFactory = TopicConnectionFactory
   TransportLayer.JMSTA.Connection.Connection1.ReconnectTries = 2000000
   TransportLayer.JMSTA.Connection.Connection1.ReconnectInterval = 2000
   TransportLayer.JMSTA.Connection.Connection1.Reconnect = true
   
   ## Topic Consumer client
   TransportLayer.JMSTA.Client.fixedge_recv_dev.ConnectionName = Connection1
   TransportLayer.JMSTA.Client.fixedge_recv_dev.SessionType = Consumer
   TransportLayer.JMSTA.Client.fixedge_recv_dev.MessagingMode = Topic
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DestinationURI = fixedge.deals
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DeliveryMode = NoPersist
   TransportLayer.JMSTA.Client.fixedge_recv_dev.TimeToLive = 100000
   TransportLayer.JMSTA.Client.fixedge_recv_dev.SessionAckMode = Auto
   TransportLayer.JMSTA.Client.fixedge_recv_dev.MessageType = Text
   TransportLayer.JMSTA.Client.fixedge_recv_dev.StorageDir = FixEdge1/log
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DurableSubscription = true
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DurableSubscriptionName = fixedge.deals

   
   If you need to configure consumer and producer, then you should repeat steps 2 and 5 from "On TIBCO EMS side" instruction and in FIXEdge.properties configuration should looks like:

   FIXEdge.properties

   TransportLayer.TransportAdapters = TransportLayer.JMSTA
   
   TransportLayer.JMSTA.Description = JMS Transport Adaptor
   TransportLayer.JMSTA.DllName = bin/jmsTADll-vc10-MD-x64.dll
   TransportLayer.JMSTA.JVMOptionsFile = FixEdge1/conf/JVM_Options.jvmopts
   TransportLayer.JMSTA.ConnectionNames = Connection1,Connection2
   TransportLayer.JMSTA.ClientNames = fixedge_recv_dev,fixedge_send_dev
   
   TransportLayer.JMSTA.Connection.Connection1.InitialContextFactory = com.tibco.tibjms.naming.TibjmsInitialContextFactory
   TransportLayer.JMSTA.Connection.Connection1.ProviderURI = tcp://epuakyiw1476:7222
   TransportLayer.JMSTA.Connection.Connection1.User = fixedge_dev
   TransportLayer.JMSTA.Connection.Connection1.Password = fixedge_dev
   TransportLayer.JMSTA.Connection.Connection1.ConnectionFactory = TopicConnectionFactory
   TransportLayer.JMSTA.Connection.Connection1.ReconnectTries = 2000000
   TransportLayer.JMSTA.Connection.Connection1.ReconnectInterval = 2000
   TransportLayer.JMSTA.Connection.Connection1.Reconnect = true
   
   TransportLayer.JMSTA.Connection.Connection2.InitialContextFactory = com.tibco.tibjms.naming.TibjmsInitialContextFactory
   TransportLayer.JMSTA.Connection.Connection2.ProviderURI = tcp://epuakyiw1476:7222
   TransportLayer.JMSTA.Connection.Connection2.User = fixedge
   TransportLayer.JMSTA.Connection.Connection2.Password = fixedge
   TransportLayer.JMSTA.Connection.Connection2.ConnectionFactory = TopicConnectionFactory
   TransportLayer.JMSTA.Connection.Connection2.ReconnectTries = 2000000
   TransportLayer.JMSTA.Connection.Connection2.ReconnectInterval = 2000
   TransportLayer.JMSTA.Connection.Connection2.Reconnect = true
      
   ## Topic Consumer client
   TransportLayer.JMSTA.Client.fixedge_recv_dev.ConnectionName = Connection1
   TransportLayer.JMSTA.Client.fixedge_recv_dev.SessionType = Consumer
   TransportLayer.JMSTA.Client.fixedge_recv_dev.MessagingMode = Topic
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DestinationURI = fixedge.deals
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DeliveryMode = NoPersist
   TransportLayer.JMSTA.Client.fixedge_recv_dev.TimeToLive = 100000
   TransportLayer.JMSTA.Client.fixedge_recv_dev.SessionAckMode = Auto
   TransportLayer.JMSTA.Client.fixedge_recv_dev.MessageType = Text
   TransportLayer.JMSTA.Client.fixedge_recv_dev.StorageDir = FixEdge1/log
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DurableSubscription = true
   TransportLayer.JMSTA.Client.fixedge_recv_dev.DurableSubscriptionName = fixedge.deals
   
    ## Topic Producer client
   TransportLayer.JMSTA.Client.fixedge_send_dev.ConnectionName = Connection2
   TransportLayer.JMSTA.Client.fixedge_send_dev.SessionType = Producer
   TransportLayer.JMSTA.Client.fixedge_send_dev.MessagingMode = Topic
   TransportLayer.JMSTA.Client.fixedge_send_dev.DestinationURI = fixedge.deals
   TransportLayer.JMSTA.Client.fixedge_send_dev.DeliveryMode = NoPersist
   TransportLayer.JMSTA.Client.fixedge_send_dev.TimeToLive = 100000
   TransportLayer.JMSTA.Client.fixedge_send_dev.SessionAckMode = Auto
   TransportLayer.JMSTA.Client.fixedge_send_dev.MessageType = Text
   TransportLayer.JMSTA.Client.fixedge_send_dev.StorageDir = FixEdge1/log
   TransportLayer.JMSTA.Client.fixedge_send_dev.DurableSubscription = false
   TransportLayer.JMSTA.Client.fixedge_send_dev.DurableSubscriptionName = fixedge.deals

    7. Configure BL Rules in BL_Config.xml to put received FIX messages to "fixedge_send_dev" client and get messages from "fixedge_recv_dev" client

    8. Start TIBCO EMS

    9. Start FIXEdge

Configuration

The JMS adaptor is configured by means of the following properties:

Note that all changes in the properties file are applied only after FixEdge restart.

JMS Adapter Monitoring

The Kafka Transport Adapter is integrated with a FIXICC monitoring feature.

The adapter provides information about the following indicators:

Start and Stop operations for JMS TA

FIXEdge C++ provides Start operation for Disconnected JMS TA sessions and Stop operation for Connecting and Running JMS TA sessions on request from the subscribed monitoring application.

Please refer to the Transport adaptor operations for FIXEdge C++ page for additional details about Start and Stop operations.

Start operation

Start operation can be applied to JMS TA sessions in the Disconnected state.

FIXEdge starts a particular JMS TA session on the request from the subscribed monitoring application and if the operation has been applied replies with a successful response.

In case when there is no session with the requested name FIXEdge logs an error and replies to the subscribed monitoring application with an error response below: 

Can't find session with id <session_name>

In case when Start operation cannot be applied FIXEdge replies to the subscribed monitoring application with an error response and logs an error below:

"Session '<session_name>': The session <session_name> can't be started: <description> Reason: Operation cannot be applied"

Stop operation

Stop operation can be applied to JMS TA sessions in the Running and Connecting states.

FIXEdge stops a particular JMS TA session on the request from the subscribed monitoring application and if the operation has been applied replies with a successful response.

In case when there is no session with the requested name FIXEdge logs an error and replies to the subscribed monitoring application with an error response below:

Can't find session with id <session_name>

In case when Stop operation cannot be applied FIXEdge replies to the subscribed monitoring application with an error response and logs an error below:

"Session '<session_name>': The session <session_name> can't be stopped: <description> Reason: Operation cannot be applied"

In case when JMS TA session is in a Disconnected state and JMS TA receives the message, this message is persisted in storage to be sent on JMS TA session start.

Troubleshooting

Linux and Windows default configuration have different relative paths

Solution:

• On linux all relative paths should be set from FIXEdge bin/ directory (e.g /home/user/B2BITS/FixEdge/v.5.8.0.x/bin) because packages for various OS has different values of FIXEdge.RootDir parameter in FIXEdge.properties.

JMS Transport Adapter fails with "Exception description.java.lang.IllegalArgumentException: Problem with initiation of InitialContext. Cannot instantiate class"

Issues in the logs

2021-02-09 12:38:27,496 UTC   DEBUG   [JNI_WRAPPER]  140737353992000  Exception description.java.lang.IllegalArgumentException: Problem with initiation of InitialContext. Cannot instantiate class: com.tibco.tibjms.naming.TibjmsInitialContextFactory
        at com.epam.fixengine.jms.context.JndiContext.configureJNDIContext(JndiContext.java:59)
        at com.epam.fixengine.jms.context.SessionContext.<init>(SessionContext.java:30)
        at com.epam.fe.jms.JMSAdaptorImpl.createSessions(JMSAdaptorImpl.java:65)
        at com.epam.fe.jms.JMSAdaptorImpl.init(JMSAdaptorImpl.java:46)
        at com.epam.fe.jms.jni.JMSAdaptor.init(JMSAdaptor.java:29)
Caused by: javax.naming.NoInitialContextException: Cannot instantiate class: com.tibco.tibjms.naming.TibjmsInitialContextFactory [Root exception is java.lang.ClassNotFoundException: com.tibco.tibjms.naming.TibjmsInitialContextFactory]
        at javax.naming.spi.NamingManager.getInitialContext(NamingManager.java:674)
        at javax.naming.InitialContext.getDefaultInitCtx(InitialContext.java:313)
        at javax.naming.InitialContext.init(InitialContext.java:244)
        at javax.naming.InitialContext.<init>(InitialContext.java:216)
        at com.epam.fixengine.jms.context.JndiContext.<init>(JndiContext.java:32)
        at com.epam.fixengine.jms.context.JndiContext.configureJNDIContext(JndiContext.java:57)
        ... 4 more

Root cause

JMS transport adapter libraries (e.g JMS ta, Tibco, active MQ, etc..) are not found in the configured classpath: java.class.path.

Solution

• Make sure that libraries are placed to jms-ta-distribution/tool/lib/.

• Check if the required libraries are defined in JVM properties files (JVM_Options.jvmopts) classpath

  JVM_Options.jvmopts

  -Djava.class.path=/opt/fixedge/FIXEdge/FIXEdge1/conf;/opt/fixedge/FIXEdge/FIXEdge1/conf/jms-ta-distribution/lib/jms-ta-jni-1.2.10.jar;/opt/fixedge/FIXEdge/FIXEdge1/conf/jms-ta-distribution/lib/jms-ta-core-1.2.10.jar;/opt/fixedge/FIXEdge/FIXEdge1/conf/jms-ta-distribution/etc;/opt/fixedge/FIXEdge/FIXEdge1/conf/jms-ta-distribution/tool/lib/tibjms.jar

• The recent version of TIBCO EMS libraries uses jms version 2.0 or newer. For this case jms-2.0.jar should be also copied to  to FIXEdge1\conf\jms-ta-distribution\lib and added to the classpath:

  JVM_Options.jvmopts

  -Djava.class.path=...;/opt/fixedge/FIXEdge/FIXEdge1/conf/jms-ta-distribution/tool/lib/jms-2.0.jar