Package org.marketcetera.client

Provides client API to communicate with the server.

See: Description

Interface Summary

Interface	Description
BrokerStatusListener	A receiver of broker status changes.
Client	A client end point that communicates with the server.
ClientFactory	Factory used to create a Client object.
ClientModuleFactoryMXBean	Management interface for the Client Module Provider.
ClientModuleMXBean	Management interface for the Client Module.
ClientVersion	The client version manager.
Messages	Internationalized messages used by this package.
OrderModifier	Modifies orders.
ReportListener	A receiver of trading reports.
Service	The application's web services.

Class Summary

Class	Description
ClientIDFactory	Client's ID factory that generates unique IDs based on IDs given out by the server.
ClientImpl	The implementation of Client that connects to the server.
ClientManager	Abstraction that manages the initialization of the Client and provides an easy way to get to its singleton instance.
ClientModuleFactory	The provider / factory that creates Client Module instance.
ClientParameters	The set of parameters needed to initialize the client.
Validations	Carries out validations for various order types.

Exception Summary

Exception	Description
ClientInitException	Instances of this class are thrown if the Client is already initialized or if it's not initialized.
ConnectionException	Represents errors encountered by the client when communicating with the server.
IncompatibleComponentsException	Represents errors encountered by the client when communicating with an incompatible server.
OrderValidationException	Indicates errors encountered when validating orders before sending them to the server.

Package org.marketcetera.client Description

Provides client API to communicate with the server. It also provides a module to enable other modules, participating in data flows, to be able to send trading orders to the server and receive trading reports from the server.

Currently the client can only connect to a single server instance. It's not possible for the client to connect to multiple server instances at the same time from within the same JVM.

Java API

The Java API provides means to connect to the server and communicate with it via a Facade, Client. The Facade hides the details of communications with the server from the clients.

Lifecycle

When using Java API to communicate with the server, the client is initialized via ClientManager.init(ClientParameters). Once the client is initialized, its instance can be accessed via ClientManager.getInstance().

All the services available from the Server are available via Client. After communicating with the server, the connection to the server can be closed and all the associated resources be released by invoking Client.close(). The client should not be used after it has been closed. The behavior of client after invoking close() is unspecified. After the client has been closed, the only permitted operation is to initialize it again via ClientManager.init(org.marketcetera.client.ClientParameters).

The client can reconnect to the server by invoking Client.reconnect(). One may choose to invoke this API because they believe that the current connection to the server is not working (ie. they are receiving ConnectionException when invoking services). The client can be used after a successful reconnect. If the reconnect fails, the only operations permitted are reconnect and close.

Features

The Java API offers the following features.

1. Send orders : Send various types of orders to the server.
2. Receive Reports : Receive various execution reports from the server.
3. Exception Notifications : Receive a notification whenever the client encounters errors when communicating with the server.
4. Fetch Old Reports : Fetch old execution reports from the server.
5. Fetch Positions : Fetch positions of various symbols from the server.

Module

A module is provided to enable server to participate in data flows. Do note that while operating as a module, only the features that send orders and receive reports are available. All other server features are only available via the Java API. It's possible to use the Java API via Client in parallel, along with the module.

The module factory provides a singleton module that is auto-created and auto-started. See ClientModuleFactory for more details.

Configuration

The module factory can be configured in two different ways.

1. Via Java API : In this scenario, the client is configured via the Java API. The module uses the already configured client instance to communicate with the server. See the Lifecycle section for details on Java API.
2. Via Module Configuration : In this scenario, the module provider is provided the server connection details via the module framework. The factory uses those details to initialize the client.

The module factory exposes the parameters for its configuration via ClientModuleFactoryMXBean. The following parameters need to be specified for the factory to be able to initialize the client.

1. URL: The URL of the server
2. Username: The user name to authenticate to the server.
3. Password: The user's password to authenticate to the server.
4. Hostname: The hostname for the server's web service.
5. Port: The port number for the server's web service.
6. IDPrefix: The ID Prefix for all orders sent out by this client.

To set these parameters by default within a strategy agent, create a file named ors_system.properties with the following contents.

Hostname=127.0.0.1
Port=9000
URL=tcp://127.0.0.1:61616
Username=admin
Password=admin
IDPrefix=

Do note that the factory will not attempt to initialize the client if it already has been initialized via the Java API.

Lifecycle

The module does not validate that the client has been initialized when it's started. The module does not close the client when it's stopped. Once created, the module's lifecycle is independent of the status of client's connection to the server. Do note that the client is configured to be closed when the JVM is stopped.

Data Types

The module accepts data of following types.

• OrderSingle
• OrderCancel
• OrderReplace
• FIXOrder

The module will emit all the reports from the server when requested. Following types of reports may be emitted by the module.

• ExecutionReport
• OrderCancelReject

Request Parameters

The module does not accept any request parameters. When requested to emit data, the module will emit all the trading reports that server sends.

Management Interface

The Module provides a management interface, ClientModuleMXBean, to operate on it during runtime.

Design Notes

The Client is meant to be a thin API to access the server. It's not intended to perform any functions that are not directly related to communicating with the server. The server depends on the client.