Introduction

FIX is a public-domain messaging standard developed specifically for the real-time electronic exchange of securities transactions. It has a large user base, and the protocol specifications are developed by the collaborative effort of banks, broker-dealers, exchanges, industry utilities, institutional investors, and IT providers around the world.

The FIX protocol specifications can be divided into two sections - the FIX session protocol and the FIX application protocol. The session protocol is concerned with the delivery of data, while the application protocol defines business-related data content.

Apache Synapse supports sending and receiving FIX messages via its FIX transport. This transport is based on Quickfix/J, a popular open source library used to develop applications based on the FIX protocol. The FIX transport enables Synapse to operate as both a FIX acceptor and a FIX initiator. If you have some prior experience working with Quickfix/J, you will realize that most of the features and configuration options available in Quickfix/J are applicable to the Synapse FIX transport as well.

To learn more about the FIX protocol and the Synapse FIX transport, please refer the following articles:

Transport Configuration

Synapse binary distribution does not contain the Quickfix/J libraries. To use the FIX transport, you must download Quickfix/J separately, and deploy the necessary jar files into the Synapse installation. We recommend using Quickfix/J 1.4.0 with Synapse. Copy the following jar files from the Quickfix/J binary distribution to the SYNAPSE_HOME/lib directory.

  • quickfixj-core.jar
  • quickfixj-msg-fix40.jar
  • quickfixj-msg-fix41.jar
  • quickfixj-msg-fix42.jar
  • quickfixj-msg-fix43.jar
  • quickfixj-msg-fix44.jar
  • mina-core.jar
  • slf4j-api.jar
  • slf4j-jdk14.jar

Similar to the file transport, the FIX transport is also mostly configured at the proxy service and endpoint level. To receive FIX messages, we expose a proxy service over the FIX transport, and specify the FIX connection settings as proxy service parameters. To send FIX messages, we define an address endpoint with a URL containing the FIX connection settings.

FIX Transport Listener

FIX transport listener enables Synapse to receive FIX messages from remote applications. Synapse may operate as a FIX acceptor or as an initiator when receiving FIX messages. To enable the FIX transport listener, uncomment the following transport receiver configuration in the SYNAPSE_HOME/repository/conf/axis2.xml file.

<transportReceiver name="fix" class="org.apache.synapse.transport.fix.FIXTransportListener"> <parameter name="non-blocking">true</parameter> </transportReceiver>

Now you may expose proxy services over the FIX transport by setting the "transports" attribute on the proxy service element to "fix":

<proxy name="MyFIXService" transports="fix"> ... </proxy>

It's also possible to expose a proxy service on FIX transport and several other transports. Simply specify the required transports as a space-separated list in the "transports" attribute:

<proxy name="MyFIXService" transports="fix http https"> ... </proxy>

Exposing a proxy service over FIX is not sufficient. We must configure the proxy service with FIX session and connection details. This is done by setting a number of parameters on the proxy service configuration. Please refer sample 257 for an example that demonstrates how this is done. Following table lists all the FIX-specific parameters that can be set on a Synapse proxy service.

Parameter Name Description/Example Required Default
transport.fix.AcceptorConfigURL If a proxy service wishes to listen to incoming FIX messages from a remote initiator, then Synapse needs to start a FIX acceptor. This parameter specifies the URL to a file, which contains the FIX configuration for the acceptor. The URL may point to a file in the local file system or a remotely hosted file accessible over a standard protocol such as HTTP. The file itself should be a standard .cfg file, typically used to configure FIX acceptors in Quickfix/J. Parameter is required if the proxy service should receive FIX traffic as an acceptor.
<parameter name="transport.fix.AcceptorConfigURL">file:conf/acceptor.cfg</parameter>
 No N/A
transport.fix.InitiatorConfigURL If a proxy service wishes to listen to incoming FIX messages from a remote acceptor, then Synapse needs to start a FIX initiator. This parameter specifies the URL to a file, which contains the FIX configuration for the initiator. The URL may point to a file in the local file system or a remotely hosted file accessible over a standard protocol such as HTTP. The file itself should be a standard .cfg file, typically used to configure FIX initiators in Quickfix/J. Parameter is required if the proxy service should receive FIX traffic as an initiator.
<parameter name="transport.fix.InitiatorConfigURL">file:conf/initiator.cfg</parameter>
 No N/A
transport.fix.AcceptorMessageStore The type of message store to be used with the acceptor. Allowed values for this parameter are 'file', 'jdbc', 'memory' and 'sleepycat'. Additional parameters required to configure the message store should be specified in the acceptor configuration file. Ignored if the proxy service is not operating in the acceptor mode.
<parameter name="transport.fix.AcceptorMessageStore">file</parameter>
 No memory
transport.fix.InitiatorMessageStore The type of message store to be used with the initiator. Allowed values for this parameter are 'file', 'jdbc', 'memory' and 'sleepycat'. Additional parameters required to configure the message store should be specified in the initiator configuration file. Ignored if the proxy service is not operating in the initiator mode.
<parameter name="transport.fix.InitiatorMessageStore">file</parameter>
 No memory
transport.fix.AcceptorLogFactory Specifies the type of FIX log factory to be used to log messages going through the acceptor. FIX messages are logged without putting them in SOAP envelopes at this level. Accepted values are 'console', 'file' and 'jdbc'. If not specified no logging will be done at the transport level. Additional parameters required to configure each of the lof factories should be specified in the acceptor configuration file. Ignored if the proxy service is not operating in the acceptor mode.
<parameter name="transport.fix.AcceptorLogFactory">file</parameter>
 No N/A
transport.fix.InitiatorLogFactory Specifies the type of FIX log factory to be used to log messages going through the initiator. FIX messages are logged without putting them in SOAP envelopes at this level. Accepted values are 'console', 'file' and 'jdbc'. If not specified no logging will be done at the transport level. Additional parameters required to configure each of the lof factories should be specified in the initiator configuration file. Ignored if the proxy service is not operating in the initiator mode.
<parameter name="transport.fix.InitiatorLogFactory">file</parameter>
 No N/A
transport.fix.UseThreadedConnectors Use multi-threaded acceptors and initiators. Setting this parameter to true is equivalent to setting both transport.fix.UseThreadedAcceptor and transport.fix.UseThreadedInitiator to true.
<parameter name="transport.fix.UseThreadedConnectors">true</parameter>
 No false
transport.fix.UseThreadedAcceptor Run the FIX acceptor in the multi-threaded mode. That is use separate threads for each acceptor session. Allowed values are true or false. Has more priority than transport.fix.UseThreadedConnectors.
<parameter name="transport.fix.UseThreadedAcceptor">true</parameter>
 No false
transport.fix.UseThreadedInitiator Run the FIX initiator in the multi-threaded mode. That is use separate threads for each initiator session. Allowed values are true or false. Has more priority than transport.fix.UseThreadedConnectors.
<parameter name="transport.fix.UseThreadedInitiator">true</parameter>
 No false
transport.fix.UseThreadedInitiator Run the FIX initiator in the multi-threaded mode. That is use separate threads for each initiator session. Allowed values are true or false.
<parameter name="transport.fix.UseThreadedInitiator">true</parameter>
 No false
transport.fix.ProcessSingleThreaded Mediate all received FIX messages on the same thread used by Quickfix/J to perform network I/O. Use this parameter to ensure that Synapse mediates the FIX messages in the received order. By default Synapse uses a pool of threads to process received FIX messages in parallel, which may change their order. Also, using a single thread has the side effect of forcing the FIX transport to control the request intake based on how fast Synapse processes them. In some cases this turns out to be the preferred behavior.
<parameter name="transport.fix.ProcessSingleThreaded">true</parameter>
 No false
transport.fix.AcceptorSingleThreaded Mediate all FIX messages received as an acceptor on the same thread used by Quickfix/J to perform network I/O. This has more priority over transport.fix.ProcessSingleThreaded.
<parameter name="transport.fix.AcceptorSingleThreaded">true</parameter>
 No false
transport.fix.InitiatorSingleThreaded Mediate all FIX messages received as an initiator on the same thread used by Quickfix/J to perform network I/O. This has more priority over transport.fix.ProcessSingleThreaded.
<parameter name="transport.fix.InitiatorSingleThreaded">true</parameter>
 No false
transport.fix.AcceptorSessionEventHandler Use this parameter to register a custom acceptor session event handler. Can be used when it's required to inject some custom logic into the way how the FIX transport handles key FIX session events. The value of this parameter should be the full qualified name of a class that implements the org.apache.synapse.transport.fix.SessionEventHandler interface.
<parameter name="transport.fix.AcceptorSessionEventHandler">foo.bar.MyEventHandler</parameter>
 No N/A
transport.fix.InitiatorSessionEventHandler Use this parameter to register a custom initiator session event handler. Can be used when it's required to inject some custom logic into the way how the FIX transport handles key FIX session events. The value of this parameter should be the full qualified name of a class that implements the org.apache.synapse.transport.fix.SessionEventHandler interface.
<parameter name="transport.fix.AcceptorSessionEventHandler">foo.bar.MyEventHandler</parameter>
 No N/A

FIX Transport Sender

To enable the FIX transport sender, uncomment the following transport sender configuration in the SYNAPSE_HOME/repository/conf/axis2.xml file.

<transportSender name="fix" class="org.apache.synapse.transport.fix.FIXTransportSender"> <parameter name="non-blocking">true</parameter> </transportSender>

To send a message using the FIX transport, define a Synapse endpoint with an address that starts with the prefix 'fix://'. The rest of the address should specify the target hostname, port and other FIX session settings. An example is shown below:

<endpoint> <address uri="fix://localhost:19876?BeginString=FIX.4.0&SenderCompID=SYNAPSE&TargetCompID=EXEC"/> </endpoint>

The above endpoint describes a FIX 4.0 session with the SenderCompID set to 'SYNAPSE' and the TargetCompID set to 'EXEC'. If this session already exists (created earlier by the proxy service), the message will be sent using that session. Otherwise, the FIX transport sender will create a new initiator session using the available session information and send the message using this new session.

Following list shows all the FIX session settings that can be configured at the endpoint level, as URL query parameters.

  • BeginString
  • SenderCompID
  • SenderSubID
  • SenderLocationID
  • TargetCompID
  • TargetSubID
  • TargetLocationID
  • DeliverToCompID
  • DeliverToSubID
  • DeliverToLocationID
  • SessionQualifier

The DeliverTo* fields will be actually set on the messages, as the messages are forwarded to the remote FIX endpoint.

There are several parameters that can be set at the proxy service level to configure the behavior of the FIX transport sender. A complete list is given below.

Parameter Name Description/Example Required Default
transport.fix.BeginStringValidation Use this parameter to enable BeginString validation for all outgoing FIX messages. That is the BeginString value currently set on the message (typically this is set by the original source application that sent the message to Synapse), must match with the BeginString field of the target FIX session. Allowed values are true or false.
<parameter name="transport.fix.BeginStringValidation">true</parameter>
 No false
transport.fix.DropExtraResponses Sometimes FIX endpoints respond to requests with multiple responses. This could be problematic, if Synapse received the original request via a protocol like HTTP. In situations such as these, this parameter can be used to force Synapse to only mediate the first response received from the remote endpoint and discard the others. Allowed values are true or false.
<parameter name="transport.fix.DropExtraResponses">true</parameter>
 No false
transport.fix.SendAllToInSequence In some integration scenarios it becomes necessary treat all received FIX messages (both requests and responses) as a single message stream and mediate them through the in-sequence of the proxy service. This parameter enables doing that. Allowed values are true or false.
<parameter name="transport.fix.SendAllToInSequence">true</parameter>
 No false
transport.fix.ResponseDeliverToCompID Configure the DeliverToCompID value that should be set on the response messages sent by the proxy service. To set the DeliverToCompID on requests, set the DeliverToCompID directly on the target FIX endpoint as a query parameter.
<parameter name="transport.fix.ResponseDeliverToCompID">APP</parameter>
 No N/A
transport.fix.ResponseDeliverToSubID Configure the DeliverToSubID value that should be set on the response messages sent by the proxy service. To set the DeliverToSubID on requests, set the DeliverToSubID directly on the target FIX endpoint as a query parameter.
<parameter name="transport.fix.ResponseDeliverToSubID">APP</parameter>
 No N/A
transport.fix.ResponseDeliverToLocationID Configure the DeliverToLocationID value that should be set on the response messages sent by the proxy service. To set the DeliverToLocationID on requests, set the DeliverToLocationID directly on the target FIX endpoint as a query parameter.
<parameter name="transport.fix.ResponseDeliverToLocationID">APP</parameter>
 No N/A

Mediating FIX Messages

The FIX transport converts all received messages into SOAP (XML). Therefore, you can treat a FIX message as any other XML message at the mediation level. You may use XPath to extract individual fields from the FIX messages, and use XSLT or XQuery to transform them into other formats. An example FIX message and its equivalent SOAP infoset as constructed by the FIX transport are shown below.

8=FIX.4.0[SOH]9=105[SOH]35=D[SOH]34=2[SOH]49=BANZAI[SOH]52=20080711-06:42:26[SOH]56=SYNAPSE[SOH]11=1215758546278[SOH]21=1[SOH]38=9000000040=154=155=DEL59=010=121
<message> <header> <field id="8">FIX.4.0</field> <field id="9">105</field> <field id="34">2</field> <field id="35">D</field> <field id="49">BANZAI</field> <field id="52">20080711-06:42:26</field> <field id="56">SYNAPSE</field> </header> <body> <field id="11">1215758546278</field> <field id="21">1</field> <field id="38">90000000</field> <field id="40">1</field> <field id="54">1</field> <field id="55">DEL</field> <field id="59">0</field> </body> <trailer> <field id="10">121</field> </trailer> </message>

Notice how the FIX header, body and trailer sections are grouped under separate parent XML elements. To extract the BeginString field (field no. 8), you may use the following XPath expression:

//header/field[@id='8']

Similarly to extract the value of field 55 from the FIX message body, you may use the following XPath expression:

//body/field[@id='55']

Representing FIX messages as XML enables you to use some of the most powerful mediation features of Synapse with FIX message flows. This includes content-based routing, message transformation and protocol switching.