uk.co.real_logic.artio.library

Class FixLibrary

java.lang.Object

uk.co.real_logic.artio.GatewayProcess

uk.co.real_logic.artio.library.FixLibrary

All Implemented Interfaces:

java.lang.AutoCloseable

public class FixLibrary
extends GatewayProcess

FIX Library instances represent a process in the gateway where session management, message parsing and API users configure the gateway.

Libraries can be run in the same process as the engine, or in a different process.

FixLibrary instances are not thread safe and should be run on their own thread.

See Also:

FixEngine

Field Summary

Fields

Modifier and Type	Field and Description
static int	CURRENT_SEQUENCE
static int	NO_MESSAGE_REPLAY

Fields inherited from class uk.co.real_logic.artio.GatewayProcess

aeron, errorHandler, fixCounters, monitoringAgent, monitoringFile, NO_CONNECTION_ID, NO_CORRELATION_ID

Method Summary

Modifier and Type	Method and Description
void	close() Close the Library.
static FixLibrary	connect(LibraryConfiguration configuration) Start connecting to an engine.
java.lang.String	currentAeronChannel()
java.util.List<uk.co.real_logic.artio.ilink.ILink3Connection>	fixPConnections() Get a list of the currently active FIXP connections.
Reply<java.lang.Long>	followerFixPSession(uk.co.real_logic.artio.fixp.FixPContext context, long testTimeoutInMs) Create a FixPConnection for a FIXP Session from a different Artio instance.
Reply<SessionWriter>	followerSession(uk.co.real_logic.artio.builder.SessionHeaderEncoder headerEncoder, long timeoutInMs) Create a SessionWriter for a Session from a different Artio instance.
java.util.List<uk.co.real_logic.artio.ilink.ILink3Connection>	iLink3Sessions() Deprecated.
Reply<uk.co.real_logic.artio.ilink.ILink3Connection>	initiate(uk.co.real_logic.artio.ilink.ILink3ConnectionConfiguration configuration) Initiate an ILink3 connection.
Reply<Session>	initiate(SessionConfiguration configuration) Initiate a FIX session.
boolean	isAtEndOfDay()
boolean	isClosed()
boolean	isConnected() Check if the library is connected to an engine.
int	libraryId() Get the identifier of the library.
java.util.List<Session>	pendingInitiatorSessions() Get a list of the initiator sessions that are currently pending.
int	poll(int fragmentLimit) Poll the library all of its component sessions to process any messages and events that have received from or should be sent to the engine.
void	readMetaData(long sessionId, MetadataHandler handler) Read the meta data associated with a session.
Reply<uk.co.real_logic.artio.messages.SessionReplyStatus>	releaseToGateway(Session session, long timeoutInMs) Release this session object to the gateway to manage.
Reply<uk.co.real_logic.artio.messages.SessionReplyStatus>	requestSession(long sessionId, int resendFromSequenceNumber, int resendFromSequenceIndex, long timeoutInMs) Request a session be acquired from the Gateway.
java.util.List<Session>	sessions() Get a list of the currently active sessions.
SessionWriter	sessionWriter(long sessionId, long connectionId, int sequenceIndex) Creates a new SessionWriter for a specified session.
protected boolean	shouldRethrowExceptionInErrorHandler()
Reply<uk.co.real_logic.artio.messages.MetaDataStatus>	writeMetaData(long sessionId, int metaDataUpdateOffset, org.agrona.DirectBuffer buffer, int offset, int length) Write meta data associated with a session.

Methods inherited from class uk.co.real_logic.artio.GatewayProcess

conductorAgent, configureAeronContext, init, initAeron, initMonitoring, initMonitoringAgent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_MESSAGE_REPLAY

public static final int NO_MESSAGE_REPLAY

See Also:

Constant Field Values

CURRENT_SEQUENCE

public static final int CURRENT_SEQUENCE

See Also:

Constant Field Values

Method Detail

connect

public static FixLibrary connect(LibraryConfiguration configuration)

Start connecting to an engine. This method returns a FixLibrary immediately even if it hasn't connected. You should call poll(int) on a regular duty cycle until the connection completes. isConnected() can be polled in order to determine whether library is connected. Also the LibraryConnectHandler.onConnect(FixLibrary) method will be invoked.

Parameters:

configuration - the configuration for this library instance.

Returns:

the library instance.

Throws:

FixGatewayException - if there's an error connecting to the FIX Gateway.

poll

public int poll(int fragmentLimit)

Poll the library all of its component sessions to process any messages and events that have received from or should be sent to the engine.

Parameters:

fragmentLimit - the maximum number of events to read from the engine.

Returns:

0 if no work was performed, > 0 otherwise.

isConnected

public boolean isConnected()

Check if the library is connected to an engine.

Note that this refers to whether a library is connected to a FIX Engine, not whether of its sessions are connected.

Returns:

true if the library is connected to an engine, false otherwise.

See Also:

Session.isConnected(), FixEngine

isAtEndOfDay

public boolean isAtEndOfDay()

isClosed

public boolean isClosed()

libraryId

public int libraryId()

Get the identifier of the library.

Returns:

the identifier of the library.

sessions

public java.util.List<Session> sessions()

Get a list of the currently active sessions.

Note: the list is unmodifiable.

Returns:

a list of the currently active sessions.

pendingInitiatorSessions

public java.util.List<Session> pendingInitiatorSessions()

Get a list of the initiator sessions that are currently pending. This means that the session has succesfully connected via TCP but it hasn't completed the FIX initiator logon process yet. Once a session in this list sends it's Logon message and receives a valid Logon message in response then its state becomes ACTIVE and it is moved to the sessions() list.

Note: the list is unmodifiable.

Returns:

a list of tthe initiator sessions that are currently pending.

close

public void close()

Close the Library. This will also remove all files associated with the library.

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class GatewayProcess

initiate

public Reply<Session> initiate(SessionConfiguration configuration)

Initiate a FIX session. Artio will connect to the specified FIX acceptor / server and attempt to logon. This method returns a reply object wrapping the Session itself.

Parameters:

configuration - the configuration to use for the session.

Returns:

the session object for the session that you've initiated. It can return the following errors: IllegalStateException if you're trying to initiate two sessions at the same time or if there's a timeout talking to the FixEngine. This probably indicates that there's a problem in your code or that your engine isn't running. FixGatewayException if you're unable to connect to the accepting gateway. This probably indicates a configuration problem related to the external gateway.

See Also:

LibraryUtil.initiate(FixLibrary, SessionConfiguration, int, IdleStrategy)

releaseToGateway

public Reply<uk.co.real_logic.artio.messages.SessionReplyStatus> releaseToGateway(Session session,
                                                                                  long timeoutInMs)

Release this session object to the gateway to manage. If the release operation has successfully completed then it will return SessionReplyStatus.OK. Similar to initiate(SessionConfiguration) this is a non-blocking operation that returns a reply object that indicates what has happened to its result.

Parameters:

session - the session to release

timeoutInMs - the timeout for this operation

Returns:

the result of this operation.

requestSession

public Reply<uk.co.real_logic.artio.messages.SessionReplyStatus> requestSession(long sessionId,
                                                                                int resendFromSequenceNumber,
                                                                                int resendFromSequenceIndex,
                                                                                long timeoutInMs)

Request a session be acquired from the Gateway. It returns a LibraryReply object. If this session is being managed by the gateway then your SessionAcquireHandler will receive a callback and the reply will be SessionReplyStatus.OK. You may also receive the reply of SessionReplyStatus.SEQUENCE_NUMBER_TOO_HIGH if the sequence number you have passed in is higher than the current sequence number known by the engine. This may happen to a sequence reset. In this case you will still get the callback to the SessionAcquireHandler but won't get a replay on any messages. You will also get a callback on the SessionAcquireHandler in the SessionReplyStatus.MISSING_MESSAGES and SessionReplyStatus.INVALID_CONFIGURATION_NOT_LOGGING_MESSAGES case but you won't necessarily get the requested replay of messages. If another library has acquired the session then this method will return SessionReplyStatus.OTHER_SESSION_OWNER. If the connection id refers to an unknown session then the method returns SessionReplyStatus.UNKNOWN_SESSION. If this library instance is unknown to the gateway, for example if its heartbeating mechanism has timed out due to poll(int) not being called often enough. If you request a session that exists in the engine but which is not connected then an offline session will be returned. This is a session whose state is disconnected and has no connection id, connectedHost or connectedPort.

Parameters:

sessionId - the id of the session to acquire.

resendFromSequenceNumber - the last received message sequence number that you know about. You will get a stream of messages replayed to you from resendFromSequenceNumber to the latest message sequence number. If you don't care about message replay then use NO_MESSAGE_REPLAY as the parameter.

resendFromSequenceIndex - the index of the sequence within which the resendFromSequenceNumber refers. if you wish to use the curren sequence (ie all messages since the latest logon then you can use CURRENT_SEQUENCE.If you don't care about message replay then use NO_MESSAGE_REPLAY as the parameter.

timeoutInMs - the timeout for this operation

Returns:

the reply object representing the result of the request.

sessionWriter

public SessionWriter sessionWriter(long sessionId,
                                   long connectionId,
                                   int sequenceIndex)

Creates a new SessionWriter for a specified session. This can be used in a clustered system to write messages outbound for a system on its primary node. In a clustered system the SessionProxy would be hooked so writing messages outbound on a normal Session object won't work. Messages written using this writer won't update the sent sequence number of any corresponding Session object. This is designed to support the intended use-case of hooking the session proxy.

Parameters:

sessionId - the id of the session to use.

connectionId - the id of the connection to use.

sequenceIndex - the sequence index that the SessionWriter should start at.

Returns:

the created SessionWriter

followerSession

public Reply<SessionWriter> followerSession(uk.co.real_logic.artio.builder.SessionHeaderEncoder headerEncoder,
                                            long timeoutInMs)

Create a SessionWriter for a Session from a different Artio instance. This SessionWriter can be used in a clustered system to fill the archive on a follower node with FIX messages that have been replicated by a leader node. Messages written using this writer will update the sent sequence number of any corresponding Session object. This allows offline sessions to be created using this method and messages sent via either the SessionWriter or the Session itself. For the FIX version see followerFixPSession(FixPContext, long).

Parameters:

headerEncoder - the message header that contains fields that identify the Session. You could set the senderCompId and targetCompId on this header for example if those are the fields used to identify your session.

timeoutInMs - the timeout required for this operation.

Returns:

a Reply that will eventually contain the SessionWriter.

followerFixPSession

public Reply<java.lang.Long> followerFixPSession(uk.co.real_logic.artio.fixp.FixPContext context,
                                                 long testTimeoutInMs)

Create a FixPConnection for a FIXP Session from a different Artio instance. This FixPConnection can be used in a clustered system to fill the archive on a follower node with FIX messages that have been replicated by a leader node. This allows offline sessions to be created using this method. When a connection is re-established with the correct logon credentials then the messages written via this offline session can be retransmitted. If a session already exists within the engine with the same identity then no duplicate session will be created and the session id of the original session will be returned. In the case that the session is currently connected, care must be taken to ensure that the version of the FIXP connection is the same as the connected session id or an error will be returned. For the FIX version see followerSession(SessionHeaderEncoder, long).

Parameters:

context - the context that uniquely identifies the connection

testTimeoutInMs - the timeout required for this operation.

Returns:

the sessionId that can be used to request the offline sesion object using requestSession(long, int, int, long).

Throws:

java.lang.IllegalArgumentException - if the FixPProtocol of the context is different to the established protocol within the library.

writeMetaData

public Reply<uk.co.real_logic.artio.messages.MetaDataStatus> writeMetaData(long sessionId,
                                                                           int metaDataUpdateOffset,
                                                                           org.agrona.DirectBuffer buffer,
                                                                           int offset,
                                                                           int length)

Write meta data associated with a session. Session meta-data is a sequence of bytes that application can associate with a session. It shares it's lifecycle with the current session - so whenever sequence numbers or seession ids are reset the old meta-data will be reset as well. If the session is persistent then the metadata persists over restarts. You can use session meta data to store information like ids for internal systems that correspond to FIX sessions. This method can be used both to update existing metadata and to initialise the sessions' metadata. When updating any metadata before the metaDataOffset position within the metadata buffer or after metaDataOffset + length will be left as previous. When i This is an asynchronous operation and the returned reply object should be checked for completion.

Parameters:

sessionId - the session id of the session that meta data is written to.

metaDataUpdateOffset - the offset within the session's metadata buffer. 0 should be used for initialization.

buffer - the buffer where the meta data to be written is stored.

offset - the offset within the buffer

length - the length of the data within the buffer.

Returns:

a Reply to indicate completion or an error code.

readMetaData

public void readMetaData(long sessionId,
                         MetadataHandler handler)

Read the meta data associated with a session.

Parameters:

sessionId - the id of the session that meta data is read from.

handler - the callback that has the returned metadata.

currentAeronChannel

public java.lang.String currentAeronChannel()

initiate

public Reply<uk.co.real_logic.artio.ilink.ILink3Connection> initiate(uk.co.real_logic.artio.ilink.ILink3ConnectionConfiguration configuration)

Initiate an ILink3 connection. Artio will connect to the iLink server and attempt to logon. This method returns a reply object wrapping the Connection itself. NB: This is an experimental API and is subject to change or potentially removal.

Parameters:

configuration - the configuration for this Session.

Returns:

a reply object wrapping the Connection itself.

See Also:

https://github.com/real-logic/artio/wiki/ILink-3-Support

iLink3Sessions

@Deprecated
public java.util.List<uk.co.real_logic.artio.ilink.ILink3Connection> iLink3Sessions()

Deprecated.

Get a list of the currently active ILink3 Sessions.

Note: the list is unmodifiable. This method has been deprecated and will be replaced by fixPConnections() it will continue to work until then.

Returns:

a list of the currently active ILink3 Sessions

fixPConnections

public java.util.List<uk.co.real_logic.artio.ilink.ILink3Connection> fixPConnections()

Get a list of the currently active FIXP connections.

Note: the list is unmodifiable.

Returns:

a list of the currently active FIXP connections.

shouldRethrowExceptionInErrorHandler

protected boolean shouldRethrowExceptionInErrorHandler()

Specified by:

shouldRethrowExceptionInErrorHandler in class GatewayProcess