uk.co.real_logic.artio.engine

Class FixEngine

java.lang.Object

uk.co.real_logic.artio.GatewayProcess

uk.co.real_logic.artio.engine.FixEngine

All Implemented Interfaces:

java.lang.AutoCloseable

public final class FixEngine
extends GatewayProcess

A FIX Engine is a process in the gateway that accepts or initiates FIX connections and hands them off to different FixLibrary instances. The engine can replicate and/or durably store streams2 of FIX messages for replay, archival, administrative or analytics purposes.

Each engine can have one or more associated libraries that manage sessions and perform business logic. These may run in the same JVM process or a different JVM process.

See Also:

FixLibrary

Field Summary

Fields

Modifier and Type	Field and Description
static int	ENGINE_LIBRARY_ID

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
java.util.List<FixPSessionInfo>	allFixPSessions() Gets session info for all FIXP sessions the FixEngine is aware of including offline ones.
java.util.List<SessionInfo>	allSessions() Gets session info for all FIX sessions the FixEngine is aware of including offline ones.
Reply<?>	bind() Binds the acceptor socket to the configured address.
void	close() Close the engine down, including stopping other running threads.
EngineConfiguration	configuration()
boolean	isClosed() Find out whether the close() operation has been called.
static FixEngine	launch(EngineConfiguration configuration) Launch the engine.
Reply<java.util.List<LibraryInfo>>	libraries() Query the engine for the list of libraries currently active.
Reply<org.agrona.concurrent.status.ReadablePosition>	libraryIndexedPosition(int libraryId) Gets a ReadablePosition that exposes where the Artio indexer has indexed up to for a library id.
Reply<java.lang.Long>	lookupSessionId(java.lang.String localCompId, java.lang.String remoteCompId, java.lang.String localSubId, java.lang.String remoteSubId, java.lang.String localLocationId, java.lang.String remoteLocationId) Gets the session id associated with some combination of id fields.
Reply<org.agrona.collections.Long2LongHashMap>	pruneArchive(org.agrona.collections.Long2LongHashMap recordingIdToMinimumPrunePositions) Frees up space from the Aeron archive of messages.
Reply<?>	resetSequenceNumber(long sessionId) Resets the sequence number of a given session.
Reply<?>	resetSessionIds(java.io.File backupLocation) Deprecated.
void	resetState(java.io.File backupLocation) This method resets the state of the of the FixEngine that also performs usual end of day processing operations.
protected boolean	shouldRethrowExceptionInErrorHandler()
Reply<?>	unbind() Unbinds the acceptor socket.
Reply<?>	unbind(boolean endOfDay) Unbinds the acceptor socket, and optionally starts an end of day operation if requested.

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

ENGINE_LIBRARY_ID

public static final int ENGINE_LIBRARY_ID

See Also:

Constant Field Values

Method Detail

launch

public static FixEngine launch(EngineConfiguration configuration)

Launch the engine. This method starts up the engine threads and then returns.

Parameters:

configuration - the configuration to use for this engine.

Returns:

the new FIX engine instance.

libraries

public Reply<java.util.List<LibraryInfo>> libraries()

Query the engine for the list of libraries currently active. If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Returns:

a list of currently active libraries.

unbind

public Reply<?> unbind()

Unbinds the acceptor socket. This does not disconnect any currently connected TCP connections. If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Returns:

the reply object, or null if the request hasn't been successfully enqueued.

unbind

public Reply<?> unbind(boolean endOfDay)

Unbinds the acceptor socket, and optionally starts an end of day operation if requested. The end of day operation performs the following steps:

1. Sends a logout message to every FIX counter-party
2. Disconnects each FIX connection after it receives either a logout reply or the heartbeat timeout elapses.
3. Disconnects the libraries from the engine

If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Parameters:

endOfDay - if currently connected connections need to be logged out and disconnected

Returns:

the reply object, or null if the request hasn't been successfully enqueued.

bind

public Reply<?> bind()

Binds the acceptor socket to the configured address. This only needs to be called if you had called unbind() previously - launch() will bind the socket by default. If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Returns:

the reply object, or null if the request hasn't been successfully enqueued.

resetSessionIds

@Deprecated
public Reply<?> resetSessionIds(java.io.File backupLocation)

Deprecated.

Resets the set of session ids. Use of just this method on its own can result in inconsistent Artio state. It is recommended that you use the resetState(File) method or pruneArchive(Long2LongHashMap) instead to reset state. This method is Deprecated and may be removed in a future version of Artio.

Parameters:

backupLocation - the location to backup the current session ids file to. Can be null to indicate that no backup is required.

Returns:

the reply object, or null if the request hasn't been successfully enqueued.

resetSequenceNumber

public Reply<?> resetSequenceNumber(long sessionId)

Resets the sequence number of a given session. Asynchronous method, the Reply instance needs to be polled to ensure that it has completed. This operation can be used to reset the sequence numbers of FIX or FIXP sessions. In the case of FIXP sessions the sequence numbers can only be reset when the session is disconnected. The sequence number reset behaviour is dependent on the protocol. If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Parameters:

sessionId - the id of the session that you want to reset

Returns:

the reply object, or null if the request hasn't been successfully enqueued.

resetState

public void resetState(java.io.File backupLocation)

This method resets the state of the of the FixEngine that also performs usual end of day processing operations. It must can only be called when the FixEngine object has been closed. These are:

1. Reset and optionally back up all Artio state (including session ids and sequence numbers
2. Truncate any recordings associated with this engine instance.

Blocks until the operation is complete.

Parameters:

backupLocation - the directory that you wish to copy Artio's session state over to for later inspection. If this is null no backup of data will be performed. If the directory exists it will be re-used, if it doesn't it will be created.

Throws:

java.lang.IllegalStateException - if this FixEngine hasn't been closed when this method is called.

libraryIndexedPosition

public Reply<org.agrona.concurrent.status.ReadablePosition> libraryIndexedPosition(int libraryId)

Gets a ReadablePosition that exposes where the Artio indexer has indexed up to for a library id. This can be used to track the persistence of messages that are sent via an Artio library.

Parameters:

libraryId - the library id of the library that you want to track the position for.

Returns:

a reply that either succeeds with the ReadablePosition or errors if the Engine doesn't know about the library in question.

allSessions

public java.util.List<SessionInfo> allSessions()

Gets session info for all FIX sessions the FixEngine is aware of including offline ones. Can be used to acquire offline sessions or for administration purposes. The returned list is updated in a thread-safe manner when new sessions are created.

Returns:

the list of session infos.

allFixPSessions

public java.util.List<FixPSessionInfo> allFixPSessions()

Gets session info for all FIXP sessions the FixEngine is aware of including offline ones. The returned list is updated in a thread-safe manner when new sessions are created.

Returns:

the list of FIXP session infos.

lookupSessionId

public Reply<java.lang.Long> lookupSessionId(java.lang.String localCompId,
                                             java.lang.String remoteCompId,
                                             java.lang.String localSubId,
                                             java.lang.String remoteSubId,
                                             java.lang.String localLocationId,
                                             java.lang.String remoteLocationId)

Gets the session id associated with some combination of id fields. If the reply is null then the query hasn't been enqueued and the operation should be retried on a duty cycle.

Parameters:

localCompId - the senderCompId of messages sent by the gateway on this session.

remoteCompId - the senderCompId of messages received by the gateway on this session.

localSubId - the senderSubId of messages sent by the gateway on this session or null if not used in session identification.

remoteSubId - the senderSubId of messages received by the gateway on this session or null if not used in session identification.

localLocationId - the senderLocationId of messages sent by the gateway on this session or null if not used in session identification.

remoteLocationId - the senderLocationId of messages received by the gateway on this session or null if not used in session identification.

Returns:

the reply object asynchronously wrapping the session id

close

public void close()

Close the engine down, including stopping other running threads. This also stops accepting new connections, and logs out and disconnects all currently active FIX sessions. NB: graceful shutdown of the FixEngine will wait for logouts to occur. This entails communicating with all FixLibrary instances currently live in order for them to gracefully close as well. Therefore if you close a FixLibrary before you call this method then the close operation could be delayed by up to CommonConfiguration.replyTimeoutInMs() in order for the FixEngine to timeout the FixLibrary. In order for graceful shutdown to successfully occur you should also ensure that any connected FixLibrary instances are regularly polled on their duty cycle. This does not remove files associated with the engine, that are persistent over multiple runs of the engine.

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class GatewayProcess

isClosed

public boolean isClosed()

Find out whether the close() operation has been called.

Returns:

true if the close() operation has been called, false otherwise.

pruneArchive

public Reply<org.agrona.collections.Long2LongHashMap> pruneArchive(org.agrona.collections.Long2LongHashMap recordingIdToMinimumPrunePositions)

Frees up space from the Aeron archive of messages. This operation does not remove all entries from the Aeron archive logs: only entries that are not part of the latest sequence index. That means that resend requests for the current sequence index can still be processed. Archive logs are pruned in chunks called segments - see the Aeron Archiver documentation for details. This means that if there are less than a segment's worth of messages that can be freed up then no space is pruned. The recordingIdToMinimumPrunePositions parameter can be useful for users who are doing a Streaming backup of the Aeron Archiver log. If you are streaming off the recorded streams from Artio to an external location, eg: a cloud backup location, then this parameter allows you to stop Artio from accidentally pruning away parts of the recorded Stream that this streaming backup is processing by providing the position that this streaming recording is at.

Parameters:

recordingIdToMinimumPrunePositions - the minimum positions to prune or null otherwise. If you're archiving segments of the Aeron archive log then this parameter can be used in order to stop those segments from being removed. The hashmap should be initialised with new Long2LongHashMap(Aeron.NULL_VALUE).

Returns:

the positions pruned up to. This is a map from recording id to a pruned position if pruning has occurred. It may be empty if no recordings have been pruned. Aeron.NULL_VALUE is used to denote missing values in the map.

configuration

public EngineConfiguration configuration()

shouldRethrowExceptionInErrorHandler

protected boolean shouldRethrowExceptionInErrorHandler()

Specified by:

shouldRethrowExceptionInErrorHandler in class GatewayProcess