Built by Maven

Programming Guide

Introduction

In real life, FIX connections occur at regular intervals. Many trading systems publish schedules defining active trading windows. The biz.onixs.fix.engine.Session object exposes members for basic FIX connection handling and automatic reconnection in case of transport failures. However, it does not maintain connections on a systematic basis according to trading calendars.

To satisfy these real‑life scheduling needs, the session scheduler component is provided. This service automatically connects certain FIX sessions to the counterparty at the beginning of the trading day (or week), keeps them connected during active hours, and disconnects them at the end of the trading period. It is also possible to keep a FIX session connected for an entire trading week and disconnect it at the end of the last trading day.

Main Class

The biz.onixs.fix.scheduler.SessionScheduler class is the workhorse of the session scheduler component. It exposes a simple but comprehensive API to handle connections by schedules of any complexity.

Registering a Session

Use biz.onixs.fix.scheduler.SessionScheduler.register(Session, SessionSchedule, SessionConnection) to register a session for automatic logon and logout according to the specified schedule.

Note: If a session is registered at a time that falls within its active period, the scheduler connects the session immediately.

Unregistering a Session

Use biz.onixs.fix.scheduler.SessionScheduler.unregister(Session) to remove a session from the scheduler.

Note: Unregistering does not disconnect an already active connection. If a session was connected by the scheduler, it remains connected until explicitly logged out.

Error Notification

The scheduler accepts the biz.onixs.fix.scheduler.ErrorListener event listener to deliver notifications about errors in session management (e.g., connection failures, schedule misconfigurations).

Scheduler Algorithm

The scheduler’s operation can be summarized as follows:

  1. Resolve Active Windows
    Evaluate all registered schedules to determine which sessions should be active at the current date and time.

  2. Connect When Active
    For each session whose schedule is active:

    • If the session is disconnected, attempt to connect using the configured connection parameters.
    • Apply retry policy (from connection settings) when a connection attempt fails, until the active window ends or a connection succeeds.

  3. Maintain Connectivity
    Keep each active session connected for its scheduled duration. If a disconnection occurs during the active window, automatically reconnect according to the policy.

  4. Disconnect When Inactive
    When the active period ends, gracefully log out and close the TCP connection.

  5. Repeat
    Continuously monitor schedules and adjust connections as time progresses.

Programmatic Configuration

Different schedule implementations are available to describe daily or multi‑day behavior.

Single‑day and Multi‑day Schedule

The first two parameters (firstDay, lastDay) define the activity week. During these days the session will always be connected at logonTime and disconnected at logoutTime if the specified duration equals a single day. If a session must remain connected for multiple days, it connects at logonTime on firstDay and disconnects at logoutTime on lastDay.

The logonTime and logoutTime parameters define the time of logon and logout for each activity day when the duration is a single day. If the session must continue for the entire week, logonTime is the logon on the first day of the activity week, and logoutTime is the logout on the last day of the activity week.

Finally, the resetPolicy parameter specifies whether sequence numbers must be reset and on which basis (never, daily, or weekly).

Reset on Every Connection

Some operations require starting every connection as a fresh FIX session — regardless of whether it is the first scheduled logon or a reconnect after a TCP error.

To achieve this:

  • Send a Logon with ResetMsgSeqNumFlag=Y (tag 141) on every connection.
  • setSetResetSeqNumbers(true) adds the flag to the initial engine‑initiated Logon only.
  • For reconnects after TCP errors, provide a custom Logon that also includes 141=Y, and ensure these settings are reapplied before each reconnect attempt.

Example FIX 4.4 Logon:

8=FIX.4.4|9=***|35=A|34=1|49=SENDER|56=TARGET|98=0|108=30|141=Y|10=***|

Example using biz.onixs.fix.scheduler.InitiatorConnection:

InitiatorConnection ic = new InitiatorConnection();
ic.setCustomLogonMessageFieldDelimiter("|");
ic.setCustomLogonMessage("8=FIX.4.4|9=***|35=A|34=1|49=SENDER|56=TARGET|98=0|108=30|141=Y|10=***|");
ic.setSetResetSeqNumbers(true); // for initial scheduled logon

File-based Configuration

To simplify development, the scheduler allows defining session schedules and connection settings in a configuration file and referencing them from code.

The presets can be loaded using biz.onixs.fix.scheduler.SchedulerSettingsLoader. Both schedules and connection settings can then be referenced via string identifiers.

Configuration File Reference

The configuration file has an XML‑based format. The XML schema is available at: https://ref.onixs.biz/fix/scheduler/scheduler-settings-1.7.xsd

Connection Management and Multiple Addresses

By design, a FIX session is a bilateral connection — a single initiator and a single acceptor. Therefore, the

biz.onixs.fix.engine.Session object accepts only **one host + port** pair.

The scheduler extends this behavior by acting as a connection manager providing a list of addresses (or a single one) as connection parameters. During connection attempts, the scheduler tries each address in order until a successful connection is established.

You can mimic the scheduler's behavior manually, but the Session object obeys the common FIX rule – a session is a bilateral connection which has only two ends – single initiator and single acceptor. Therefore, the Session object accepts only one host + port pair. The Scheduler acts as a connection manager providing a list of addresses (or only one if set) as the connection parameters.

Quartz Configuration

The session scheduler uses the Quartz Scheduler library internally.

At start, Quartz is configured using the bundled default configuration:

org.quartz.scheduler.instanceName: DefaultQuartzScheduler
org.quartz.scheduler.rmi.export: false
org.quartz.scheduler.rmi.proxy: false
org.quartz.scheduler.wrapJobExecutionInUserTransaction: false

org.quartz.threadPool.class: org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount: 10
org.quartz.threadPool.threadPriority: 5
org.quartz.threadPool.threadsInheritContextClassLoaderOfInitializingThread: true

org.quartz.jobStore.misfireThreshold: 60000

org.quartz.jobStore.class: org.quartz.simpl.RAMJobStore

org.quartz.scheduler.skipUpdateCheck: true

This configuration file is located inside the session scheduler JAR.

A custom Quartz configuration can be provided via

biz.onixs.fix.scheduler.SessionScheduler.setQuartzConfigFile(String).

Samples

Check also Samples :: Scheduler.