Programmatic Configuration

Any available option can be set via API.

final HandlerSettings settings = new HandlerSettings();
settings.getConnectionSettings().setRemoteAddress("localhost", 10000);

Properties File Configuration

Settings can be loaded from the properties file:

final HandlerSettings settings = new HandlerSettings();
settings.init("site/handler.properties");

The sample properties file follows. Not all available options are mentioned.

Host = 193.29.89.65
Port = 19508
SslEnabled = true
Timeout = 5
RSAKeyPath = /path/to/eurex-public-key.pem
HeartbeatInterval = 30000
ReconnectionSettings.Number = 3
ReconnectionSettings.Interval = 30

Property List

The configuration parameter (key) is case-sensitive. The list of available parameters follows.

Address Mapping and Failover

The handler does not implement gateway failover directly. Instead, it provides an biz.onixs.eurex.eti.handler.core.AddressMapping mechanism that transparently redirects a configured address to a different physical endpoint at connect time.

Mappings can be added programmatically via biz.onixs.eurex.eti.handler.core.ConnectionSettings.addAddressMapping(String, int, String, int):

settings.getConnectionSettings().addAddressMapping(
        "10.8.0.1", 19542,
        "10.8.0.1", 19547);

Alternatively, mappings can be defined in the properties file using the AddressMapping.N.* keys listed in the Property List:

AddressMapping.1.From.Host = 10.8.0.1
AddressMapping.1.From.Port = 19542
AddressMapping.1.To.Host   = 10.8.0.1
AddressMapping.1.To.Port   = 19547

Automatic Disconnection

The handler automatically terminates the session in the following cases:

• Remote close (EOF) — the exchange closes the TCP connection; the inbound stream signals end-of-stream and the receiver exits cleanly.
• I/O error — any unrecoverable exception on the receive path triggers an immediate disconnect.
• Unexpected logoff — a LogoutResponse received from the exchange stops the session cleanly.

Note on heartbeat timeout: a socket read timeout (derived from HeartbeatInterval and ReasonableTransmissionTime) is used only as an anti-hang guard on the read loop and does not close the connection by itself. Only an actual TCP close or hard I/O error triggers a disconnect.

Reconnection

Reconnection behavior is controlled via biz.onixs.eurex.eti.handler.core.ReconnectionSettings, configured as part of biz.onixs.eurex.eti.handler.core.HandlerSettings.

When ReconnectionSettings.Number > 0 and an unexpected connection loss is detected, the handler:

1. Performs a clean disconnect: CONNECTED → DISCONNECTING → DISCONNECTED.
2. Resets the outbound MsgSeqNum to 1 (a fresh session is started on each reconnect).
3. Makes up to Number + 1 total connection attempts (1 initial attempt plus up to Number retries), waiting Interval seconds between failed attempts (default: 3 retries, 30 s apart).

If all attempts fail the handler stays DISCONNECTED. If a later reconnect succeeds and the connection is lost again, the same cycle repeats with a fresh attempt budget. There is no cumulative cap on reconnect cycles. Set ReconnectionSettings.Number = 0 to disable automatic reconnection.

The relevant properties are listed in the Property List.

State Monitoring

Implement the biz.onixs.eurex.eti.handler.core.event.HandlerStateListener interface and register it via biz.onixs.eurex.eti.handler.core.Handler.setHandlerStateListener(HandlerStateListener) to be notified of every state transition.

handler.setHandlerStateListener(new MyHandlerStateListener());

public class MyHandlerStateListener implements HandlerStateListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyHandlerStateListener.class);

    public void onStateChange(HandlerState oldState, HandlerState newState) {
        LOG.info("Handler state changed: {} -> {}", oldState, newState);
    }
}

The handler moves through the following states: NOT_INITED → DISCONNECTED → CONNECTING → CONNECTED → DISCONNECTING → DISCONNECTED.

Each individual reconnect attempt produces its own observable state-transition pair. With ReconnectionSettings.Number = N and all attempts failing after an unexpected drop:

DISCONNECTED → CONNECTING → CONNECTED          initial logon succeeded
CONNECTED → DISCONNECTING → DISCONNECTED       unexpected drop detected
DISCONNECTED → CONNECTING → DISCONNECTED       reconnect attempt 1 of N+1 failed
...
DISCONNECTED → CONNECTING → DISCONNECTED       reconnect attempt N+1 of N+1 failed

The number of CONNECTING → DISCONNECTED transitions equals the number of failed attempts. If a reconnect attempt succeeds the last pair becomes DISCONNECTED → CONNECTING → CONNECTED and the handler resumes normal operation.

End-of-Day

The handler does not perform end-of-day cleanup automatically. The exchange signals the end of the trading session via a biz.onixs.eurex.eti.handler.message.TradingSessionStatusBroadcast message with tradSesEvent equal to TradSesEvent.END_OF_DAY_SERVICE, delivered to the biz.onixs.eurex.eti.handler.core.event.OtherListener.onTradingSessionStatusBroadcast(TradingSessionStatusBroadcast) callback. The application should react to this event by performing any required cleanup and calling disconnect().

Thread Affinity

To reduce CPU cache misses the sender and receiver threads can be pinned to specific cores via biz.onixs.eurex.eti.handler.core.HandlerSettings.setSendingThreadAffinity(int[]) and biz.onixs.eurex.eti.handler.core.HandlerSettings.setReceivingThreadAffinity(int[]). Pass an array of zero-based CPU indices:

settings.setSendingThreadAffinity(new int[]{0});
settings.setReceivingThreadAffinity(new int[]{1});

Inbound Messages

Implement the biz.onixs.eurex.eti.handler.core.event.InboundMessageListener interface and register it via biz.onixs.eurex.eti.handler.core.Handler.setInboundMessageListener(InboundMessageListener) to receive a callback for every message received from the exchange.

handler.setInboundMessageListener(new MyInboundMessageListener());

public class MyInboundMessageListener implements InboundMessageListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyInboundMessageListener.class);

    public void onInboundMessage(Message message) {
        LOG.debug("Received {} seq={}: {}", message.getTemplateId(), message.getMsgSeqNum(), message);
    }
}

Outbound Messages

Implement the biz.onixs.eurex.eti.handler.core.event.OutboundMessageListener interface and register it via biz.onixs.eurex.eti.handler.core.Handler.setOutboundMessageListener(OutboundMessageListener) to receive a callback for every message sent to the exchange.

handler.setOutboundMessageListener(new MyOutboundMessageListener());

public class MyOutboundMessageListener implements OutboundMessageListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyOutboundMessageListener.class);

    public void onOutboundMessage(Message message) {
        LOG.debug("Sent {} seq={}: {}", message.getTemplateId(), message.getMsgSeqNum(), message);
    }
}

Persistence and Querying

The handler does not persist messages internally. The listener callbacks above are the integration point for application-level persistence: write messages to a database, append them to a file, or publish them to a message bus as the application requires.

Note that the Message object passed to onInboundMessage is reused across callbacks for performance - see Message Thread Safety if you need to hold a reference beyond the callback.

Requesting Retransmission

Use biz.onixs.eurex.eti.handler.message.RetransmitRequest to request retransmission of a missed sequence range. Set the refApplId to identify the stream (e.g. RefApplId.TRADE), the partitionId, and the begin/end sequence numbers of the gap.

void requestRetransmit(Handler handler, int partitionId, long firstMissing, long lastMissing) {
    RetransmitRequest request = new RetransmitRequest();
    request.setRefApplId(RefApplId.TRADE);
    request.setPartitionId(partitionId);
    request.setApplBegSeqNum(firstMissing);
    request.setApplEndSeqNum(lastMissing);
    handler.send(request);
}

For Matching Engine messages (order and quote events) use biz.onixs.eurex.eti.handler.message.RetransmitMEMessageRequest instead, which identifies the range by message ID rather than sequence number.

Handling the Response

The exchange acknowledges the request and begins retransmission. The acknowledgement is delivered to the biz.onixs.eurex.eti.handler.core.event.AdminListener callbacks:

• biz.onixs.eurex.eti.handler.core.event.AdminListener.onRetransmitResponse(RetransmitResponse) for broadcast stream retransmission
• biz.onixs.eurex.eti.handler.core.event.AdminListener.onRetransmitMEMessageResponse(RetransmitMEMessageResponse) for Matching Engine message retransmission

The retransmitted messages themselves arrive through the same typed listeners as regular inbound messages.

Message Receiving

For each message type the Handler has a static object that is used for deserialization and calling a user code callback. This means that you can't use reference to the message from the callback and need to create your own copy if you want to process the message later in a separate thread.

Message Sending

The Handler uses message objects passed to send method even after the user returns control from this method. There is a queue to which the Handler adds these objects and until they are serialized to bytes and sent over the network the user should not make any changes to these objects.

Error Listener

The handler uses exceptions to report errors that occurred while performing a certain action. For example, the handler will raise a regular exception to report the inability to find an actual license for the product. However, the handler processes data asynchronously; therefore, the handler is not able to report any further errors since the data processing is started. For this reason, the handler exposes the

method to subscribe to error events.

handler.setErrorListener(new MyErrorListener());

Once an instance of error listener is assigned to the handler, it will invoke the

method each time an error occurs.

public class MyErrorListener implements ErrorListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyErrorListener.class);

    public void onError(ErrorCode errorCode, String description) {
        LOG.error("onError(): errorCode={}, description={}", errorCode, description);
    }
}

Warning Listener

Miscellaneous non-critical issues may occur while the handler is being executed. The handler will process such issues by itself; thus, no special steps are required for such cases. However, sometimes it's reasonable to be notified about such events. For this reason, the handler exposes the

method to subscribe to warning events.

handler.setWarningListener(new MyWarningListener());

When an instance of warning listener is assigned to the handler, it will invoke the

method each time a warning occurs.

public class MyWarningListener implements WarningListener {
    private static final Logger LOG = LoggerFactory.getLogger(MyWarningListener.class);

    public void onWarning(String description) {
        LOG.warn("onWarning(): description={}", description);
    }
}

Administrative Message Events

To be notified about administrative message events, implement the

handler.setAdminListener(new MyAdminListener());

The sample interface implementation demonstrates available message events to receive.

public class MyAdminListener implements AdminListener {
    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.Reject} message received.
     * @param message message
     */
    public void onReject(Reject message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.RetransmitMEMessageResponse} message received.
     * @param message message
     */
    public void onRetransmitMEMessageResponse(RetransmitMEMessageResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.RetransmitResponse} message received.
     * @param message message
     */
    public void onRetransmitResponse(RetransmitResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.SubscribeResponse} message received.
     * @param message message
     */
    public void onSubscribeResponse(SubscribeResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.UnsubscribeResponse} message received.
     * @param message message
     */
    public void onUnsubscribeResponse(UnsubscribeResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.UserLoginResponse} message received.
     * @param message message
     */
    public void onUserLoginResponse(UserLoginResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.UserLogoutResponse} message received.
     * @param message message
     */
    public void onUserLogoutResponse(UserLogoutResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.InquireSessionListResponse} message received.
     * @param message message
     */
    public void onInquireSessionListResponse(InquireSessionListResponse message) {
    }

    /**
     * Notifies about the outgoing message.
     * @param message message
     */
    public void onOutboundMessage(Message message) {
    }

    /**
     * Notifies about the inbound message.
     * @param message message
     */
    public void onInboundMessage(Message message) {
    }
}

Order Handling Message Events

To be notified about order handling message events, implement the

handler.setOrderHandlingListener(new MyOrderHandlingListener());

The sample interface implementation demonstrates available message events to receive.

class MyOrderHandlingListener implements OrderHandlingListener {
    /**
     * * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllOrderNRResponse} message received.
     * @param message message
     */
    public void onDeleteAllOrderNRResponse(DeleteAllOrderNRResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllOrderBroadcast} message received.
     * @param message message
     */
    public void onDeleteAllOrderBroadcast(DeleteAllOrderBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllOrderResponse} message received.
     * @param message message
     */
    public void onDeleteAllOrderResponse(DeleteAllOrderResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteOrderBroadcast} message received.
     * @param message message
     */
    public void onDeleteOrderBroadcast(DeleteOrderBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteOrderNRResponse} message received.
     * @param message message
     */
    public void onDeleteOrderNRResponse(DeleteOrderNRResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteOrderResponse} message received.
     * @param message message
     */
    public void onDeleteOrderResponse(DeleteOrderResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.ModifyOrderNRResponse} message received.
     * @param message message
     */
    public void onModifyOrderNRResponse(ModifyOrderNRResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.ModifyOrderResponse} message received.
     * @param message message
     */
    public void onModifyOrderResponse(ModifyOrderResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.NewOrderNRResponse} message received.
     * @param message message
     */
    public void onNewOrderNRResponse(NewOrderNRResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.NewOrderResponse} message received.
     * @param message message
     */
    public void onNewOrderResponse(NewOrderResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.MassOrderAck} message received.
     * @param message message
     */
    @Override
    public void onMassOrderAck(MassOrderAck message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.OrderExecNotification} message received.
     * @param message message
     */
    public void onOrderExecNotification(OrderExecNotification message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.OrderExecReportBroadcast} message received.
     * @param message message
     */
    public void onOrderExecReportBroadcast(OrderExecReportBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.OrderExecResponse} message received.
     * @param message message
     */
    public void onOrderExecResponse(OrderExecResponse message) {
    }
}

Quote Handling Message Events

To be notified about quote handling message events, implement the

handler.setQuoteHandlingListener(new MyQuoteHandlingListener());

The sample interface implementation demonstrates available message events to receive.

public class MyQuoteHandlingListener implements QuoteHandlingListener {
    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllOrderQuoteEventBroadcast} message received.
     * @param message message
     */
    public void onDeleteAllOrderQuoteEventBroadcast(DeleteAllOrderQuoteEventBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllQuoteBroadcast} message received.
     * @param message message
     */
    public void onDeleteAllQuoteBroadcast(DeleteAllQuoteBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.DeleteAllQuoteResponse} message received.
     * @param message message
     */
    public void onDeleteAllQuoteResponse(DeleteAllQuoteResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.InquireMMParameterRequest} message received.
     * @param message message
     */
    public void onInquireMMParameterRequest(InquireMMParameterRequest message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.InquireMMParameterResponse} message received.
     * @param message message
     */
    public void onInquireMMParameterResponse(InquireMMParameterResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.MMParameterDefinitionResponse} message received.
     * @param message message
     */
    public void onMMParameterDefinitionResponse(MMParameterDefinitionResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.MassQuoteResponse} message received.
     * @param message message
     */
    public void onMassQuoteResponse(MassQuoteResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.QuoteActivationNotification} message received.
     * @param message message
     */
    public void onQuoteActivationNotification(QuoteActivationNotification message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.QuoteActivationResponse} message received.
     * @param message message
     */
    public void onQuoteActivationResponse(QuoteActivationResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.QuoteExecutionReport} message received.
     * @param message message
     */
    public void onQuoteExecutionReport(QuoteExecutionReport message) {
    }
}

Quote and Cross Request Message Events

To be notified about quote and cross request message events, implement the

handler.setQuoteAndCrossRequestListener(new MyQuoteAndCrossRequestListener());

The sample interface implementation demonstrates available message events to receive.

public class MyQuoteAndCrossRequestListener implements QuoteAndCrossRequestListener {
    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.CrossRequestResponse} message received.
     * @param message message
     */
    public void onCrossRequestResponse(CrossRequestResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.RFQResponse} message received.
     * @param message message
     */
    public void onRFQResponse(RFQResponse message) {
    }
}

Strategy Creation Message Events

To be notified about strategy creation message events, implement the

handler.setStrategyCreationListener(new MyStrategyCreationListener());

The sample interface implementation demonstrates available message events to receive.

public class MyStrategyCreationListener implements StrategyCreationListener {
    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.AddComplexInstrumentResponse} message received.
     * @param message message
     */
    public void onAddComplexInstrumentResponse(AddComplexInstrumentResponse message) {
    }
}

Other Message Events

To be notified about other message events, implement the

handler.setOtherListener(new MyOtherListener());

The sample interface implementation demonstrates available message events to receive.

public class MyOtherListener implements OtherListener {
    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.BroadcastErrorNotification} message received.
     * @param message message
     */
    public void onBroadcastErrorNotification(BroadcastErrorNotification message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.NewsBroadcast} message received.
     * @param message message
     */
    public void onNewsBroadcast(NewsBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.RiskNotificationBroadcast} message received.
     * @param message message
     */
    public void onRiskNotificationBroadcast(RiskNotificationBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.LegalNotificationBroadcast} message received.
     * @param message message
     */
    public void onLegalNotificationBroadcast(LegalNotificationBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.ServiceAvailabilityBroadcast} message received.
     * @param message message
     */
    public void onServiceAvailabilityBroadcast(ServiceAvailabilityBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.TMTradingSessionStatusBroadcast} message received.
     * @param message message
     */
    public void onTMTradingSessionStatusBroadcast(TMTradingSessionStatusBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.TradeBroadcast} message received.
     * @param message message
     */
    public void onTradeBroadcast(TradeBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.TradingSessionStatusBroadcast} message received.
     * @param message message
     */
    public void onTradingSessionStatusBroadcast(TradingSessionStatusBroadcast message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.PartyEntitlementsUpdateReport} message received.
     * @param message message
     */
    public void onPartyEntitlementsUpdateReport(PartyEntitlementsUpdateReport message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.InquireMarginBasedRiskLimitResponse} message received.
     * @param message message
     */
    public void onInquireMarginBasedRiskLimitResponse(InquireMarginBasedRiskLimitResponse message) {
    }

    /**
     * Notifies about {@link biz.onixs.eurex.eti.handler.message.UpdateRemainingRiskAllowanceBaseResponse} message received.
     * @param message message
     */
    public void onUpdateRemainingRiskAllowanceBaseResponse(UpdateRemainingRiskAllowanceBaseResponse message) {
    }
}