org.marketcetera.client
Interface Client

public interface Client

A client end point that communicates with the server.

The client provides the following lifecycle methods.

• reconnect(): to reconnect to the server
• reconnect(ClientParameters): to reconnect to a server that is different from the one the client was originally connected to.

The client provides the following set of services that communicate with the server.

• sendOrder: sendOrder(OrderSingle), sendOrder(OrderReplace), sendOrder(OrderCancel), sendOrderRaw(FIXOrder)
• receive reports
• receive broker status updates
• fetch past reports
• getEquityPositionAsOf(Date, Equity) fetch equity position}
• getAllEquityPositionsAsOf(Date) fetch all open equity positions}
• getOptionPositionAsOf(java.util.Date, Option) fetch option position}
• getOptionPositionsAsOf(java.util.Date, String[]) fetch option positions}
• getAllOptionPositionsAsOf(java.util.Date) fetch all open option positions}

Since:

1.0.0

Version:

$Id: Client.java 16154 2012-07-14 16:34:05Z colin $

Author:

anshul@marketcetera.com

Method Summary

void	addBrokerStatusListener(BrokerStatusListener listener) Adds a broker status listener, which receives all the broker status changes sent out by the server.
void	addExceptionListener(ExceptionListener inListener) Adds an exception listener.
void	addReportListener(ReportListener inListener) Adds a report listener.
void	addServerStatusListener(ServerStatusListener listener) Adds a server connection status listener, which receives all the server connection status changes.
void	close() Closes the connection to the server.
Map<PositionKey<Equity>,BigDecimal>	getAllEquityPositionsAsOf(Date inDate) Returns all open equity positions based on reports, generated and received on or before the supplied date in UTC.
Map<PositionKey<Future>,BigDecimal>	getAllFuturePositionsAsOf(Date inDate) Returns all open future positions based on reports, generated and received on or before the supplied date in UTC.
Map<PositionKey<Option>,BigDecimal>	getAllOptionPositionsAsOf(Date inDate) Returns the aggregate position of each option (option,account,actor) tuple based on all reports received for each option instrument on or before the supplied date in UTC and which are visible to the given user.
BrokersStatus	getBrokersStatus() Returns the server's broker status.
BigDecimal	getEquityPositionAsOf(Date inDate, Equity inEquity) Returns the position of the supplied equity based on reports, generated and received on or before the supplied date in UTC.
BigDecimal	getFuturePositionAsOf(Date inDate, Future inFuture) Returns the position of the supplied future based on reports, generated and received on or before the supplied date in UTC.
Date	getLastConnectTime() Returns the last time the client was successfully connected or reconnected to the server.
BigDecimal	getOptionPositionAsOf(Date inDate, Option inOption) Gets the current aggregate position for the option instrument based on execution reports received on or before the supplied date in UTC, and which are visible to the given user.
Map<PositionKey<Option>,BigDecimal>	getOptionPositionsAsOf(Date inDate, String... inRootSymbols) Returns the aggregate position of each option (option,account,actor) tuple based on all reports received for each option instrument on or before the supplied date in UTC, and which are visible to the given user.
Collection<String>	getOptionRoots(String inUnderlying) Returns the collection of known option roots for the underlying symbol.
ClientParameters	getParameters() Returns the parameters that client is using to connect to the server.
ReportBase[]	getReportsSince(Date inDate) Returns all the reports (execution report and order cancel rejects) generated and received by the server since the supplied date in UTC.
String	getUnderlying(String inOptionRoot) Returns the underlying symbol for the supplied option root, if a mapping is found for it.
Properties	getUserData() Gets the user data associated with the current user.
UserInfo	getUserInfo(UserID id, boolean useCache) Returns the information of the user with the given ID.
boolean	isCredentialsMatch(String inUsername, char[] inPassword) Returns true if the supplied user name, password match the credentials used to connect to the server.
boolean	isServerAlive() Returns true if client has a live connection to the server.
void	reconnect() Disconnects the connection to the server and reconnects back using the same properties as were supplied when creating this instance.
void	reconnect(ClientParameters inParameters) Disconnects the connection to the server and reconnects back using the properties supplied to this method.
void	removeBrokerStatusListener(BrokerStatusListener listener) Removes a broker status listener that was previously added via addBrokerStatusListener(BrokerStatusListener).
void	removeExceptionListener(ExceptionListener inListener) Removes exception listener that was previously added via addExceptionListener(java.beans.ExceptionListener).
void	removeReportListener(ReportListener inListener) Removes a report listener that was previously added via addReportListener(ReportListener).
void	removeServerStatusListener(ServerStatusListener listener) Removes a server connection status listener that was previously added via addServerStatusListener(ServerStatusListener).
void	sendOrder(OrderCancel inOrderCancel) Sends the supplied order to the server.
void	sendOrder(OrderReplace inOrderReplace) Sends the supplied order to the server.
void	sendOrder(OrderSingle inOrderSingle) Sends the supplied order to the server.
void	sendOrderRaw(FIXOrder inFIXOrder) Sends the supplied FIX Message Order to the server.
void	setUserData(Properties inProperties) Sets the user data associated with the current user.

Method Detail

sendOrder

void sendOrder(OrderSingle inOrderSingle)
               throws ConnectionException,
                      OrderValidationException

Sends the supplied order to the server.

Parameters:

inOrderSingle - The order to send.

Throws:

ConnectionException - if there were connection errors sending the order out to the server.

OrderValidationException - if the order didn't have complete or consistent data to be sent to the server.

sendOrder

void sendOrder(OrderReplace inOrderReplace)
               throws ConnectionException,
                      OrderValidationException

Sends the supplied order to the server.

Parameters:

inOrderReplace - The order to send.

Throws:

ConnectionException - if there were connection errors sending the order out to the server.

OrderValidationException - if the orders didn't have complete or consistent data to be sent to the server.

sendOrder

void sendOrder(OrderCancel inOrderCancel)
               throws ConnectionException,
                      OrderValidationException

Sends the supplied order to the server.

Parameters:

inOrderCancel - The order to send.

Throws:

ConnectionException - if there were connection errors sending the order out to the server.

OrderValidationException - if the orders didn't have complete or consistent data to be sent to the server.

sendOrderRaw

void sendOrderRaw(FIXOrder inFIXOrder)
                  throws ConnectionException,
                         OrderValidationException

Sends the supplied FIX Message Order to the server.

When supplying raw FIX Message, a brokerID has to be supplied

Parameters:

inFIXOrder - the raw FIX Order to send.

Throws:

ConnectionException - if there were connection errors sending the order to the server.

OrderValidationException - if the supplied message was not of a type that's supported by the system.

getReportsSince

ReportBase[] getReportsSince(Date inDate)
                             throws ConnectionException

Returns all the reports (execution report and order cancel rejects) generated and received by the server since the supplied date in UTC.

Parameters:

inDate - The date in UTC. Cannot be null.

Returns:

All the reports since the supplied date, may be empty.

Throws:

ConnectionException - if there were connection errors fetching data from the server.

getEquityPositionAsOf

BigDecimal getEquityPositionAsOf(Date inDate,
                                 Equity inEquity)
                                 throws ConnectionException

Returns the position of the supplied equity based on reports, generated and received on or before the supplied date in UTC.

Parameters:

inDate - the date in UTC. Cannot be null.

inEquity - The equity. Cannot be null.

Returns:

the current position of the equity.

Throws:

ConnectionException - if there were connection errors fetching data from the server.

getAllEquityPositionsAsOf

Map<PositionKey<Equity>,BigDecimal> getAllEquityPositionsAsOf(Date inDate)
                                                              throws ConnectionException

Returns all open equity positions based on reports, generated and received on or before the supplied date in UTC.

Parameters:

inDate - the date in UTC. Cannot be null.

Returns:

the open equity positions. Includes non-zero positions only.

Throws:

ConnectionException - if there were connection errors fetching data from the server.

getFuturePositionAsOf

BigDecimal getFuturePositionAsOf(Date inDate,
                                 Future inFuture)
                                 throws ConnectionException

Returns the position of the supplied future based on reports, generated and received on or before the supplied date in UTC.

Parameters:

inDate - the date in UTC. Cannot be null.

inFuture - The future. Cannot be null.

Returns:

the current position of the future.

Throws:

ConnectionException - if there were connection errors fetching data from the server.

getAllFuturePositionsAsOf

Map<PositionKey<Future>,BigDecimal> getAllFuturePositionsAsOf(Date inDate)
                                                              throws ConnectionException

Returns all open future positions based on reports, generated and received on or before the supplied date in UTC.

Parameters:

inDate - the date in UTC. Cannot be null.

Returns:

the open future positions. Includes non-zero positions only.

Throws:

ConnectionException - if there were connection errors fetching data from the server.

getOptionPositionAsOf

BigDecimal getOptionPositionAsOf(Date inDate,
                                 Option inOption)
                                 throws ConnectionException

Gets the current aggregate position for the option instrument based on execution reports received on or before the supplied date in UTC, and which are visible to the given user.

Buy trades result in positive positions. All other kinds of trades result in negative positions.

Parameters:

inDate - the date in UTC. Cannot be null.

inOption - the option instrument

Returns:

the aggregate position for the option.

Throws:

ConnectionException - if there were errors retrieving the position.

getAllOptionPositionsAsOf

Map<PositionKey<Option>,BigDecimal> getAllOptionPositionsAsOf(Date inDate)
                                                              throws ConnectionException

Returns the aggregate position of each option (option,account,actor) tuple based on all reports received for each option instrument on or before the supplied date in UTC and which are visible to the given user.

Buy trades result in positive positions. All other kinds of trades result in negative positions.

Parameters:

inDate - the date in UTC. Cannot be null.

Returns:

the position map.

Throws:

ConnectionException - if there were errors retrieving the position map.

getOptionPositionsAsOf

Map<PositionKey<Option>,BigDecimal> getOptionPositionsAsOf(Date inDate,
                                                           String... inRootSymbols)
                                                           throws ConnectionException

Returns the aggregate position of each option (option,account,actor) tuple based on all reports received for each option instrument on or before the supplied date in UTC, and which are visible to the given user.

Buy trades result in positive positions. All other kinds of trades result in negative positions.

Parameters:

inDate - the date in UTC. Cannot be null.

inRootSymbols - the list of option root symbols.

Returns:

the position map.

Throws:

ConnectionException - if there were errors retrieving the position map.

getUnderlying

String getUnderlying(String inOptionRoot)
                     throws ConnectionException

Returns the underlying symbol for the supplied option root, if a mapping is found for it. Null otherwise.

The mapping is retrieved from the server the first time an option root symbol is specified. The value returned by the server is cached on the client for all subsequent invocations for the same root symbol. All the cached values are cleared when the client is closed.

Parameters:

inOptionRoot - The option root symbol.

Returns:

The underlying symbol for the supplied option root. null, if no mapping was found.

Throws:

ConnectionException - if there were errors retrieving the underlying symbol.

getOptionRoots

Collection<String> getOptionRoots(String inUnderlying)
                                  throws ConnectionException

Returns the collection of known option roots for the underlying symbol.

The mapping is retrieved from the server the first time an underlying symbol is specified. The value returned by the server is cached on the client for all subsequent invocations for the same underlying symbol. All the cached values are cleared when the client is closed.

Parameters:

inUnderlying - The underlying symbol.

Returns:

The sorted collection of option roots if mappings are found for the option root, null otherwise.

Throws:

ConnectionException - if there were errors retrieving the option roots.

addReportListener

void addReportListener(ReportListener inListener)

Adds a report listener. The report listener receives all the reports sent out by the server.

If the same listener is added more than once, it will receive notifications as many times as it's been added.

The listeners are notified in the reverse order of their addition.

Parameters:

inListener - The listener instance that should be supplied the reports.

removeReportListener

void removeReportListener(ReportListener inListener)

Removes a report listener that was previously added via addReportListener(ReportListener). If the listener was added more than once, only its most recently added occurrence will be removed.

Parameters:

inListener - The listener instance that should no longer be receiving the reports.

addBrokerStatusListener

void addBrokerStatusListener(BrokerStatusListener listener)

Adds a broker status listener, which receives all the broker status changes sent out by the server.

If the same listener is added more than once, it will receive notifications as many times as it has been added.

The listeners are notified in the reverse order of their addition.

Parameters:

listener - The listener which should be supplied the broker status changes.

removeBrokerStatusListener

void removeBrokerStatusListener(BrokerStatusListener listener)

Removes a broker status listener that was previously added via addBrokerStatusListener(BrokerStatusListener).

If the listener was added more than once, only its most recently added instance will be removed.

Parameters:

listener - The listener which should stop receiving broker status changes.

addServerStatusListener

void addServerStatusListener(ServerStatusListener listener)

Adds a server connection status listener, which receives all the server connection status changes.

If the same listener is added more than once, it will receive notifications as many times as it has been added.

The listeners are notified in the reverse order of their addition.

Parameters:

listener - The listener which should be supplied the server connection status changes.

removeServerStatusListener

void removeServerStatusListener(ServerStatusListener listener)

Removes a server connection status listener that was previously added via addServerStatusListener(ServerStatusListener).

If the listener was added more than once, only its most recently added instance will be removed.

Parameters:

listener - The listener which should stop receiving server connection status changes.

addExceptionListener

void addExceptionListener(ExceptionListener inListener)

Adds an exception listener. The exception listeners are notified whenever the client encounters connectivity issues when communicating with the server.

The listeners are notified only when connectivity issues are encountered when sending or receiving messages, ie. when any of the send*() methods are invoked, or when the client receives a message and encounters errors processing it before delivering it to ReportListener or BrokerStatusListener, or when client heartbeats cannot reach the server.

If the same listener is added more than once, it will receive notifications as many times as it's been added.

The listeners are notified in the reverse order of their addition.

Parameters:

inListener - the listener instance.

removeExceptionListener

void removeExceptionListener(ExceptionListener inListener)

Removes exception listener that was previously added via addExceptionListener(java.beans.ExceptionListener). The listener will stop receiving exception notifications after this method returns. If the listener was added more than once, only its most recently added occurrence will be removed.

Parameters:

inListener - The exception listener that should no longer

close

void close()

Closes the connection to the server. The behavior of any of the methods of this class after this method is invoked is undefined.

reconnect

void reconnect()
               throws ConnectionException

Disconnects the connection to the server and reconnects back using the same properties as were supplied when creating this instance.

Throws:

ConnectionException - if there were errors reconnecting.

reconnect

void reconnect(ClientParameters inParameters)
               throws ConnectionException

Disconnects the connection to the server and reconnects back using the properties supplied to this method.

Parameters:

inParameters - The parameters to use when reconnecting to the server. These parameters are stored so that subsequent invocations of reconnect() will use these parameters instead of the ones that were supplied when creating this instance.

Throws:

ConnectionException - if there were errors reconnecting.

getParameters

ClientParameters getParameters()

Returns the parameters that client is using to connect to the server.

Returns:

the parameters used by the client to connect to the server.

getLastConnectTime

Date getLastConnectTime()

Returns the last time the client was successfully connected or reconnected to the server.

Returns:

the last time the client was successfully connected or reconnected to the server.

getBrokersStatus

BrokersStatus getBrokersStatus()
                               throws ConnectionException

Returns the server's broker status.

Returns:

The status.

Throws:

ConnectionException - Thrown if the operation cannot be completed.

getUserInfo

UserInfo getUserInfo(UserID id,
                     boolean useCache)
                     throws ConnectionException

Returns the information of the user with the given ID. A local cache can be used to avoid frequent server roundtrips, but it may return stale information. The cache is updated whether or not it was used for retrieval.

All cached values are cleared when the client is closed.

Parameters:

id - The user ID.

useCache - True if the local cache should be used.

Returns:

The information.

Throws:

ConnectionException - Thrown if the operation cannot be completed.

isCredentialsMatch

boolean isCredentialsMatch(String inUsername,
                           char[] inPassword)

Returns true if the supplied user name, password match the credentials used to connect to the server.

This method returns false if the client is not connected to the server.

Parameters:

inUsername - the username

inPassword - the password

Returns:

true, if the supplied credentials match the ones used to authenticate to the server and the client is connected to the server, false otherwise.

isServerAlive

boolean isServerAlive()

Returns true if client has a live connection to the server.

Returns:

true, if the connection to the server is alive.

setUserData

void setUserData(Properties inProperties)
                 throws ConnectionException

Sets the user data associated with the current user.

Parameters:

inProperties - a Properties value

Throws:

ConnectionException - if an error occurs connecting to the server

getUserData

Properties getUserData()
                       throws ConnectionException

Gets the user data associated with the current user.

Returns:

a Properties value

Throws:

ConnectionException - if an error occurs connecting to the server