Establishing FIX Connection

Establishing Connection

To establish a FIX connection as Acceptor the following method must be used:

To establish a FIX connection as Initiator the following method must be used:

Closing Connection

To disconnect the session the following method must be used:

This member implements a graceful closing of the FIX connection as defined by the Standard.

Reconnection Facility

When a FIX session is in the active state and there are some network issues the engine will try to restore the FIX connection in accordance with ConnectionRetries.Number and ConnectionRetries.Interval settings.

Example.

Connection and Session Lifetime

A single FIX session can exist across multiple sequential (not concurrent) physical connections. Parties can connect and disconnect multiple times while maintaining a single FIX session. That is, once the logout() method is called, the FIX Connection is terminated, however, the FIX session life continues. It is possible to continue the same session later using either logonAsAcceptor() or logonAsInitiator(..) methods again. In other words, a FIX Session is comprised of one or more FIX connections.

See also

Understanding Session States, Connecting using Custom Logon Message.

Exchanging Messages

Sending Messages to a Counterparty

To send a message to a counterparty one of the following methods must be used:

and

This method is asynchronous. As soon as a session is created it is possible to start sending messages via the session.

If the session is not established, the messages are stored in the session storage and will be sent in the replay to the resend request when the connection is established with the counterparty and the sequence numbers mismatch is detected (please see the Resending Messages page).

Receiving Messages from a Counterparty

To receive incoming application-level messages it is necessary to implement one of the following interfaces:

and

And register the handler with the corresponding method:

or

To receive incoming session-level messages it is necessary to implement one of the following interfaces:

and

And register the handler with the corresponding method:

or

Example.

Structured message exchange:

Flat message exchange:

Message Sequence Numbers

Understanding Message Sequencing

A single FIX session can exist across multiple sequential (not concurrent) physical connections. Parties can connect and disconnect multiple times while maintaining a single FIX session. That is, once the logout() method is called, the FIX Connection is terminated, however, the FIX session life continues. It is possible to continue the same session later using either logonAsAcceptor() or logonAsInitiator(..) methods again. In other words, a FIX Session is comprised of one or more FIX connections.

All FIX messages are identified by a unique sequence number (MsgSeqNum field) within the bounds of a single FIX session. Sequence numbers are initialized at the start of each FIX session starting at 1 (one) and increment throughout the session. Each session establishes an independent incoming and outgoing sequence series.

The engine automatically synchronizes sequence numbers when reconnecting during a FIX session on the base of the information that was previously stored in log files.

Manipulating Message Sequence Numbers

Monitoring sequence numbers enables parties to synchronize applications gracefully when reconnecting during a FIX session.

The expected sequence number of the next incoming message can be get using the following method:

And set using the following method:

The sequence number of the next outgoing message can be get using the following method:

And set using the following method:

Resetting inbound and outbound sequence numbers back to 1, for whatever reason, constitutes the beginning of a new FIX session. The following method must be used to backup the previous log files and reset the sequence numbers to 1:

Some implementations of the FIX protocol expect that a FIX Session coincides with a FIX Connection. In other words, message sequence numbers must be reset back to 1 before each Logon messages exchange including reconnect.

To interact with such FIX venues, keepSequenceNumbersBetweenFixConnections parameter of session constructor should be set to false. In this case before the Logon messages exchanges sequence numbers are set back to 1.

See also

Resetting Message Sequence Numbers, Resetting Message Sequence Numbers via ResetSeqNumFlag Field.

Automatic Message Fields

The FIX session sets or updates specific fields in the outgoing messages automatically.

The following fields belong to the message header and trailer. They are mandatory for all FIX versions and all message types.

• BeginString(8)
• BodyLength(9)
• MsgType(35)
• SenderCompID(49)
• TargetCompID(56)
• MsgSeqNum(34)
• SendingTime(52)
• CheckSum(10)

The following fields are set or updated only if they are configured explicitly for the session. They are applicable for all message types.

Manipulating Message Fields

A FIX message represents a sequence of fields whose values are associated with unique numbers (tags). Such an interpretation treats a message as a collection of values associated with tag numbers. For this reason, the primary approach in handling message fields is similar to managing associative collections.

Adding Field Into Message

To associate a field with a value in a structured message, the following method must be used:

If there is no field of a given tag number available in the message, this member creates an association. If the field already exists, this member updates its value with the new value.

To associate a field with a value in a flat message, the following method must be used:

It will add a tag-value pair at the end of the message no matter it exists or not.

OR

The following method must be used:

If there is no field of a given tag number it will throw an exception. If the field already exists, this member updates its value with the new value.

Accessing Field Value

To get a field value the following method can be used for structured message:

and the following methods for the flat message:

and

where the indexes can be obtained using the following method:

Accessing Field Value Directly

The following class has been implemented in order to provide direct access/pointer to the region in a received message of value associated with the field.

Example usage which avoids a string allocation:

Removing Field From Message

To remove a field value the following method can be used for structured message:

and the following methods for the flat message:

and

Example.

Named Tags Constants

The following class contains the constants for the tag values:

Also there are similar classes defined for each FIX version:

etc. The use of these constants makes the source code more readable.

Example.

Iterating over Fields of Message

To iterate over all fields of a FIX message please use the following method for the structured message:

This iterator does not iterate over fields from a repeating group. To iterate over fields of the repeating group you need to get the corresponding GroupInstance object from the repeating group, please see the FIX Repeating Group.

The following method for the flat message:

Message class provides iterator over raw message, please use the following method:

This iterator allows iterating over all fields including repeating groups of received raw FIX message as it is. Before any modifications to FIX message the set of fields will be in the same order as they are received/parsed and will include duplicates. Compared to the above-mentioned iterator it is slower.

Summary

See also

FIX Repeating Group.

Secure Logon

CME Globex implemented secure authentication for iLink and Drop Copy sessions on Convenience Gateway (CGW) and Market Segment Gateway (MSGW). The new logon procedure secures the client system logon with:

• Customer identity verification - a client system logon request will be signed with security credentials issued and validated by CME Group.
• Message confidentiality and integrity - to credential the logon message, the client system sends a keyed-hash message authentication code (HMAC) generated from a combination of the logon FIX tag values. When CME Globex receives the logon message, it uses the identical inputs to calculate the HMAC value to validate against the logon request. If the values do not match, CME Globex rejects the logon.

Customers must create secure key pairs for iLink and Drop Copy Sessions in the CME Customer Center.

CME Secure Logon requires to add several specific tags to Logon message, so our FIX Engine is ready to implement Secure Logon procedure. We have updated our CME Trading Client sample to help to implement Secure Logon.

Implementing Secure Logon consist of two parts: creating canonical request string and calculating HMAC. Canonical request string is just a union of several tags from Logon message. Please note, that Session fills values of some fields like SendingTime right before message sent, so its values can be taken from onOutboundSessionMessage() callback. To calculate HMAC a standard Java cryptographic classes are used.

Example.

Understanding Session States

During the FIX session lifetime, state changes occur. The Session class exposes the following method to determine in which state it currently resides:

The following tables describe all possible FIX session states that can occur during its lifetime, as well as what a specific state means for a session with a particular role.

Tracking Session State Change

To be notified about the changes in the session state implement the following class:

and register it as event handler with the following method:

Example.

Session Events and Listeners

The events and their listeners of the Session class are listed below.

Session state is changed:

Application-level message is received from the counterparty:

Application-level flat message is received from the counterparty:

Session-level message is received from the counterparty:

Session-level flat message is received from the counterparty:

Application-level message will be sent to the counterparty:

Application-level flat message will be sent to the counterparty:

Session-level message will be sent to the counterparty:

Application-level message resending request:

Error condition is detected:

Warning condition is detected:

Example.

Accepting FIX Session Without a Prior Creation of Session Object

Sometimes there is a requirement to accept an incoming FIX session "on the fly", without the prior creation of the session object. The engine exposes an ability to create a session object in response to the incoming FIX connection. To take advantage of this feature it is necessary to implement and subscribe to the Engine.DynamicAcceptorListener listener in the engine object.

The event arguments object provides information to make a decision on whether to accept the connection:

• incoming FIX logon message
• session identification information (session id) — SenderCompId, TargetCompId, etc.

To accept the incoming connection:

1. session object needs to be created using session identification information (session id) provided in the event arguments or logon message
2. created Session object is passed to the createdSession property of the event arguments object

Otherwise, the incoming connection will be rejected. Optionally a reject reason can be passed to the event arguments object.

Example.

Connecting using Custom Logon Message

Sometime there is a need to set additional fields (e.g. Username(553), Password(554)) in the initiation logon message. In this case the following method can be used:

Example.

Check also Samples :: Credential, the CredentialBuySide example.

Disconnecting using Custom Logout Message

If there is a need to set additional fields in the Logout(5) message then the custom logout message can be configured.

This custom logout message can be set on the session object:

Example.

Or this custom logout message can be passed to the logout method:

Example.

Logon Password Authentication

When Accepting an incoming FIX connection additional authentication checks may be required. The typical checks are logon username/password and source IP address. Depending on the result of the logon verification check the decision can be made whether to accept the FIX connection or reject and close the connection. This is typically performed at the logon stage.

In order to achieve this, you should subscribe to the inbound session messages and add the required check logic. If the check fails and the FIX connection needs to be rejected (closed) then an exception can be thrown from the inbound session message listener.

In the following example, the password authentication check is demonstrated.

The text from the exception goes to the FIX logout message text field (Text(58)).

Check also Samples :: Credential for paired live applications with authentication support.

Resetting Message Sequence Numbers

Session class exposes the following method to reset both incoming and outgoing message local sequence numbers to 1 and backup the previous log files:

Resetting Message Sequence Numbers via ResetSeqNumFlag Field

ResetSeqNumFlag(141) field in the Logon(A) message indicates that the both sides of the FIX session should reset sequence numbers.

To send a logon message with this field during Establishing FIX Connection, use the setResetSeqNumFlag parameter of the following method:

Resending Messages

When the Resend Request(2) message is received from the counterparty (e.g. due to a sequence number mismatch), MessageResending event is raised if an application has previously subscribed to this event. Otherwise, the SequenceReset-GapFill(4) message will be sent instead of the requested message.

If the sent application-level message needs to be resent to the counterparty then the return value of the MessageResending event listener should be set to true while handling the event. Otherwise, the SequenceReset-GapFill(4) message will be sent instead (e.g. in case of an aged order).

The message that is about to be resent is available via Msg property of the following parameter:

Example.

Memory Based Session Storage

Memory-based session storage is typically used to maintain a high-performance FIX session when persisting of session state and messages in the file system is not required.

To create such a session storageType parameter of session constructor should be set to

Async File-based Session Storage

Asynchronous File-Based Session Storage combines the good-performance with the File-Based Session Storage functionality. This storage has the same abilities as File-Based Session Storage except for the asynchronous file operations. Each this storage creates the separated thread, which will be used to perform all operations with the file system.

To create such a session storageType parameter of session constructor should be set to

Pluggable Session Storage

Pluggable session storage is the storage implemented by the user. Such storage should implement the following interfaces:

and

After implementing the instance of the above-mentioned interface the implemented storage repository should be registered in storage repository manager. Then a session with corresponding storage type can be created (see below for more details).

Example.

Please, check the pluggable-storage sample, included into distribution package of FIX Engine.

Scrambling Password in Session Storage

For the security reasons the values of the following fields can be scrambled in the session storage:

• field Password(554) in Logon(A) message

In order to achieve this on the session level the following option should be true:

Inbound Message Log Filtering

There is an option to skip saving of some inbound FIX messages to session storage. For instance, for a performance reason.

This can be configured on a per-session basis:

For instance, the

implementation is used to filter specified message types:

The space-delimited list of message types to filter is specified.

Default Threading Model

Each session instance starts two separate threads: for sending and receiving messages. The following table explains which listener could be called from each one thread.

Custom Timestamp Provider

The engine by default updates SendingTime of FIX messages to be sent to counterparty using internally implemented timestamp provider. Also, it uses a timestamp provider while writes timestamp of a FIX message written into a log file.

Custom timestamp provider can be implemented and passed to session in order to be used in the above-mentioned cases.

It is required to implement the following interface:

and pass an instance to the session using the following method:

Message Throttling

Some venues limit the number of messages that the venue can process during the time unit (so-called "message throttling"). If an application sends messages too often, then they can be rejected.

To not exceeds the limits, there is the method:

This method performs outgoing message throttling. It must be called before each of a send(...) function call. If the count of messages per a time unit exceeds the throttling limit, the function will block until the given time interval is passed.

To set throttling limit parameters, use the following methods:

and

Example:

Engine Level

The engine level dialect is defined with the FIX element with no id attribute specified. The dialect defined for the engine level is set implicitly for all engine sessions with such FIX version.

Example.

In this example, the dialect is set for all FIX 4.2 sessions. I.e. it changes the base FIX version definitions in the engine.

You need no additional steps to start using this dialect in your code. It must be only set in the configuration.

Session Level

The session level dialect is defined with the FIX element with id attribute specified. The dialect defined for the session level needs to be set explicitly for the selected sessions.

In this example, the dialect is defined over base FIX 4.2 version definition and has specified id. I.e. it doesn't change the base FIX version definitions in the engine.

Using FIX dialect in the code is easy.

Dialect Description

To show how to define a FIX variant Dialect using the XML-based description, there is a step-by-step explanation below. It is used by the engine. For a complete reference of the definition, capabilities refer to dialects definition XML schema.

Using QuickFIX Dialect

The engine supports dialect in the QuickFIX XML format, so you can use it as it is. Identifier (id) will be generated when a QuickFIX dialect is used. This id is equal to the dialect file name without extension. Therefore, QuickFIX dialect becomes a session-level.

Samples

Check also Samples :: Dialect for paired live applications with dialect support.

Creating SSL Context

Before establishing an SSL-secured FIX session the SSL context needs to be created. One of the methods follows.

Parameters:

• keyStoreName — key store resource name;
• trustStoreName — trust store resource name; can be set to null if you don't want to validate counterparty certificate;
• keyPassword — key pair password used during key pair generation;
• keyStorePassword — key store password;
• trustStorePassword — trust store password; can be set to null if the trust store name is set to null.

The key and trust stores are loaded as described in the Unified Resource Loading.

Acceptor with SSL

The acceptor SSL configuration is performed on the engine level via the following method.

Make sure that you configure SSL before doing engine init.

Initiator with SSL

The initiator SSL configuration is performed on the session level via the following method.

Make sure that you configure SSL before doing session logon.

SSL Configuration via System Properties

The SSL encryption can be configured via system properties instead of the

In this case the default SSL context can be used:

Key and Certificate Management

To perform key and certificate management the keytool can be used. This tool is a part of JDK package and the complete documentation can be found in the JDK documentation → Tools & Tool APIs → Security.

Below you can find the simplified pre-steps to do in order to organize secure communication between two parties.

Samples

Check also Samples :: SSL for paired live applications with SSL support.

Session tuning-up

Updating Engine configuration

Manipulating FIX messages

While constructing FIX messages, each time message, that has to be sent, is not efficient, because it involves memory allocation and subsequent destruction. The following class provides ability to reuse a message of a particular type:

It exposes the following method:

It wipes out all the FIX fields, assigned to the given instance. This method does not deallocate all memory occupied, it just brings the message to the initial state as it was just constructed. However, after the previously allocated memory is reused, thus, the second use of the object allows to setup FIX fields faster.

Session Tuning-up

There are many settings in the Session class and this section covers the only subset that relates to high-throughput workloads.

Updating Engine configuration

Transport Layer and the TCP/IP Stack

There are many options in the protocol stack that can affect the efficiency of the data delivery. You must understand the characteristics of the version of the stacks you are running, and that they are compatible with the versions and options on the other stacks.

Session Tuning-up