FIX Adapter

Contents

Introduction
Setting FIX Adapter Properties
Adapter Ports And Schemas
Using the Adapter in a StreamBase Application
Configuration File Formats
Implementing a Custom Admin Message Interceptor Class
StreamBaseFIX-Specific Functionality
Typechecking and Error Handling
Suspend, Resume, Shutdown Behavior
Related Topics

Introduction

The TIBCO StreamBase® Adapter for FIX enables a StreamBase application to connect to a FIX venue, and to send and receive FIX messages. The FIX adapter is a single, bidirectional adapter that can both send and receive FIX messages. However, to facilitate its use in EventFlow diagrams, the adapter is represented as an Input adapter and an Output adapter, with separate icons in the StreamBase Studio Palette view. These icons can be used separately, or used as a pair that shares a single FIX connection (described below in Linking Input and Output adapters).

The FIX Input and Output adapters have the following capabilities:

  • FIX Output Adapter

    • Establishes a FIX connection (either as initiator or acceptor) to a target and creates one or more FIX sessions.

    • Converts incoming tuples from the application to FIX messages and sends them to the FIX target.

    • Optionally logs FIX message traffic between the adapter and the FIX target.

    • Optionally stores outgoing FIX messages in a file or database.

  • FIX Input Adapter

    • Can establish a FIX connection (either as initiator or acceptor) and create one or more FIX sessions. Alternatively, can be linked to an existing FIX Output adapter to share its FIX connection, as described in Linking Input and Output adapters.

    • Converts incoming application-level FIX messages from the target to tuples and sends them to the application. The adapter can be configured to route tuples from different message types to specific output ports. (For example, route all Cancel and Cancel/Replace messages to port 2.) Up to 10 ports can be configured for this purpose.

    • Optionally sends admin-level FIX messages to the application.

    • Can receive commands from the application to log on, log out, or reset individual sessions, or all sessions simultaneously.

    • Optionally logs FIX message traffic between the adapter and the FIX target.

The FIX Input and Output adapters each have their own set of input and output ports, the fields for which are defined later in this document. In addition, each adapter has its own adapter properties. These are described in Setting FIX Adapter Properties.

FIX Engines

To connect to FIX targets, the FIX Input and Output adapters use the services of one of several FIX engines. As of this release, the adapters can use one of the following as a FIX engine:

  • StreamBaseFIX, a high-speed, low-latency engine derived from the B2Bits Antenna FIX engine from EPAM Systems.

  • QuickFIX/J 1.4.0

StreamBase includes a copy of the QuickFIX/J libraries, so you can use the adapters out of the box with this engine.

A copy of the StreamBaseFIX engine is also included, but you will need a separate license to use it — see your StreamBase representative for details.

Linking Input and Output adapters

While it is possible to use the FIX Input adapter individually to receive FIX messages, or to use the FIX Output adapter individually to send FIX messages, it is usually more useful to combine their capabilities to both send and receive messages in the same FIX session. To accommodate this, the FIX adapter provides the capability to link an FIX Input adapter with an FIX Output adapter so that they share the same FIX connection and sessions. In EventFlow applications, having separate Input and Output adapter icons that share a connection (instead of a single bidirectional adapter icon) helps minimize the need for loops in the EventFlow logic.

To link an Input and FIX Output adapters so that they share a single FIX connection, follow these steps:

  • Create an FIX Output adapter and configure it to connect to a FIX target, as described in Adapter Properties Tab. In this Output adapter's General tab, note the value of the Name parameter. For clarity set this value to something other than the default name. It is important to make sure that this name is unique inside your application, or errors will occur at runtime. For this example, we will use the name MyFIXOutputAdapter.

  • Create an instance of the FIX Input adapter.

  • In this new adapter's Adapter Properties tab, make sure the Share A FIX Connection With An Output Adapter option is checked.

  • In the Share With The FIX Output Adapter Named field, enter the name of your FIX Output adapter (MyFIXOutputAdapter in our example).

  • Notice that checking the Share A FIX Connection option disables several other settings on the Adapter Properties tab and on the Trace Management tab. This is because those settings are now shared from the named Output adapter.

Setting FIX Adapter Properties

Settings are used to control most of the behavior of the adapter. The settings are grouped under several tabs in the Properties view in StreamBase Studio.

Input Adapter Properties

General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Class name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this adapter starts as part of the JVM engine that runs this EventFlow module. If this field is set to No or to a module parameter that evaluates to false, the adapter instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

This section describes the Adapter Properties tab for FIX Input adapters. See Adapter Properties Tab below for FIX Output adapters.

Share A FIX Connection With An Output Adapter

Default: check box cleared (false)

Specifies that this Input adapter is linked to an existing FIX Output adapter and uses the FIX connection established by an existing FIX Output adapter.

Share With The FIX Output Adapter Named

Default: none

When Share A FIX Connection With An Output Adapter is selected, the FIX Output adapter named in this field shares its FIX connection with the present Input adapter, thereby linking them.

Note

This control is dimmed and unavailable unless Share A FIX Connection With An Output Adapter is selected.

Fix Engine To Use

Default: QuickFIX/J

Specifies the FIX engine to use to establish a connection to the target. In the current release of the main FIX adapter, this can be either QuickFIX/J or StreamBaseFIX.

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

FIX Configuration File

Default: none

The name of the configuration file to feed to the underlying FIX engine. The format of this file depends on the value of Fix Engine To Use. See Configuration File Formats for more information.

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

Logon When Application Starts

Default: check box selected (true)

Specifies whether the FIX connections should be started when the application starts. If this option is left cleared (false), the adapter does not attempt to establish the configured connections until a Connect command is issued (see Input Ports for more information on the Connect command).

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

Field Name Map File

Default: none

Specifies the name of an optional file that contains field name mappings.

By default, when a FIX message is received, the output schema of the Input adapter is examined and all fields that are found to have an identically-named field in the FIX message are set to the value of that FIX field. Similarly, when sending a FIX message, each field in the incoming tuple has its value copied to the identically-named outgoing FIX message field.

However, you might instead prefer to have the value of a FIX field set in a StreamBase field of a different name (or vice-versa). Do so by specifying a name map file, which contains a set of FIX field to StreamBase field mappings. See Field Name Map File for the format of this file.

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

FIX Admin Message Interceptor Class

Default: none

Specifies the name of an optional class that implements one of the following interfaces:

com.streambase.sb.adapter.fix.engine.quickfixj.QFJAdminMessageInterceptor
com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor

Choose the interface that matches your underlying FIX engine. This interface is responsible for setting custom fields on outgoing FIX admin messages. See Implementing a Custom Admin Message Interceptor Class for details on how to use this functionality.

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

FIX Application Message Interceptor Class

Default: none

Specifies the name of an optional class that implements one of the following interfaces:

com.streambase.sb.adapter.fix.engine.quickfixj.QFJAppMessageInterceptor
com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor (Note that this is the same interface as above; when this setting is used, your implementation will be called for application-level messages as well.)

Choose the interface that matches your underlying FIX engine. This interface is responsible for setting custom fields on outgoing FIX application messages. See Implementing a Custom Admin Message Interceptor Class for details on how to use this functionality -- the only difference being that in the case of QuickFIX/J the com.streambase.sb.adapter.fix.engine.quickfixj.QFJAppMessageInterceptor has a method called onAppMessage(SessionID id, Message msg) instead of onAdminMessage(SessionID id, Message msg).

Note

This control is dimmed and unavailable when Share A FIX Connection With An Output Adapter is selected.

Perform User-Level Logon Procedure (BE / BF FIX messages)

Default: check box cleared (false)

Some FIX venues require initiators to perform a secondary logon procedure after the regular Logon (A) messages have been exchanged. This is done by exchanging a series of UserRequest (BE) and UserResponse (BF) messages to establish the proper credentials. Selecting this option will cause the adapter to automatically perform this procedure, using the credentials provided in the configuration file. These credentials are expected to be present in the form of the following settings:

  • For QuickFIX/J

    • Username=MyUsername

    • Password=MyCurrentPassword

    • NewPassword=MyNextPassword

  • For StreamBaseFIX

    • <username>MyUsername</username>

    • <password>MyCurrentPassword</password>

    • <new-password>MyNextPassword</new-password>

Note that the values above are required to be present when the adapter is configured to perform BE/BF logon procedures.

Use SenderSubID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the session from which the FIX message was received. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the SenderSubID (tag 50) field will also be used to identify the session.

Use SenderLocationID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the session from which the FIX message was received. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the SenderLocationID (tag 142) field will also be used to identify the session.

Use TargetSubID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the session from which the FIX message was received. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the TargetSubID (tag 57) field will also be used to identify the session.

Use TargetLocationID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the session from which the FIX message was received. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the TargetLocationID (tag 143) field will also be used to identify the session.

Port Management Tab

Add Port For Admin Messages

Default: false

If this option is checked, an output port is added to the adapter to receive all incoming admin-level FIX messages. See Administration-Level FIX Message Routing Port for details.

Add Command Input Port

Default: false

If this option is checked, an input port is added to allow the application to send commands to the adapter. The schema used by this port, along with the available commands are described in Input Ports.

Message Routing Map

Default: none

Use the Message Routing Map to define up to 10 output ports.

By default, the adapter routes all incoming application-level FIX messages to the first output port. However, you can add additional output ports to the adapter, to each of which are routed incoming FIX messages of specified types, as identified by the value of FIX tag 35 (MsgType).

Use the message routing map to tell the adapter how you would like to have the incoming FIX messages routed. Add one row for each output port you want to add. Thus, the first row of the map table specifies the first output port, the second row specifies the second output port, and so on. Remember that if you check the Add Port for Admin Messages control, the admin port is always the last port added to the adapter, and is not represented in the Message Routing Map table.

The following example map sends all messages to output port 1, except for messages of type D (New Order - Single), which go to output port 2, and message types F (OrderCancelRequest), G (OrderCancelReplaceRequest), q (OrderMassCancelRequest), and u (CrossOrderCancelRequest), which are routed to output port 3. Use a comma-delimited list to specify multiple message types.

Note

This example shows port 1 with a value of * to specify all other message types. This illustrates the fact that port 1 is always assumed to have a value of *, regardless of what you actually type in the Value column for that port, or even when the map is empty. This is a corollary to the rule that all application-level message types not specified in the routing map go to port 1.

Note

If a message type appears in more than one entry, a typecheck exception is issued.

Edit Schemas Tab

The use of the standard Edit Schema tab is described in the Defining Input Streams page of the Authoring Guide.

For every port you specify in the Message Routing Map, you must define its schema in the Edit Schemas tab. Remember that even if the routing map is empty, there is still one default output port for application-level messages. This means you must define at least one schema in this tab. The schemas do not need to be the same for every port, but there is one mandatory field that must be present in each schema. This field is:

  • MsgType (string)

If you plan on having the adapter act as a FIX acceptor, or connect to more than one venue at a time by defining multiple sessions in the configuration file, you will also need the following fields:

  • BeginString (string)

  • SenderCompID (string)

  • TargetCompID (string)

Those fields are necessary to help identify the session from which incoming FIX messages originate and to which outgoing FIX messages are destined.

Note

If necessary, you may also use the following fields to further differentiate sessions:

  • SenderSubID (string)

  • SenderLocationID (string)

  • TargetSubID (string)

  • TargetLocationID (string)

See Use SenderSubID Field To Identify Session for more details.

Every other field you define in the schema is expected to have a corresponding field in the incoming FIX messages directed to that port. When the adapter receives such a FIX message, it iterates through all the fields in your schema, gets the corresponding value in the FIX field, and sets the tuple's field to that value. Any field in the FIX message that has no corresponding field in the schema is ignored and is not passed on to the application. In this way, you can maximize the efficiency of your application by only defining the FIX fields of interest in your schema.

The adapter uses an algorithm to identify a corresponding FIX field, given a StreamBase field. That algorithm is as follows:

  • If a name map was specified for the adapter (see Field Name Map File), the map is checked for an entry containing the StreamBase field. If there is such an entry, the FIX field specified in that mapping is used.

  • If no match is found in the name map (or if no name map was specified), the FIX dictionary is queried for a FIX field with the same name as the StreamBase field. If a match is found, that FIX field is used.

  • If no match is found, the StreamBase field is examined to see if its name conforms to the pattern __tag_nnn, where nnn is an integer. If it does, the FIX dictionary is queried for a FIX field with tag nnn. If a match is found, that FIX field is used.

  • If no match has been found at this point, a warning is issued at the console when the application starts and the unmatched StreamBase field remains null when a FIX message is received.

In addition, you can define the special field __FIXMessageBody as a blob. If this field is present in the schema, the FIX Input adapter places the entire incoming FIX message verbatim in the blob field. Conversely, if this field is present and non-null in an outgoing tuple, the FIX Output adapter uses the FIX message contained therein (again as a verbatim FIX message, which is to say a string of SOH-delimited tag=value pairs in accordance with the FIX specification) to initialize the outgoing message, then uses the other fields in the tuple to overwrite the corresponding fields in the FIX message.

This mechanism can be useful in cases where all you need to do is relay a FIX message verbatim to another party. For example, you might use a schema similar to the following, setting the SenderCompID and TargetCompID fields to match the intended recipient instead of the original sender:

Field Type Mapping

Because the FIX protocol internally uses strings to represent the value of every field, you may specify all fields in your schema to be of type string (with the exception of repeating groups; see the NumInGroup FIX data type in the list below). However, to get more type safety and better ease of use in your application you may use the following type mappings between FIX and StreamBase fields:

FIX Data Type StreamBase Data Type
String string
MultipleValueString string
Char string
Currency string
Exchange string
Country string
MonthYear string
Price double
Amt double
Qty double
Float double
Percentage double
PriceOffset double
DayOfMonth int
SeqNum int
Length int
Int (FIX 4.3 and newer) int
Int (FIX 4.2 and older) int, unless this field represents what is referred to in later FIX versions as NumInGroup — that is, the cardinality of a FIX repeating group. In such cases, you should use a list(tuple), as described for the NumInGroup type below.
NumInGroup list(tuple), where the tuple contains one or more of the fields in this repeating group. Each instance of the repeating group will be placed in a tuple in the list. See Accessing Repeating Groups for more details.
Boolean boolean
Data blob
UtcDate timestamp
UtcDateOnly timestamp
LocalMktDate timestamp
UtcTimeOnly timestamp — this contains the appropriate time of day; the date will be 01/01/1970.
UtcTimeStamp timestamp
Time timestamp — this contains the appropriate time of day; the date will be 01/01/1970.
Accessing Repeating Groups

Access to FIX repeating group fields is done through fields of type List. Let us consider the example of a FIX 4.4 NewOrderSingle (MsgType=D) message and its NoPartyIDs (tag 453) group (which itself contains a nested repeating group: NoPartySubIDs, tag=802.) The group contains the following fields:

  • PartyID (448)

  • PartyIDSource (447)

  • PartyRole (452)

  • NoPartySubIDs (802)

    • PartySubID (523)

    • PartySubIDType (803)

To access all these fields in your StreamBase application you should start by creating a named schema (let's call it NoPartySubIDsGroup) with the following fields:

  • PartySubID (string)

  • PartySubIDType (int)

This schema will hold the values of each instance of the inner repeating group. You will also need another named schema (NoPartyIDsGroup) to hold the values of each instance of the top-level group:

  • PartyID (string)

  • PartyIDSource (char)

  • PartyRole (int)

  • NoPartySubIDs (list of NoPartySubIDsGroup)

Finally, you will need to add the following field to your top-level schema for the output port which is to receive messages of type D:

  • NoPartyIDs (list of NoPartyIDsGroup)

Once you have these schemas and fields defined you are ready to access the values contained therein using standard List and Tuple expression idioms, such as NoPartyIDs[2].NoPartySubIDs[3].PartySubID. Similarly you may also send messages containing repeating group data by creating a list of tuples (with an appropriate named schema), setting the inner fields' values and assigning the list to the corresponding field in your tuple.

Note

When creating your schema for a repeating group you do not have to include every field or the group in your schema; however you should always include its first field and position it as the first field of your schema.

Trace Management Tab

For debugging purposes, it can be useful to see the actual FIX messages being exchanged between the adapter and the FIX target. The settings on this tab allow you to control which incoming and outgoing messages you would like the adapter to log.

Note

When FIX message logging is enabled, in the default configuration, messages appear in the Console view in Studio, or on the StreamBase Server terminal, for command-line launches. In Studio, the Console view is generally small. When using FIX message logging, you can instead prepare a launch configuration that directs the output of the run session to a file.

By default, all incoming FIX messages are logged. However, to reduce clutter, you can select which FIX message types you would like the adapter to log by specifying a message type filter. This filter can either describe the message types you want logged, or those you do not want logged. For example, you may wish to only see messages of type D and F, or see all messages except heartbeats (type 0).

To exclude all FIX heartbeat messages (type 0) from the log, use the following settings:

FIX Adapter Trace Management Tab Setting
Log incoming FIX Messages selected
Incoming Message Filter Type Exclude
Incoming Message Filter 0
Log Outgoing FIX Messages selected
Outgoing Message Filter Type Exclude
Outgoing Message Filter 0

Note

Unless noted otherwise, the settings on this tab for the FIX Input adapter are disabled if you check the Share A FIX Connection With An Output Adapter option on the Adapter Properties tab. In that case, trace management settings are taken from the linked FIX Output adapter. (This note only applies to the Trace Management tab for the FIX Input adapter, and not to the same tab of the FIX Output adapter.)

Log Incoming FIX Messages

Default: false

When checked, this option specifies that the adapter is to log incoming FIX messages to the console. Note that this setting does not affect any console- or file-based logging performed by the underlying FIX engine. Furthermore because writing to the console is a costly operation it should be used only for diagnostic purposes.

Incoming Message Filter Type

Default: Include

This tells the adapter whether it should treat the incoming message type filter as a list of messages to log (Include), or a list of messages not to log (Exclude.)

Incoming Message Filter

Default: none

Contains a comma-separated list of message types (that is, the value of FIX tag 35) on which to filter. If left empty, it is taken to mean all messages.

Note

Because leaving this setting empty means all messages, the behavior is different, depending on the setting of Incoming Message Filter Type. If it is Include, all messages are logged. If it is Exclude, no messages are logged (because all messages are excluded).

Log Outgoing FIX Messages

Default: false

When checked, this option specifies that the adapter is to log outgoing FIX messages to the console. Note that this setting does not affect any console- or file-based logging performed by the underlying FIX engine. Furthermore because writing to the console is a costly operation it should be used only for diagnostic purposes.

Outgoing Message Filter Type

Default: Include

This tells the adapter whether it should treat the outgoing message type filter as a list of messages to log (Include), or a list of messages not to log (Exclude.)

Outgoing Message Filter

Default: none

Contains a comma-separated list of message types (that is, the value of FIX tag 35) on which to filter. If left empty, it is taken to mean all messages.

Note

Because leaving this setting empty means all messages, the behavior is different, depending on the setting of Outgoing Message Filter Type. If it is Include, all messages are logged. If it is Exclude, no messages are logged (because all messages are excluded).

Report Profiling Data

Default: false

Do not enable this option in a production system. Use this option in collaboration with StreamBase Technical Support to troubleshoot performance issues in your application.

When set to true, the adapter collects data on how long it takes to process messages and regularly report the results to the console. Reported data includes the average, standard deviation, minimum and maximum times (in microseconds) taken to receive each FIX message, convert it into a tuple and send it to the application (or vice-versa for the Output adapter).

Note

Even when an Input adapter is linked to an Output adapter, this setting is applied independently. In other words, the setting for the Output adapter does not override the setting for the Input adapter.

When set to true, the following FIX fields are used by the adapter for internal accounting. If your site's FIX connection requires any of these fields to be set to specific values for proper operation, then do not enable this option:

OnBehalfOfSubID (116)
OnBehalfOfLocationID (144)
DeliverToCompID (128)
DeliverToSubID (129)
DeliverToLocationID (145)
Reporting Interval (in # of messages)

Default: 10000

When Report Profiling Data is set to true, this setting should be set to the number of FIX messages after which performance data should be reported. A positive integer is expected.

Note

Even when an Input adapter is linked to an Output adapter, this setting is applied independently. In other words, the setting for the Output adapter does not override the setting for the Input adapter.

Log Level

Default: INFO

Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Output Adapter Properties

General Tab

The General tab for the FIX Output adapter is the same as for the FIX Input adapter, described above in General Tab

Adapter Properties Tab

This section describes the Adapter Properties tab for FIX Output adapters. See Adapter Properties Tab above for FIX Input adapters.

Fix Engine To Use

Default: QuickFIX/J

Specifies the FIX engine to use to establish a connection to the target. In the current release, this can be QuickFIX/J or StreamBaseFIX.

Note

This option is required.

FIX Configuration File

Default: none

The name of the configuration file to pass to the underlying FIX engine. The format of this file depends on the value of the Fix Engine To Use option. See Configuration File Formats for more information.

Note

This option is required.

Logon When Application Starts

Default: check box selected (true)

Specifies whether the FIX connections should be started when the application starts. If this option is cleared (false) the adapter does not attempt to establish the configured connection(s) until a Connect command is issued (see Input Ports for more information on the Connect command).

Field Name Map File

Default: none

This field is the same for output adapters as for input adapters, described above at Field Name Map File.

FIX Admin Message Interceptor Class

Default: none

Specifies the name of an optional class that implements one of the following interfaces:

com.streambase.sb.adapter.fix.engine.quickfixj.QFJAdminMessageInterceptor
com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor

Choose the interface that matches your underlying FIX engine. This interface is responsible for setting custom fields on outgoing FIX admin messages. See Implementing a Custom Admin Message Interceptor Class for details on how to use this functionality.

Note

This control is dimmed when Share A FIX Connection With An Output Adapter is selected.

FIX Application Message Interceptor Class

Default: none

Specifies the name of an optional class that implements one of the following interfaces:

com.streambase.sb.adapter.fix.engine.quickfixj.QFJAppMessageInterceptor
com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor (Note that this is the same interface as above; when this setting is used, your implementation will be called for application-level messages as well.)

Choose the interface that matches your underlying FIX engine. This interface is responsible for setting custom fields on outgoing FIX application messages. See Implementing a Custom Admin Message Interceptor Class for details on how to use this functionality -- the only difference being that in the case of QuickFIX/J the com.streambase.sb.adapter.fix.engine.quickfixj.QFJAppMessageInterceptor has a method called onAppMessage(SessionID id, Message msg) instead of onAdminMessage(SessionID id, Message msg).

Perform User-Level Logon Procedure (BE / BF FIX messages)

Default: check box cleared (false)

Some FIX venues require initiators to perform a secondary logon procedure after the regular Logon (A) messages have been exchanged. This is done by exchanging a series of UserRequest (BE) and UserResponse (BF) messages to establish the proper credentials. Selecting this option will cause the adapter to automatically perform this procedure, using the credentials provided in the configuration file. These credentials are expected to be present in the form of the following settings:

  • For QuickFIX/J

    • Username=MyUsername

    • Password=MyCurrentPassword

    • NewPassword=MyNextPassword

  • For StreamBaseFIX

    • <username>MyUsername</username>

    • <password>MyCurrentPassword</password>

    • <new-password>MyNextPassword</new-password>

Note that the values above are required to be present when the adapter is configured to perform BE/BF logon procedures.

Use SenderSubID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the FIX session to which the message should be sent. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the SenderSubID (tag 50) field will also be used to identify the session.

Use SenderLocationID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the FIX session to which the message should be sent. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the SenderLocationID (tag 142) field will also be used to identify the session.

Use TargetSubID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the FIX session to which the message should be sent. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the TargetSubID (tag 57) field will also be used to identify the session.

Use TargetLocationID Field To Identify Session

Default: check box cleared (false)

By default, if more than one FIX session is configured the adapter will use the values of the BeginString, SenderCompID and TargetCompID fields to uniquely identify the FIX session to which the message should be sent. However, some FIX engines (such as QuickFIX/J) allow other fields to further differentiate a session. If this option is set to true, the value of the TargetLocationID (tag 143) field will also be used to identify the session.

Trace Management Tab

The Trace Management tab for the FIX Output adapter is the same as for FIX Input adapters, described above at Trace Management Tab.

Concurrency Tab

The Concurrency tab for the FIX Output adapter is the same as for the FIX Input adapter, described above in Concurrency Tab

Adapter Ports And Schemas

Input Adapter Ports

Output Ports

The FIX Input adapter has a variable number of output ports, depending on its Properties configuration, described above at Adapter Properties Tab.

Application-level FIX Message Routing Ports

The adapter always has at least one output port, which is the default routing port for application-level FIX messages. When the adapter receives application-level FIX messages, it converts their contents to StreamBase tuples and sends them to this default output port (unless otherwise specified with the Message Routing Map option).

The schema for application-level message ports is left to the user to define. The fields in this schema determine what FIX fields are passed to the StreamBase application. See Edit Schemas Tab for details on defining a schema for output ports.

Depending on the specification of the Message Routing Map option, there is at least one and as many as ten output ports dedicated to incoming FIX application-level message routing. These ports always appear first.

Administration-Level FIX Message Routing Port

If the Add Port For Admin Messages option is enabled, one more port is added to receive admin-level FIX messages. The schema for this port is pre-set by the adapter, and is described in the following table:

Field Name Field Type Description
MsgType string Value of MsgType FIX field (tag=35). Used by all admin messages.
SenderCompID string Value of SenderCompID FIX field (tag=49). Used by all admin messages.
TargetCompID string Value of TargetCompID FIX field (tag=56). Used by all admin messages.
SenderSubID string Value of SenderSubID FIX field (tag=50). Used by all admin messages.
TargetSubID string Value of TargetSubID FIX field (tag=57). Used by all admin messages.
SenderLocationID string Value of SenderLocationID FIX field (tag=142). Used by all admin messages.
TargetLocationID string Value of TargetLocationID FIX field (tag=143). Used by all admin messages.
ResetSeqNumFlag boolean Value of ResetSeqNumFlag FIX field (tag=114). Used by Logon (A) messages.
RawDataLength int Value of RawDataLength FIX field (tag=95). Used by Logon (A) messages.
RawData string Value of RawData FIX field (tag=96). Used by Logon (A) messages.
TestReqID string Value of TestReqID FIX field (tag=112). Used by Heartbeat (0) and Test Request (1) messages.
BeginSeqNo int Value of BeginSeqNo FIX field (tag=7). Used by Resend Request (2) messages.
EndSeqNo int Value of EndSeqNo FIX field (tag=16). Used by Resend Request (2) messages.
RefSeqNum int Value of RefSeqNum FIX field (tag=4). Used by Reject (3) messages.
RefTagID int Value of RefTagID FIX field (tag=371). Used by Reject (3) message.
RefMsgType string Value of RefMsgType FIX field (tag=372). Used by Reject (3) messages.
SessionRejectReason int Value of SessionRejectReason FIX field (tag=373). Used by Reject (3) messages.
Text string Value of Text FIX field (tag=58). Used by Reject (3) and Logout (5) messages.
EncodedTextLen int Value of EncodedTextLen FIX field (tag=354). Used by Reject (3) and Logout (5) messages.
EncodedText blob Value of EncodedText FIX field (tag=355). Used by Reject (3) and Logout (5) messages.
GapFillFlag boolean Value of GapFillFlag FIX field (tag=123). Used by Sequence Reset (4) messages.
NewSeqNo int Value of NewSeqNo FIX field (tag=36). Used by Sequence Reset (4) messages.
__ExtraInfo string This field can contain additional information not available in the incoming FIX message, or may describe an admin-level type of event that does not have an associated FIX message. For example, in the case of abrupt disconnection of the FIX target, a tuple is generated that contains the string Disconnect. Because there was no corresponding FIX message, all other fields except for SenderCompID and TargetCompID are null in this instance.

Similarly, in response to a ConnectionStatus command (described below) this field will be set to a value of Connected or Disconnected.

At startup time, once the initialization of each configured FIX session has completed, a tuple will be emitted with this field set to "SessionReady".

Note

When this field is non-null, the values for SenderCompID and TargetCompID will be set from the perspective of the session (that is, TargetCompID is set to your counterparty's name) whereas when this field is null — that is, the tuple represents an actual incoming FIX message — those fields will be set from the perspective of the counterparty (that is, TargetCompID is set to your own party's name).

__SessionConfig list<tuple> This is used when a GetSessionConfiguration command is used (described below). The list represents all the configuration settings used by the named session. Each tuple in the list includes a Name field and a Value field to represent each setting.

Input Ports

By default, the FIX Input adapter has no input ports. If the Add Command Input Port option is enabled, an input port is created to allow applications to send commands to the adapter, such as performing a reset of a FIX session.

The schema for this port is expected to contain the following fields:

Field Name Field Type Field Description
Command string Always required. Should contain the name of the command to execute (see below for a list of available commands).
BeginString string Only required if the adapter is configured to connect to more than one session. Should contain the value of the FIX BeginString (tag=8) field, such as FIX.4.3. This, along with the SenderCompID and TargetCompID fields (see below) is used to uniquely identify the session to which a command applies.
SenderCompID string Only required if the adapter is configured to connect to more than one session. Should contain the value of the FIX SenderCompID (tag=49) field. This, along with the BeginString and TargetCompID fields (see below) is used to uniquely identify the session to which a command applies.
TargetCompID string Only required if the adapter is configured to connect to more than one session. Should contain the value of the FIX TargetCompID (tag=56) field. This, along with the BeginString and BeginCompID fields (see below) is used to uniquely identify the session to which a command applies.
BeginSeqNo int Only required for the SetSenderMsgSeqNum and SetTargetMsgSeqNum commands, where it should contain the new message sequence number to use. Also required for the ReplayMessages command, where it should contain the sequence number of the first message to replay from the message store.
EndSeqNo int Only required for the ReplayMessages command, where it should contain the sequence number of the last message to replay from the message store.
Log (Optional) Tuple A tuple containing information for the setLogLevel command.
Log.Level String Required when Log tuple is present, this represents the new log level to set for this adapter. Available values are 'OFF', 'ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE', and 'ALL'.
Log.LogIncomingFIXMessages Boolean Optional field to determine if the adapter should log incoming FIX messages. If this field is not present or null the current value is used.
Log.IncomingFIXMessagesFilterType String Optional field to set the type of filter used when filtering incoming FIX messages. Available values are 'Include' and 'Exclude'. If this field is not present or null the current value is used.
Log.IncomingFIXMessagesFilter String Optional field to set the FIX messages to filter when filtering incoming FIX messages. If this field is not present or null the current value is used.
Log.LogOutgoingFIXMessages Boolean Optional field to determine if the adapter should log outgoing FIX messages. If this field is not present or null the current value is used.
Log.OutgoingFIXMessagesFilterType String Optional field to set the type of filter used when filtering outgoing FIX messages. Available values are 'Include' and 'Exclude'. If this field is not present or null the current value is used.
Log.OutgoingFIXMessagesFilter String Optional field to set the FIX messages to filter when filtering outgoing FIX messages. If this field is not present or null the current value is used.

In addition, in cases where SenderCompID and TargetCompID are not sufficient to identify a session, the following optional fields can be added to the schema (see Use SenderSubID Field To Identify Session):

Field Name Field Type Field Description
SenderSubID string Value of FIX tag=50.
SenderLocationID string Value of FIX tag=142.
TargetSubID string Value of FIX tag=57.
TargetLocationID string Value of FIX tag=143.

Depending on the command to be sent, different fields will need to be filled.

Available commands include:

  • Connect: Establish a connection and log on to all configured FIX sessions.

    Requires the following field to be filled:

    • Command: Set to the value Connect.

      Note

      This command is only meaningful if the Logon When Application Starts setting was left cleared (false) since the connection is otherwise automatically established when the application starts. See Logon When Application Starts.

      Note

      Once the configured connections are successfully started, further invocations of this command will be ignored.

      Once the configured connections are successfully started, further invocations of this command are ignored.

  • Logon: Log on to the specified FIX session.

    Requires the following fields to be filled:

    • Command: Set to the value Logon.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Logon All: Log on to all configured FIX sessions.

    Requires the following fields to be filled:

    • Command: Set to the value LogonAll.

  • Logout: Log out of the specified FIX session.

    Requires the following fields to be filled:

    • Command: Set to the value Logout.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Logout All: Log out of all configured FIX sessions.

    Requires the following fields to be filled:

    • Command: Set to the value LogoutAll.

  • Connection Status: Issue a Connection Status tuple for the specified FIX session. The status tuple will be emitted on the Input adapter's Admin port (see Administration-Level FIX Message Routing Port). The status tuple will contain a non-null value in its __ExtraInfo field of either Connected or Disconnected. The SenderCompID and TargetCompID fields will also be set.

    Requires the following fields to be filled:

    • Command: Set to the value ConnectionStatus.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Connection Status All: Report on the connection status of all configured FIX sessions. One status tuple will be emitted for each session.

    Requires the following fields to be filled:

    • Command: Set to the value ConnectionStatusAll.

  • Reset: Reset specified FIX session (Logout, reset incoming and outgoing message sequence numbers to 1, logon again.)

    Requires the following fields to be filled:

    • Command: Set to the value ResetSession.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Reset All: Reset all configured FIX sessions.

    Requires the following fields to be filled:

    • Command: Set to the value ResetAllSessions.

  • Get Next MsgSeqNums: Get the next incoming and outgoing message sequence numbers. As a result of this command, a new tuple will be emitted on the Admin Message input stream (see Administration-Level FIX Message Routing Port). This tuple's __ExtraInfo field will contain a string of the form SenderSeqNum=nnn,TargetSeqNum=mmm, where nnn and mmm are the next sequence number for the sender and target, respectively. If more than one session is configured, the SenderCompID and TargetCompID fields (and other related fields, as appropriate) will contain the values sent in the command tuple.

    Requires the following fields to be filled:

    • Command: Set to the value GetMsgSeqNums.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Set Sender MsgSeqNum: Explicitly sets the value of the next outgoing message's MsgSeqNum (tag=34) value.

    Requires the following fields to be filled:

    • Command: Set to the value SetSenderMsgSeqNum.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • BeginSeqNo: The sequence number you would like the next outgoing message to have.

  • Set Target MsgSeqNum: Explicitly sets the expected value of the next incoming message's MsgSeqNum (tag=34) value. Normally, the adapter's underlying FIX engine would automatically take care of negotiating message number sequencing, but this may be useful to recover from message sequence disparities when dealing with badly-behaved FIX counterparties (such as parties that incorrectly support the usual ResendRequest/SequenceReset FIX mechanism of recovery).

    Requires the following fields to be filled:

    • Command: Set to the value SetTargetMsgSeqNum.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • BeginSeqNo: The sequence number you would like the next outgoing message to have.

  • Message Replay: In certain high-availability scenarios, it is not sufficient to rely on the FIX engine's automatic support of the ResendRequest/SeqReset message recovery mechanism provided by the FIX Specification. Sometimes an explicit replay of incoming FIX messages is required — even if, from the perspective of the engine, those messages have already been successfully processed. For example those messages may still have been in flight in the StreamBase application when a failure occurred and need to be reprocessed.

    To handle these situations a command was added to instruct the adapter to replay incoming FIX messages based on their MsgSeqNum values. The messages are replayed by the adapter as if they had just been received. Note that any fast-ack classes currently in effect (see Auto-Acknowledge) will NOT be invoked for messages replayed in this fashion.

    Note

    This command is currently only available when running with the StreamBaseFIX engine, and requires that the following settings be present in the fixengine.properties file (see StreamBaseFIX Configuration File for details):

    • storageFactory=com.epam.fixengine.storage.FilesystemStorageFactory

    • storageDirectory=${fixaj.home}/myLogDirectory

    • incomingStorageIndexed=true

    Requires the following fields to be filled:

    • Command: Set to the value ReplayMessages.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if this is an acceptor session or if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if this is an acceptor session or if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if this is an acceptor session or if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • BeginSeqNo: The sequence number of the first incoming FIX message you would like replayed.

    • EndSeqNo: The sequence number of the last incoming FIX message you would like replayed, inclusively.

  • Get Session Configuration: This returns a tuple on the Status output port containing the list of settings used to configure the given session. The settings are returned as a list of tuples in the __SessionConfig field, and each of these tuples have two string fields: Name (containing the setting's name) and Value (containing its value).

    Note

    This command is only available with the QuickFIX/J and StreamBaseFIX engines.

    Requires the following fields to be filled:

    • Command: Set to the value GetSessionConfiguration.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Get Log Path: This returns a tuple on the Status output port containing in its __ExtraInfo field the full path of the directory where the log files created by the FIX engine will be located.

    Note

    This command is only available with the QuickFIX/J and StreamBaseFIX engines.

    Requires the following fields to be filled:

    • Command: Set to the value GetLogPath.

    • BeginString: The value of the FIX BeginString (tag=8) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • SenderCompID: The value of the FIX SenderCompID (tag=49) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

    • TargetCompID: The value of the FIX TargetCompID (tag=56) field used to identify this session. Only required if there are more than one session configured for use by this adapter — otherwise, may be left null.

  • Get Adapter Version: This returns a tuple on the Status output port containing the adapter's version string in the __ExtraInfo field.

    Note

    This command is only available with the QuickFIX/J and StreamBaseFIX engines.

    Requires the following fields to be filled:

    • Command: Set to the value GetAdapterVersion.

  • Set Log Level: Allows the end user to dynamically change the log level of the adapter during runtime.

    Requires the following field to be filled:

    • Command: Set to the value setLogLevel.

    • Log: A tuple with at minimum a String field 'Level' to set the new adapter log level.

Output Adapter Ports

The FIX Output adapter has no output ports, and has only one input port, which receives tuples to be converted to application-level FIX messages and sent to a connected FIX target.

The schema used by this port is determined by the application. As is the case for the FIX Input adapter's application-level FIX message routing ports, the fields in the schema are expected to contain fields whose names have a direct counterpart in the destination FIX message. (See Edit Schemas Tab for details.) Some fields are mandatory and must be included in this schema. Those fields are the same four mandatory fields as in the FIX Input adapter's application-level FIX message routing ports and are described in Edit Schemas Tab.

Note

The underlying FIX engine used by the adapter will automatically fill in certain fields prior to sending the FIX message, so you don't have to worry about setting these fields yourself. Those fields are:

  • BodyLength (tag=9)

  • MsgSeqNum (tag=34)

  • SecureDataLen (tag=90) (when using message encryption)

  • SecureData (tag=91) (when using message encryption)

  • SendingTime (tag=52)

  • CheckSum (tag=10)

Similarly, if only one session is configured and it is running as a FIX initiator the BeginString, SenderCompID and TargetCompID fields are initialized for you (as well as Sub and Location variants thereof, if warranted).

Requesting Outgoing Message Send Confirmation

When converting a tuple to be sent as a FIX message to the counterparty, the Output Adapter checks the tuple's schema for the presence of a string field named __AckID. If this field is found and its value for a given tuple is non-null, the adapter sends a tuple to the Input Adapter's Admin output port to confirm that it was indeed sent. This can be useful in certain HA scenarios where the system must ensure that every message has either been correctly sent or will be retried at a later time. The confirmation tuple has values for the following fields:

  • __ExtraInfo: Set to the value Ack - Success if the tuple was successfully converted to a FIX message and sent to the counterparty, and Ack - Failure if an error occurred (and as a result the message cannot be sent).

  • Text: Set to the value found in the original tuple's __AckID field. This allows you to establish a correlation between the outgoing message and its ACK confirmation.

  • SenderCompID and TargetCompID: Set to the the correct values for the session to which the outgoing tuple was destined.

Using the Adapter in a StreamBase Application

This section demonstrates how to use the FIX adapter in a StreamBase application. As shown in the EventFlow diagram below, the adapter appears as two icons on the canvas: one for input and one for output. Each icon has a specific set of input and output ports to communicate with the surrounding application. As with other StreamBase adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.

Note

While you can use an instance of the FIX Input adapter on its own as a way to receive FIX messages (or an instance of the FIX Output adapter to send FIX messages), the most useful configuration is to use one instance of each Input and Output and link them to share the same FIX connection, to allow you to both send and receive messages. See Linking Input and Output adapters for more details.

Adding the Adapter to an EventFlow Application

Add an instance of the adapter to a new StreamBase EventFlow application as follows:

  1. In StreamBase Studio, create a project, including an empty StreamBase EventFlow application file to host the adapter.

  2. From the Operators and Adapter drawer of the Palette view, drag a FIX Input component to the canvas.

  3. From the Operators and Adapter drawer, drag a FIX Output component to the canvas.

  4. Select the FIX Output adapter icon, and in the Properties view, select the General tab.

  5. In the Name box, enter a more meaningful name for your output adapter (the default is OutputAdapter1.) For this example, we use MyFIXOutput.

  6. Select the Adapter Properties tab.

  7. Enter the name of the QuickFIX/J configuration file this adapter should use to connect to the FIX target. See Configuration File Formats for details on creating this file.

  8. Select the FIX Input adapter icon, and in the Properties view select the Adapter Properties tab.

  9. Check the Share A FIX Connection With An Output Adapter option, and enter the name of your FIX Output adapter (MyFIXOutput in this example) in the Share With The FIX Output Adapter Named text box. This is how the Input adapter becomes linked with the specified output adapter and is made to share its FIX connection.

  10. Select the Edit Schemas tab, and define a schema for the Input adapter's default application-level FIX message routing port. See Edit Schemas Tab for details. The adapter generates typecheck errors when the input streams are missing required fields, when unexpected fields are present, or when fields are of the wrong type or size.

    Note

    You may find it useful to use a named schema for this port. For example, you may wish to use the same schema for your Output adapter's input stream.

  11. Connect Input and Output Streams to the adapters' input and output ports.

  12. Select the Input stream connected to MyFIXOutput's input port, and define its schema. Again, refer to Edit Schemas Tab for details.

Configuration File Formats

This section describes the format of the configuration and field name map files used by the FIX adapter.

QuickFIX/J Configuration File
StreamBaseFIX Configuration File
StreamBaseFIX Properties Files
Field Name Map File

QuickFIX/J Configuration File

When the adapter is configured to use QuickFIX/J as an underlying FIX engine, the value of the FIX Configuration File property must be set to a valid QuickFIX/J configuration file in the current Studio project. The configuration file describes the FIX sessions to establish when the adapter starts. A typical QuickFIX/J configuration file for an acceptor session might look like the following example: 

[DEFAULT]
ConnectionType=acceptor

# This prevents excessive memory usage over time.
# See http://n2.nabble.com/limiting-memory-usage-of-FileStore-(patch)-td839881.html 
# for details.
FileStoreMaxCachedMsgs=0

[SESSION]
BeginString=FIX.4.2
SenderCompID=MySenderID
TargetCompID=MyTargetID
SocketAcceptPort=1234
FileLogPath=logs/
FileStorePath=store/

A typical initiator session, connecting to an acceptor that runs locally, looks like the following:

[DEFAULT]
ConnectionType=initiator

# This prevents excessive memory usage over time.
# See http://n2.nabble.com/limiting-memory-usage-of-FileStore-(patch)-td839881.html 
# for details.
FileStoreMaxCachedMsgs=0

[SESSION]
BeginString=FIX.4.2
SenderCompID=MySenderID
TargetCompID=MyTargetID
SocketConnectionHost=localhost
SocketConnectPort=1234
FileLogPath=logs/
FileStorePath=store/
HeartBtInt=30

To specify a custom data dictionary, or to override a venue-specific default dictionary provided by StreamBase, use lines like the following example: 

UseDataDictionary=Y
DataDictionary=myDictionaryFile

The QuickFIX/J engine uses its own logging system by default. Independent of FIX engine, the FIX adapter participates in the standard StreamBase platform logging system that uses the SLF4J front end, as described in Using StreamBase Logging. The default configuration for StreamBase platform logging is to use the Logback back end when StreamBase Server is run in the foreground, and the Log4J back end when running as a service.

To direct the QuickFIX/J engine to participate in the adapter's logging system, specify the following line in the [Default] section of the configuration file: 

logtype=slf4j

With this setting, both the FIX adapter and the QuickFIX/J engine participate together in the host StreamBase Server's logging system. If you have configured the hosting application to use Log4J for all logging (described in Using StreamBase Logging), you must use the logtype=slf4j setting to have the QuickFIX/J engine participate in Log4J logging.

An alternative setting that enables the QuickFIX/J Screen* configuration options is: 

logtype=screen

For example, to suppress log messages from the QuickFIX/J engine, configure it to log to the console with logtype=screen and then set other settings for no logging: 

[DEFAULT]
logtype=screen
ScreenLogShowIncoming=N
ScreenLogShowOutgoing=N
ScreenLogShowEvents=N
...

For a complete description of the QuickFIX/J configuration options, refer to the QuickFIX/J User Manual.

StreamBaseFIX Configuration File

When the adapter is configured to use StreamBaseFIX as the underlying FIX engine, the value of the FIX Configuration File property must be set to a valid StreamBaseFIX configuration file in the current Studio project. The configuration file describes to the engine the FIX sessions to establish when the adapter starts. The StreamBaseFIX configuration file is in XML format for which the complete set of valid elements is shown in the following example. Values in this example show an adapter configured as an acceptor, with typical settings; this same example is provided as StreamBaseFIX-config-1.xml in the FIX adapter sample shipped with StreamBase. 

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

<!-- Sample configuration file for use by the StreamBase FIX 
     adapter when used with the StreamBaseFIX engine. -->

<sessions>
  <session name="SessionOne">

    <!--
    The actual FIX version to use.
    One of:
      FIX.4.0
      FIX.4.1
      FIX.4.2
      FIX.4.3
      FIX.4.4
      FIX.5.0
      FIX.5.0SP1
      FIX.5.0SP2
    -->
    <version>FIX.4.2</version>
    
    <!--
    The contents of the BeginString (8) FIX field.
    One of:
      FIX.4.0
      FIX.4.1
      FIX.4.2
      FIX.4.3
      FIX.4.4
      FIXT.1.1
    -->
    <begin-string>FIX.4.2</begin-string>

    <sender-comp-id>FIXAdapter_1</sender-comp-id>
    <target-comp-id>FIXAdapter_2</target-comp-id>

    <!--
    Set to false if your session is to be run as a 
    FIX acceptor.
    -->
    <initiator>true</initiator>
    
    <!-- You can use this to pick up fixengine.properties from another location than the top-level directory of the project.
         This can be usefule when multiple FIX-based adapters want to use different versions of fixengine.properties.
         Note that if one adapter uses this setting in a project, all FIX-based adapters must use it,
         and no fixengine.properties must be present in the default location.
         
    <fixengine-properties-file>mySubDir/fixengine.properties</fixengine-properties-file>
    -->

    <!--
    For initiators, the port to which to connect. For acceptors,
    the port on which to listen for connection requests.
    -->
    <port>1234</port>
    
    <!--
    For initiators, the host to which to connect. For acceptors,
    this setting is ignored.
    -->
    <acceptor-hostname>localhost</acceptor-hostname>

    <!--
    Heartbeat interval, in seconds.
    -->
    <heartbeat-interval>30</heartbeat-interval>
    
    <!--
    Set to 'true' to have the session reset message sequence 
    numbers to 1 when sending a Logon message.
    Defaults to 'false'.
    -->
    <reset-on-logon>true</reset-on-logon>
    
    <!--
    When set to 'true', time-based FIX fields (such as 
    UTCTimestamp fields) are formatted in outgoing messages to 
    include the millisecond portion of the timestamp.
    Defaults to 'true'.
    -->
    <use-date-milliseconds>true</use-date-milliseconds>

    <!--
    Name of the FIX Data Dictionary to use with this session.
    This string must match the value of the 'id' attribute of 
    the <fixdic> tag at the top of the dictionary file.
     -->    
    <dictionary></dictionary>
    
    <!--
    Name of the FIX Data Dictionary file to use with this session.
    Only used if <dictionary> is also specified.
    Should be set to the file name of the dictionary to load. If the
    given file name is a relative path, it will be considered relative
    to the classpath.
    If <dictionary> is used but <dictionary-file> isn't, the adapter
    will search for a file named "fixaj-dictionaries/XXXDictionary.xml"
    in the classpath, where "XXX" is the value given in the <dictionary> tag.
     -->
    <dictionary-file></dictionary-file>
    
    <!--
    Fully-qualified name of the class implementing
    com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor.
    This class is used to customize outgoing messages, such as to add 
    custom fields to Logon messages.
     -->
    <message-interceptor></message-interceptor>

    <!--
    If this is set to a non-empty value, it supercedes the value of 
    the fixengine.properties file's "storageFactory" setting.
    Typical values are one of:
      com.epam.fixengine.storage.FilesystemStorageFactory
      com.epam.fixengine.storage.InMemoryStorageFactory
    Only valid for initiators; acceptors use the value found in 
    fixengine.properties for all incoming sessions. 
    -->
    <storage-factory></storage-factory>
    
    <!--
    When using a FilesystemStorageFactory (either set through the 
    fixengine.properties file or through the <storage-factory> setting 
    above) this indicates the location where the storage files should 
    reside. The location is relative to the StreamBase project's 
    top-level directory. This setting supercedes the value set in the
    "storageDirectory" directive of the fixengine.properties file.
    
    Only valid for initiators; acceptors use the value found in 
    fixengine.properties for all incoming sessions. 
    -->
    <storage-directory></storage-directory>

    <!--
    This section defines the list of 'fast-ack' classes (which must 
    implement com.streambase.sb.adapter.fix.engine.antenna.IFastAck) 
    that will be called upon to send immediate acknowledgement in 
    response to incoming FIX messages. For example, you can write a 
    class that sends an automatic PENDING_NEW ExecutionReport in 
    response to each new order placed via NewOrderSingle.
    -->
    <!--
    <fast-acks>
      <fast-ack name="MyAcker" msg-type="D" 
      class="com.streambase.sb.adapter.fix.engine.antenna.NewOrderSingleFastAck"/>
    </fast-acks>
    -->

    <username></username>
    <password></password>
    
    <!--
    Connect using SSL.
    
    Note that store locations and passwords for auth certificates must also be specified,
    for example via sbd.sbconf's <java-vm> directive. 
    -->
    <use-ssl>false</use-ssl>

    <!--
    Use these to schedule the period of time sessions should be active.
    Logons initiated during a scheduled stop are not sent until the 
    schedule starts again.
    
    If the session is logged on at the time the schedule stops, it is
    logged off.
    
    Acceptors no longer accept connections during the scheduled stop.
    
    The time expression is the same as for the cron utility in Unix/Linux 
    systems. See http://en.wikipedia.org/wiki/Cron#CRON_expression for 
    a description.
    -->
    <!--  
    <scheduled-start>30 09 * * *</scheduled-start>
    <scheduled-stop>30 16 * * *</scheduled-stop>
    -->
    
    <!--
    The following settings are used for EBS' UserRequest (BE) / 
    UserResponse (BF) user-level logon mechanism and password 
    management. 
    -->
    <!--
    <cstm-appl-ver-id></cstm-appl-ver-id>
    <new-password></new-password>
    
    <user-data-list>
      <user-data name="AutoCancelDuplSession" value="Y" />
      <user-data name="SendConfirmedDeals" value="Y" />
      <user-data name="LargeDifferenceCheck" value="Y" />
      <user-data name="PriceCheck" value="Y" />
      <user-data name="WideSpreadCheck" value="Y" />
      <user-data name="LocalPriceDisplay" value="Y" />
      <user-data name="HideMyPrices" value="Y" />
      <user-data name="AllowFixedDateNDFs" value="Y" />
      <user-data name="OrderThroughput" value="1" />
      <user-data name="dealcode" value="ABCD" />
    </user-data-list>
    -->
    
    <!-- 
    Acceptors only: You may restrict counterparties to those with the specified
    IP addresses / ranges (using CIDR notation).
    -->
    <!--
    <acceptor-ip-whitelist>
      <whitelisted-ip>127.0.0.1</whitelisted-ip>
      <whitelisted-ip>10.97.233.1/24</whitelisted-ip>
    </acceptor-ip-whitelist>
    -->

  </session>
</sessions>

StreamBaseFIX Properties Files

In addition to the configuration file described in the previous section, the StreamBaseFIX engine also requires the presence of a second file named fixengine.properties, which helps specify engine-wide settings. Place this file in your project's top-level directory, or use the adapter configuration file's <fixengine-properties-file> setting to specify another location. Here is an example of a typical file, the same one provided in the FIX adapter sample shipped with StreamBase.

The StreamBaseFIX engine is derived from the B2Bits Antenna FIX engine from EPAM Systems. Refer to the B2BITS FIX Antenna Java Programmer's Guide for a complete description of the available settings for the fixengine.properties file. 

#
# This fixengine.properties file is used by the StreamBaseFIX 
# engine and contains engine-wide settings.
#

# Sets the queue mode.
# Set "true" for an in-memory queue (faster but less safe, some 
# messages may be lost in the event of a crash)
inMemoryQueue=true

# Validation disabled
validation=false

# Maximum number of messages in a queue before we pause 
# the pumper thread to allow queued messages to be sent out. 
# Set rather high for max performance; set 1 or pretty 
# low for realtime experience.
# 0 - disable queue control, do not pause pumper thread
queueThresholdSize = 1

# Set to com.epam.fixengine.storage.InMemoryStorageFactory 
# for increased performance (no message store or logging will be kept)
storageFactory=com.epam.fixengine.storage.FilesystemStorageFactory
# storageFactory=com.epam.fixengine.storage.InMemoryStorageFactory

# When using com.epam.fixengine.storage.FilesystemStorageFactory 
# this determines where log and storage files are saved.
storageDirectory=./fixajLogs

# Specifies cleaning mode for persistent message storage of closed 
# sessions. Possible values: None | Backup | Delete. Default is None.
storageCleanupMode=None

# Enable/disable persistent storage file growth. If false, the 
# persistent message storage file is capped at the value of the 
# maxStorageGrowSize setting (see below). Default: false 
storageGrowSize=false

# Sets the maximum persistent message storage file size in bytes.
# Default is 1MB. Only relevant when 
# storageFactory=com.epam.fixengine.storage.FilesystemStorageFactory
# and storageGrowSize=false.
maxStorageGrowSize=1Mb

# Set this to true to enable the adapter's "ReplayMessages" command.
incomingStorageIndexed=false

# Specifies the number of autoreconnect attempts:
#    negative number - no reconnects,
#    0 - infinite number of reconnects,
#    positive number - number of reconnect attempts.
autoreconnectAttempts=0
autoreconnectDelayInMs=5000

Field Name Map File

The section Field Name Map File describes how it is possible to map FIX fields to StreamBase fields with different names. The mappings must be placed in a plain text file that contains a list of entries in the following format, one entry per line: 

FIX-field-name=StreamBase-field-name

When the adapter receives FIX messages, entries that do not correspond to valid FIX or StreamBase field names are ignored.

Blank lines in the map file are ignored. Lines that begin with the # character are treated as comment lines and are ignored.

Implementing a Custom Admin Message Interceptor Class

Certain FIX venues require that custom fields be added to FIX administrative messages to be considered valid. For example, a venue may require that a Username (tag=553) and Password (tag=554) fields be added to Logon (MsgType=A) messages while using the FIX 4.2 protocol (which did not define these fields).

The FIX adapter includes ready-to-use Admin Message Interceptor classes to add Username (tag=553) and Password (tag=554) fields to your Logon message. To use this functionality, proceed as follows:

  • QuickFIX/J users:

    1. In Studio, select the adapter and enter the following value in the FIX Admin Message Interceptor Class field in the Adapter Properties tab in the Properties view: com.streambase.sb.adapter.fix.engine.quickfixj.UsernamePasswordQFJAdminMessageInterceptor

    2. In your adapter's configuration file, add the following lines to the [DEFAULT] section if you wish the values to apply to all sessions configured in the file or to the [SESSION] section to which the values apply: 

      Username=MyUserName
Password=MyPassword

      Where MyUserName and MyPassword are replaced with your own user name and password, respectively.

  • StreamBaseFIX users:

    1. In Studio, select the adapter and enter the following value in the FIX Admin Message Interceptor Class field in the Adapter Properties tab in the Properties view: com.streambase.sb.adapter.fix.engine.antenna.UsernamePasswordFIXAJMessageInterceptor

    2. In your adapter's configuration file, add the following section under the <session> tag: 

      <username>MyUserName</username>
<password>MyPassword</password>

      Where MyUserName and MyPassword are replaced with your own user name and password, respectively.

In the case of both FIX engines, if you omit either the username or password entry in the configuration file, the message interceptor also omits the corresponding field in the FIX Logon message. This allows you to set only the Username (tag=553) field (by omitting the password entry) or only the Password (tag=554) field (by omitting the username entry) in the Logon message.

Because the FIX adapter's underlying FIX engine usually handles the sending and receiving of admin messages automatically, a mechanism must be provided to add such custom fields manually. This is accomplished by making available to the adapter a custom class that will be responsible for adding the fields before the messages are sent. When such a class is specified, the adapter will call into it with every outgoing message, allowing the class to modify it.

The class must implement one of the following interfaces, depending on your underlying FIX engine:

com.streambase.sb.adapter.fix.engine.quickfixj.QFJAdminMessageInterceptor
com.streambase.sb.adapter.fix.engine.antenna.FIXAJMessageInterceptor

These interfaces are defined as follows:

QuickFIX/J version:

package com.streambase.sb.adapter.fix.engine.quickfixj;

import java.io.InputStream;

import org.slf4j.Logger;

import quickfix.Message;
import quickfix.SessionID;

import com.streambase.sb.StreamBaseException;
import com.streambase.sb.adapter.fix.IFIXAdminMessageInterceptor;

/**
 * QuickFIX/J-aware specialization of the AdminMessageInterceptor interface. 
 */
public interface QFJAdminMessageInterceptor extends IFIXAdminMessageInterceptor
{
    /**
     * Allows the implementer to receive the name of the configuration file
     * used with this adapter. This can be useful to extract custom settings
     * from the configuration file, such as login credentials, etc.
     * 
     * This method is guaranteed to have been be called before the first call
     * to onAdminMessage().
     * 
     * @param logger the supplied Logger may be used to output trace information.
     * @param isConfig the configuration file used to configure the adapter.
     */
    public void setConfigFile(Logger logger, InputStream isConfig) 
       throws StreamBaseException;
    
    /**
     * Called whenever QF/J is about to send an admin-level FIX message to the target.
     * This method is free to change the content of the message, for example to add
     * custom fields.
     * @param id the SessionID to which this message is destined.
     * @param msg the actual Message about to be sent.
     */
    public void onAdminMessage(SessionID id, Message msg);
    }

StreamBaseFIX version:

package com.streambase.sb.adapter.fix.engine.antenna;

import java.io.InputStream;

import org.slf4j.Logger;

import com.epam.fix.message.FIXFieldList;
import com.streambase.sb.StreamBaseException;
import com.streambase.sb.adapter.fix.IFIXAdminMessageInterceptor;


/**
 * StreamBase FIX specialization of the AdminMessageInterceptor interface. 
 */
public interface FIXAJMessageInterceptor extends IFIXAdminMessageInterceptor
{
    /**
     * Gets the list of extra fields to add to outgoing Login messages for 
     * the given session.
     * @param sessionName the name of the session (as set in the config 
     * file's name attribute of the session tag) for which to get the extra 
     * outgoing Login fields.
     * @return the extra fields to add to outgoing Login messages.
     */
    public FIXFieldList getOutgoingLoginFields(String sessionName);
    
    /**
     * Gets the list of extra fields to expect from incoming Login messages 
     * for the given session.
     * @param sessionName the name of the session (as set in the config 
     * file's name attribute of the session tag) for which to set the extra 
     * incoming Login fields.
     * @return the extra fields to expect from incoming Login messages.
     */
    public FIXFieldList getIncomingLoginFields(String sessionName);
    
    /**
     * Gets the list of extra fields to add to every outgoing FIX message's 
     * header.
     * @param sessionName the name of the session (as set in the config 
     * file's name attribute of the session tag) for which to set the 
     * extra header fields.
     * @return the extra header fields to add to all outgoing messages.
     */
    public FIXFieldList getHeaderFields(String sessionName);
    
    /**
     * Allows the implementer to receive the name of the configuration file
     * used with this adapter. This can be useful to extract custom settings
     * from the configuration file, such as login credentials, etc.
     * 
     * This method is guaranteed to have been be called before the first call
     * to onAdminMessage().
     * 
     * @param logger the supplied Logger may be used to output trace information.
     * @param isConfig the configuration file used to configure the adapter.
     */
    public void setConfigFile(Logger logger, InputStream isConfig) throws StreamBaseException;
}

As an example, you might want to add a Password (tag=554) field to every outgoing Logon message to connect to a FIX counterparty, and you chose QuickFIX/J as the adapter's underlying FIX engine. One solution is to add a new setting to the adapter's configuration file to specify the password to use, like this: 

[default]
ConnectionType=initiator
SenderCompID=MySenderID
SocketConnectHost=localhost
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5
FileLogPath=fixlogs/sender.log
FileStorePath=fixlogs/sender.store

[session]
Password=MyPassword
BeginString=FIX.4.3
TargetCompID=MyTargetID
SocketConnectPort=2001

Then you must write a class that implements com.streambase.sb.adapter.fix.engine.quickfixj.QFJAdminMessageInterceptor to use this setting. (Long lines in the following example are shown broken with a line continuation backslash for publication clarity.) 

package com.mycompany;

import java.io.InputStream;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;

import org.slf4j.Logger;

import com.streambase.sb.StreamBaseException;

import quickfix.ConfigError;
import quickfix.FieldConvertError;
import quickfix.FieldNotFound;
import quickfix.Message;
import quickfix.SessionID;
import quickfix.SessionSettings;
import quickfix.field.MsgType;
import quickfix.field.Password;

/**
 * Implementation of a QFJAdminMessageInterceptor that applies custom 
 * password semantics.
 */
public class CustomQFJAdminMessageInterceptor implements QFJAdminMessageInterceptor
{
  public static final String PASSWORD_KEY = "Password";

  private Logger logger;
    
  /**
   * This stores the value of the Password key for each session defined 
   * in the configuration file.
   */
  private Map<SessionID, String> pwdMap = new HashMap<SessionID, String>();

  /**
   * {@inheritDoc}
   */
  public void onAdminMessage(SessionID id, Message msg)
  {
    //
    // Are we using the Currenex FIX protocol?
    //
    try
      {
        //
        // Are we trying to log on (that is MsgType="A"?)
        //
        if (msg.getHeader().getString(MsgType.FIELD).compareTo("A") == 0)
          {
            //
            // Retrieve the password value for this session
            //
            String pwd = pwdMap.get(id);

            //
            // If this is null, ignore. The checks in setConfigFile() below should
            // be enough to prevent that anyway...
            //
            if (pwd != null)
              {
                //
                // Add the missing "Password" field to the outgoing Logon message.
                //
                msg.setString(Password.FIELD, pwd);
              }
          }
      }
      catch (FieldNotFound e)
      {
        // Missing "MsgType" field is impossible in every known version of FIX...
      }

    if (logger.isDebugEnabled())
      logger.debug(String.format("CustomQFJAdminMessageInterceptor: Sending \
admin message: %s", msg.toString()));
  }

  /**
   * {@inheritDoc}
   */
  public void setConfigFile(Logger logger, InputStream isConfig) 
    throws StreamBaseException
  {
    this.logger = logger;

    //
    // Read the "Password" setting for each session defined in the QuickFIX/J configuration file.
    // We'll use this as the value when adding tag 554 to the Logon message.
    //
    SessionSettings ss;
    try
      {
        //
        // Read in the config file
        //
        ss = new SessionSettings(isConfig);

        //
        // Go through each session's section to retrieve its Password value
        //
        Iterator<SessionID> iter = ss.sectionIterator();
        while (iter.hasNext())
          {
            SessionID id = iter.next();
            String pwd = getSetting(ss, id, PASSWORD_KEY);
            if (pwd == null || pwd.trim().isEmpty())
            {
              throw new StreamBaseException(String.format("CustomQFJAdminMessageInterceptor: \
Cannot find '%s' directive in QuickFIX/J configuration file", PASSWORD_KEY));
            }
            else
              pwdMap.put(id, pwd);
          }
      }
      catch (ConfigError ce)
        {
          throw new StreamBaseException("CurrenexQFJAdminMessageInterceptor: \
Error loading QuickFIX/J configuration file.", ce);
        }
      catch (FieldConvertError fce)
        {
          throw new StreamBaseException(String.format("CustomQFJAdminMessageInterceptor: \
Error reading '%s' directive from QuickFIX/J configuration file", 
          PASSWORD_KEY),
          fce);
        }
  }
    
  /**
   * This method retrieves the desired value as set for the given session ID.
   * If the value is not explicitly set for the session it will look at the value
   * set in the [DEFAULT] section and use it if found. Otherwise null will be returned.
   * 
   * @param ss the settings file from which to retrieve a value.
   * @param key the name of the setting to retrieve, e.g. "Password".
   * @param sessionID the ID of the session for which to retrieve the value. If null,
   * the default section is assumed.
   * @return The value of the requested key, or null if not found in either the session's or
   * DEFAULT sections. 
   * @throws FieldConvertError 
   * @throws ConfigError 
   */
   private String getSetting(SessionSettings ss, SessionID sessionID, String key)
            throws ConfigError, FieldConvertError
   {
     if (key == null || key.trim().isEmpty())
       return null;
        
     String value = null;
        
     //
     // Look for a session-specific setting first
     //
     if (sessionID != null && ss.isSetting(sessionID, key))
       value = ss.getString(sessionID, key);
        
     //
     // If no value is set, try the default value
     //
     if (value == null || value.trim().isEmpty())
       {
         if (ss.isSetting(key))
           value = ss.getString(key);
       }
        
       return value;
   }
}

For the code above to compile, ensure that the following JAR files are present on your build path:

  • For QuickFIX/J:

    • streambase/lib/adapter/fix.jar

    • streambase/lib/ext/sb-fix-core.jar

    • streambase/lib/ext/quickfixj-all.jar

  • For StreamBaseFIX:

    • streambase/lib/adapter/fix.jar

    • streambase/lib/ext/sb-fix-core.jar

    • streambase/lib/ext/fixaj-*.jar

Now make sure this class is available to the adapter at runtime. The most expedient way of accomplishing this is to put your class in a JAR file and place this JAR file in StreamBase's lib/adapter/ext directory.

Next, in your adapter's Adapter Properties tab, set the FIX Admin Message Interceptor Class value to com.mycompany.CustomQFJAdminMessageInterceptor so the adapter knows to load your custom class and call it at runtime.

Finally, make sure that the fields you are adding to the message are considered valid by the underlying FIX engine, which usually entails a modification to the data dictionary used by the engine. In the example above, to use a FIX version prior to 4.3, define the Password field as a string field with tag 554 (because that field did not exist in previous FIX versions), and modify the definition of the Logon message to add this new field.

Refer to the QuickFIX/J documentation for details on how to modify data dictionaries. To modify a StreamBaseFIX data dictionary, please contact StreamBase technical support.

StreamBaseFIX-Specific Functionality

The FIX adapter provides a tight integration with the the StreamBaseFIX engine, and as such is able to offer more features when used with this engine. Those features are described in this section.

SSL Connections

To connect to a FIX counterparty using the Secure Socket Layer (SSL) protocol, you must specify <use-ssl>true</use-ssl> in your session's definition (see StreamBaseFIX Configuration File) and ensure that Java's SSL-specific properties (such as -Djavax.net.ssl.trustStore, -Djavax.net.ssl.keyStore, -Djavax.net.ssl.keyStorePassword and so on) are also set correctly -- for example by specifying them in your application's sbd.sbconf's <java-vm> directive.

Acceptor Counterparty Whitelisting

When running the adapter configured as a FIX acceptor, you may specify the list of IP addresses / IP ranges that are authorized to connect as counterparties. When this whitelist is specified, any counterparty not found in the list will be refused connection.

To specify an acceptor whitelist, use the <acceptor-ip-whitelist> configuration directive (see StreamBaseFIX Configuration File) to list one or more IP addresses or IP address ranges using CIDR notation.

Note

Sessions configured as FIX initiators ignore the <acceptor-ip-whitelist> section.

Replay Messages Command

A new command was added to have the adapter replay already-processed incoming FIX messages, to handle certain high-availability situations. See Message Replay.

Auto-Acknowledge

In low-latency situations you may wish to have the adapter quickly send acknowledgement in reply to certain messages (a typical usage would be for a sell-side application wishing to send a PENDING_NEW ExecutionReport when an order is received). Such fast-ack responses should not need active participation of the application and so can be handled at the FIX engine level.

Using this functionality will typically involve the coding of a Java class that will construct the reply message in response to the trigger (e.g. constructing an ExecutionReport in reply to a NewOrderSingle message).

To use this functionality:

  1. Instruct the adapter to enable the fast-ack mechanism by adding a <fast-acks> section such as the one highlighted in the configuration file snippet below: 

    <?xml version="1.0" encoding="UTF-8"?>
<sessions>
  <session name="SessionOne">
    <version>FIX.4.4</version>
    <begin-string>FIX.4.4</begin-string>
    <sender-comp-id>STREAMBASE</sender-comp-id>
    <target-comp-id>COUNTERPARTY</target-comp-id>
    <initiator>true</initiator>
    <port>1234</port>
    <acceptor-hostname>localhost</acceptor-hostname>
    <heartbeat-interval>30</heartbeat-interval>
    <reset-on-logon>true</reset-on-logon>
    <use-date-milliseconds>true</use-date-milliseconds>
    <dictionary></dictionary>
    <message-interceptor></message-interceptor>

    <!--
    This section defines the list of 'fast-ack' classes (which must implement
    com.streambase.sb.adapter.fix.engine.antenna.IFastAck) that will be called
    upon to send immediate acknowledgement in response to incoming FIX messages.
    For example, you can write a class that sends an automatic PENDING_NEW
    ExecutionReport in response to each new order placed via NewOrderSingle.
    -->
    <fast-acks>
      <fast-ack name="MyAcker" msg-type="D" 
       class="com.streambase.sb.adapter.fix.engine.antenna.NewOrderSingleFastAck"/>
     </fast-acks>
        ...        
  </session>
</sessions>

    In this example, one fast-ack class (named com.streambase.sb.adapter.fix.engine.antenna.NewOrderSingleFastAck) is installed to respond to messages of type D (NewOrderSingle). The name attribute is only used to identify this fast-ack instance in logging traces.

    Note that you may use multiple fast-ack classes at a time (simply add more <fast-ack> tags to the <fast-acks> section); however only one fast-ack class per message type is allowed.

  2. Write your fast-ack class. Your class must implement com.streambase.sb.adapter.fix.engine.antenna.IFastAck (available in $streambase_home/lib/adapter/fix.jar) and reads as follows: 

    package com.streambase.sb.adapter.fix.engine.antenna;

import org.slf4j.Logger;
import com.epam.fix.message.FIXFieldList;

/**
 * This interface defines the methods necessary to implement a class capable of doing fast acks in response
 * to given FIX messages (e.g. NewOrderSingle -> ExecutionReport(PENDING_NEW)).
 */
public interface IFastAck
{
    /**
     * Create an automated ACK for an incoming message.
     * 
     * @param ack Ack Message to populate.
     * @param sessionID FIX session from which this message originated.
     * @param incomingMsg incoming FIX message.
     * @return true if ack is successfully populated.
     */
    public boolean ack(FIXFieldList ack, SessionID sessionID, FIXFieldList incomingMsg);

    /**
     * Returns the MsgType of the ack message, e.g. {'8'}.
     * @return a String containing the value of the outgoing ack message's MsgType (35) field.
     */
    public String getAckMessageType();

    /**
     * Gives the implementer access to the config file used to configure the current FIX session(s).
     * This method is guaranteed to be called immediately after the class is constructed and before
     * any calls to {@link #ack(FIXFieldList, SessionID, FIXFieldList)} are made.
     * @param sessionInfo the configuration used to set up the current FIX session.
     * @param logger a Logger to use for issuing traces.
     */
    public void setConfig(SessionInfo info, Logger logger);
}

    Here is an example implementation (also available in fix.jar) that will send an ExecutionReport in response to a NewOrderSingle message: 

    //
// Copyright (c) 2004-2019 TIBCO Software Inc. All rights reserved.
//

package com.streambase.sb.adapter.fix.engine.antenna;

import org.slf4j.Logger;

import com.epam.fix.message.FIXFieldList;

/**
 * This class can be installed on the FIX adapter to make it auto-generate
 * PENDING_NEW ExecutionReport messages back to the sender of NewOrderSingle ("D")
 * messages BEFORE the message is converted and sent to the StreamBase application.
 */
public class NewOrderSingleFastAck implements IFastAck
{
    private SessionInfo info;
    private Logger logger;

    //
    // You can use the configuration file to pass along custom values to this class
    //
    @SuppressWarnings("unused")
    private String myCustomSetting;
    
    private static final int LAST_SHARES_TAG = 32;
    private static final int LAST_PX_TAG = 31;
    private static final int CUM_QTY_TAG = 14;
    private static final int AVG_PX_TAG = 6;
    private static final int LEAVES_QTY_TAG = 151;
    private static final int ORDER_STATUS_TAG = 39;
    private static final int EXEC_TYPE_TAG = 150;
    private static final int EXEC_TRANS_TYPE_TAG = 20;
    
    private static final int SECURITY_ID_TAG = 48;
    private static final int SECURITY_ID_SRC_TAG = 22;
    private static final int ORD_TYPE_TAG = 40;
    private static final int SYMBOL_TAG = 55;
    private static final int SYMBOL_SFX_TAG = 65;
    private static final int SIDE_TAG = 54;
    private static final int ORDER_QTY_TAG = 38;
    private static final int PRICE_TAG = 44;
    private static final int CLORD_ID_TAG = 11;

    private static final byte[] zeroAsBytes = "0".getBytes();
    private static final byte[] aAsBytes = "A".getBytes();
    
    private static final String sMsgType = "8";

    /**
     * This method is called by the adapter when a NewOrderSingle ("D") message is received, BEFORE
     * it is converted to a tuple and sent to the StreamBase application. We use this to generate a
     * quick PENDING_NEW ExecutionReport ("8") message for the sender.
     * @param ack the ExecutionReport message to send back to sender. This method is expected to fill out the message
     * with the appropriate fields. 
     * @param sessionID the {@link SessionID} describing the current FIX session.
     * @param incomingMsg the contents of the NewOrderSingle message that was just received and for which an
     * ack is desired.
     * @return true if the Ack message is to be sent, false otherwise (i.e. no action will be taken by the adapter).
     */
    public boolean ack(FIXFieldList ack, SessionID sessionID, FIXFieldList incomingMsg)
    {
        ack.clear();
        
        if (incomingMsg.isTagExists(SYMBOL_TAG))
            ack.addTag(SYMBOL_TAG, incomingMsg.getTagValueAsBytes(SYMBOL_TAG));
        if (incomingMsg.isTagExists(SYMBOL_SFX_TAG))
            ack.addTag(SYMBOL_SFX_TAG, incomingMsg.getTagValueAsBytes(SYMBOL_SFX_TAG));
        if (incomingMsg.isTagExists(SIDE_TAG))
            ack.addTag(SIDE_TAG, incomingMsg.getTagValueAsBytes(SIDE_TAG));
        if (incomingMsg.isTagExists(ORDER_QTY_TAG))
            ack.addTag(ORDER_QTY_TAG, incomingMsg.getTagValueAsBytes(ORDER_QTY_TAG));
        
        //
        // These fields never change
        //
        ack.addTag(LAST_SHARES_TAG, zeroAsBytes);
        ack.addTag(LAST_PX_TAG, zeroAsBytes);
        ack.addTag(CUM_QTY_TAG, zeroAsBytes);
        ack.addTag(AVG_PX_TAG, zeroAsBytes);
        ack.addTag(ORDER_STATUS_TAG, aAsBytes);
        
        if (incomingMsg.isTagExists(SECURITY_ID_TAG))
            ack.addTag(SECURITY_ID_TAG, incomingMsg.getTagValueAsBytes(SECURITY_ID_TAG));
        if (incomingMsg.isTagExists(SECURITY_ID_SRC_TAG))
            ack.addTag(SECURITY_ID_SRC_TAG, incomingMsg.getTagValueAsBytes(SECURITY_ID_SRC_TAG));
        if (incomingMsg.isTagExists(ORD_TYPE_TAG))
            ack.addTag(ORD_TYPE_TAG, incomingMsg.getTagValueAsBytes(ORD_TYPE_TAG));
        if (incomingMsg.isTagExists(PRICE_TAG))
            ack.addTag(PRICE_TAG, incomingMsg.getTagValueAsBytes(PRICE_TAG));
        if (incomingMsg.isTagExists(CLORD_ID_TAG))
            ack.addTag(CLORD_ID_TAG, incomingMsg.getTagValueAsBytes(CLORD_ID_TAG));
        
        if (!info.getBeginString().equals("FIX.4.0"))
        {
            ack.addTag(EXEC_TYPE_TAG, aAsBytes);
            ack.addTag(LEAVES_QTY_TAG, zeroAsBytes);
        }
        if (info.getBeginString().equals("FIX.4.0") ||
            info.getBeginString().equals("FIX.4.1") ||
            info.getBeginString().equals("FIX.4.2"))
        {
            ack.addTag(EXEC_TRANS_TYPE_TAG, zeroAsBytes);
        }
        
        if (logger.isDebugEnabled())
            logger.debug("Sending fast ack: " + ack.toString());

        //
        // Now that it's properly populated, tell the adapter to send this message
        //
        return true;
    }

    /**
     * @return a String representing the message type generated by the {@link #ack(FIXFieldList, SessionID, FIXFieldList)} method.
     */
    public String getAckMessageType()
    {
        return sMsgType;
    }

    /**
     * This method is guaranteed to be called BEFORE the first call to {@link #ack(FIXFieldList, SessionID, FIXFieldList)} --
     * usually immediately after the creation of the class instance.
     * @param info the configuration of this FIX instance.
     * @param logger the {@link Logger} instance that should be used to issue traces by this class.
     */
    public void setConfig(SessionInfo info, Logger logger)
    {
        this.info = info;
        this.logger = logger;
        
        //
        // You could use the configuration information to pass along custom settings to this class;
        // Just use info.getCustomValue(String settingName) to access them here...
        //
        myCustomSetting = this.info.getCustomValue("MyCustomSetting");
    }

    @Override
    public void setLogger(Logger logger) {
        this.logger = logger;
    }
}

  3. At a minimum you will need the following JAR files in your classpath to compile the above:

    • $streambase_home/lib/adapter/fix.jar

    • $streambase_home/lib/ext/fixaj-*.jar

  4. Finally, make sure your class is available to your application at runtime. One easy way to do this is to place it in a JAR file and place this JAR file in the $streambase_home/lib/ext/ directory.

Typechecking and Error Handling

The FIX Input adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter generates typecheck messages for the following reasons:

  • A required property is missing.

  • One or more required fields in an output schema (notably for the application-level FIX message routing ports) is missing or is of the wrong type or size.

  • There are too many entries in the Message Routing Map (up to 10 entries are allowed).

  • There are empty entries in the Message Routing Map.

  • The Share a FIX Connection With An Output Adapter option is checked, but the Share With The FIX Output Adapter Named field is left empty.

Similarly, the FIX Output adapter can generate typecheck messages in the following situations:

  • The FIX Configuration File field, a required setting, is left blank.

  • One or more required fields in the input schema is missing or is of the wrong type or size.

At runtime, StreamBase fields of type double that evaluate to NaN (not-a-number) will be left null in the corresponding FIX message.

Suspend, Resume, Shutdown Behavior

When suspended, the adapter continues to receive and process FIX messages, but no longer emits tuples on its output ports.

When resumed, the adapter once again starts emitting tuples on its output ports.

When the application is shut down, the adapter attempts to do a clean log out of all active sessions: A Logout message is sent and the adapter waits for a Logout response before closing the connection with each counterparty.

Related Topics