biz.onixs.eurex.eti.handler.core

Class Handler

java.lang.Object

biz.onixs.eurex.eti.handler.core.Handler

public class Handler
extends Object

The entry point of the Handler: it establishes an ETI session, exchanges messages with the exchange, and reports everything that happens on the session to the listeners the application registers.

One instance owns one session at a time. To run several ETI sessions concurrently, create one handler per session.

Lifecycle

init(HandlerSettings) applies the settings and checks the license, connect() establishes a session, disconnect() ends it, and shutdown() releases the handler's threads. A handler may be reused after a shutdown() by calling init() again; init() is refused while the previous use has not finished.

The handler reports its progress through HandlerState:

 NOT_INITED  -> DISCONNECTED
 DISCONNECTED -> NOT_INITED | CONNECTING
 CONNECTING   -> CONNECTED  | DISCONNECTED
 CONNECTED    -> DISCONNECTING | DISCONNECTED
 DISCONNECTING -> DISCONNECTED
 

An established session always passes through DISCONNECTING on its way out, however it ends. A connect attempt that never established one settles from CONNECTING straight to DISCONNECTED. Register a HandlerStateListener to observe every transition.

connect() and disconnect() are asynchronous: they accept the request and return, and the handler carries it out on its own thread. A connect() issued immediately after a disconnect() is carried out after that disconnect, not refused by it. Watch the state to learn when a request has taken effect.

Reconnection

When ReconnectionSettings allows it, the handler reconnects on its own after an unexpected connection loss, reusing the logon that established the lost session. Each attempt starts a fresh ETI session, so the outbound sequence number restarts at 1.

Threads and listeners

The public methods of this class may be called from any thread. Listener callbacks are invoked on the handler's own threads: inbound messages and administrative events on the receiving thread, outbound message events on the sending thread, and state changes, errors and warnings on whichever thread produced them - including the thread that called init() or shutdown(). The one exception is the logon exchange of a session being established: the LogonRequest and the LogonResponse are reported on the thread carrying out the connect, not on a messaging thread.

A listener that blocks holds up the handler operation that is calling it, so keep callbacks short and do the work elsewhere. A listener may call back into the handler, but it should check getState() first rather than assume a request will be accepted.

Sending

send(ApplicationMessage) queues a message for the session in place when it is called and returns as soon as it is queued. A message still queued when its session ends is discarded and reported to the ErrorListener; it is never carried over to the session a reconnect establishes.

See Also:

Programming Guide

Constructor Summary

Constructors

Constructor and Description
Handler()

Method Summary

Modifier and Type	Method and Description
void	connect(LogonRequest logonRequest) Establishes the connection.
void	connect(LogonRequestEncrypted logonRequestEncrypted, String gatewayPassword) Establishes the connection with encrypted password.
void	disconnect() Ends the current session.
CharSequence	encryptPassword(String password)
CharSequence	encryptPassword(String password, String rsaKeyPath)
static String	getDefaultCstmApplVerId() Returns the version of supported Eurex T7 Release.
License	getLicense() Returns the license info.
String	getName() Returns the name of the Handler.
HandlerState	getState() Returns handler state.
static String	getVendor() Returns the vendor name.
String	getVersion() Returns the version of the Handler.
void	init(HandlerSettings settings) Initializes the handler.
void	init(biz.onixs.util.settings.Settings settings) Initializes the handler.
void	init(String settingsResource) Initializes the handler.
boolean	send(ApplicationMessage message) Sends the message.
boolean	send(UserLoginRequestEncrypted userLoginRequest, String password) Sends the User Login with Encrypted Password.
void	setAdminListener(AdminListener listener) Sets the administrative events listener.
void	setErrorListener(ErrorListener listener) Sets the error listener.
void	setHandlerStateListener(HandlerStateListener listener) Sets the handler state listener.
void	setInboundMessageListener(InboundMessageListener listener) Sets the inbound message event listener.
void	setOrderHandlingListener(OrderHandlingListener listener) Sets the order handling listener.
void	setOtherListener(OtherListener listener) Sets the other message listener.
void	setOutboundMessageListener(OutboundMessageListener listener) Sets the outbound message event listener.
void	setQuoteAndCrossRequestListener(QuoteAndCrossRequestListener listener) Sets the quote and cross request listener.
void	setQuoteHandlingListener(QuoteHandlingListener listener) Sets the quote handling listener.
void	setReceivedBytesListener(ReceivedBytesListener listener) Sets the bytes received event listener.
void	setStrategyCreationListener(StrategyCreationListener listener) Sets the strategy creation listener.
void	setWarningListener(WarningListener listener) Sets the warning listener.
void	shutdown() Shuts the handler down: ends any session it still has and releases its threads.

Methods inherited from class java.lang.Object

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

Constructor Detail

Handler

public Handler()

Method Detail

init

public void init(String settingsResource)
          throws HandlerException

Initializes the handler.

Parameters:

settingsResource - settings resource to load from

Throws:

HandlerException - if an error occurs during initialization, or if this handler is still in use - call shutdown() and let it return first. A handler that was never initialized, or whose shutdown() has completed, is accepted.

init

public void init(biz.onixs.util.settings.Settings settings)
          throws HandlerException

Initializes the handler.

Parameters:

settings - settings to apply

Throws:

HandlerException - if an error occurs during initialization, or if this handler is still in use - call shutdown() and let it return first. A handler that was never initialized, or whose shutdown() has completed, is accepted.

init

public void init(HandlerSettings settings)
          throws HandlerException

Initializes the handler.

Parameters:

settings - settings to apply

Throws:

HandlerException - if an error occurs during initialization, or if this handler is still in use - call shutdown() and let it return first. A handler that was never initialized, or whose shutdown() has completed, is accepted.

encryptPassword

public CharSequence encryptPassword(String password)
                             throws Exception

Throws:

Exception

encryptPassword

public CharSequence encryptPassword(String password,
                                    String rsaKeyPath)
                             throws Exception

Throws:

Exception

connect

public void connect(LogonRequest logonRequest)
             throws HandlerException

Establishes the connection.

Parameters:

logonRequest - initial logon message

Throws:

HandlerException - if the handler is already connected - call disconnect() first; if it has been shut down - call init() to reopen it - or if the connect could not be queued. A connect() issued immediately after a disconnect() is not refused: that teardown is asynchronous, so the connect is accepted and queued behind it.

connect

public void connect(LogonRequestEncrypted logonRequestEncrypted,
                    String gatewayPassword)
             throws HandlerException

Establishes the connection with encrypted password.

Parameters:

logonRequestEncrypted - initial logon message

gatewayPassword - gateway password

Throws:

HandlerException - if the handler is already connected - call disconnect() first; if it has been shut down - call init() to reopen it - or if the connect could not be queued. A connect() issued immediately after a disconnect() is not refused: that teardown is asynchronous, so the connect is accepted and queued behind it.

disconnect

public void disconnect()

Ends the current session.

Asynchronous: the request is accepted here and carried out on the handler's own thread against the session that was in place when this was called. The handler is not disconnected when this returns - watch for HandlerState.DISCONNECTED to learn when it is.

The handler logs out gracefully where it can. When a graceful logout is not possible - the outbound queue is full, or the connection has already gone - it closes the connection instead. Either way the session passes through HandlerState.DISCONNECTING; what differs is whether a logout is sent to the exchange, and how long the teardown takes.

Messages still queued for the session when it ends are discarded and reported to the error listener.

A connect() issued immediately after this call is carried out rather than lost, and the session it establishes is not torn down by this disconnect: the two requests take effect in the order they were issued, leaving the handler connected on the new session.

Calling this on a handler that is already HandlerState.DISCONNECTED is harmless and publishes no transition, so do not wait for one. Calling it while a connect is still in flight does end that attempt, and DISCONNECTED is published when it does.

shutdown

public void shutdown()
              throws HandlerException

Shuts the handler down: ends any session it still has and releases its threads.

Terminal against a concurrent connect(). A connect racing this call is either refused with a HandlerException or abandoned before it can establish a session; no connect can leave the handler connected once this has been called. What this cannot do is un-send a logon the exchange has already received - such an attempt is never published as a live session, and the connection it opened is closed.

This waits up to 5 s for the session teardown to finish. Normally the handler ends up HandlerState.NOT_INITED; if it does not - because the teardown did not complete in time, or the calling thread was interrupted - the failure is reported to the error listener rather than thrown, so that calling this from a finally block or a JVM shutdown hook cannot mask the exception being propagated. The handler stays shut down either way.

A listener callback that has not returned can outlive this call. Until it does, the threads it occupies are still running and a following init() is refused.

To use the handler again afterwards, call init().

Throws:

HandlerException - declared for callers that catch it, but not thrown: a shutdown that does not complete is reported to the error listener, as described above

send

public boolean send(ApplicationMessage message)

Sends the message.

Queuing is asynchronous and bound to the session in place when this was called. When that session ends, anything still queued for it is discarded rather than carried over to the session a reconnect establishes, and the discarded messages are reported to the error listener.

One documented exception to that binding: a call descheduled between the connection check and the enqueue, and left off-CPU across an entire teardown and reconnect, can have its message picked up by the new session instead of discarded. It is not reachable at normal scheduling latencies, and it is the only case in which a message crosses a session boundary.

Parameters:

message - message to send

Returns:

true if the message was accepted onto the outbound queue of the session in place when this was called - which is not a guarantee that it will be sent, since the session may end before the message is transmitted; false if the queue is full

Throws:

RuntimeException - if the connection is closed. This, not a false return, is what a caller sees while a session is down and a reconnect is in flight - including from inside the error listener that reports a drained session's discards, which are dispatched with the connection already closed. Resubmitting from that callback is therefore not possible; record the loss and resubmit once the handler reports CONNECTED again

NullPointerException - if message is null

send

public boolean send(UserLoginRequestEncrypted userLoginRequest,
                    String password)
             throws Exception

Sends the User Login with Encrypted Password.

Queued with the same session-bound semantics as send(ApplicationMessage).

Parameters:

userLoginRequest - User Login Request with Encrypted Password

password - the user password, encrypted with the configured RSA key before it is sent

Returns:

true if the message was accepted onto the outbound queue of the session in place when this was called - which is not a guarantee that it will be sent, since the session may end before the message is transmitted; false if the queue is full

Throws:

RuntimeException - if the connection is closed. This, not a false return, is what a caller sees while a session is down and a reconnect is in flight - including from inside the error listener that reports a drained session's discards, which are dispatched with the connection already closed. Resubmitting from that callback is therefore not possible; record the loss and resubmit once the handler reports CONNECTED again

NullPointerException - if userLoginRequest is null

Exception - if the password could not be encrypted - the configured RSA key is missing, unreadable or not a valid public key

setErrorListener

public void setErrorListener(ErrorListener listener)

Sets the error listener.

Parameters:

listener - error listener

setWarningListener

public void setWarningListener(WarningListener listener)

Sets the warning listener.

Parameters:

listener - warning listener

setHandlerStateListener

public void setHandlerStateListener(HandlerStateListener listener)

Sets the handler state listener.

Parameters:

listener - handler state listener

setAdminListener

public void setAdminListener(AdminListener listener)

Sets the administrative events listener.

Parameters:

listener - administrative events listener

setInboundMessageListener

public void setInboundMessageListener(InboundMessageListener listener)

Sets the inbound message event listener.

Parameters:

listener - inbound message event listener

setOutboundMessageListener

public void setOutboundMessageListener(OutboundMessageListener listener)

Sets the outbound message event listener.

Parameters:

listener - outbound message event listener

setReceivedBytesListener

public void setReceivedBytesListener(ReceivedBytesListener listener)

Sets the bytes received event listener.

Parameters:

listener - bytes received event listener

setStrategyCreationListener

public void setStrategyCreationListener(StrategyCreationListener listener)

Sets the strategy creation listener.

Parameters:

listener - strategy creation listener

setOrderHandlingListener

public void setOrderHandlingListener(OrderHandlingListener listener)

Sets the order handling listener.

Parameters:

listener - order handling listener

setQuoteAndCrossRequestListener

public void setQuoteAndCrossRequestListener(QuoteAndCrossRequestListener listener)

Sets the quote and cross request listener.

Parameters:

listener - quote and cross request listener

setQuoteHandlingListener

public void setQuoteHandlingListener(QuoteHandlingListener listener)

Sets the quote handling listener.

Parameters:

listener - quote handling listener

setOtherListener

public void setOtherListener(OtherListener listener)

Sets the other message listener.

Parameters:

listener - other message listener

getState

public HandlerState getState()

Returns handler state.

Returns:

handler state

getDefaultCstmApplVerId

public static String getDefaultCstmApplVerId()

Returns the version of supported Eurex T7 Release.

Returns:

Version string in the format `major.minor`.

getName

public String getName()

Returns the name of the Handler.

Returns:

Name of the Handler.

getVersion

public String getVersion()

Returns the version of the Handler.

Returns:

Version string in the format `major.minor.patch`.

getVendor

public static String getVendor()

Returns the vendor name.

Returns:

Vendor name as a string.

getLicense

public License getLicense()
                   throws HandlerException

Returns the license info.

Returns:

License instance.

Throws:

HandlerException - if the handler is not initialized.