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, {@link org.marketcetera.client.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 {@link org.marketcetera.client.ClientManager#init(ClientParameters)}. Once the client is initialized, its instance can be accessed via {@link org.marketcetera.client.ClientManager#getInstance()}.

All the services available from the Server are available via {@link org.marketcetera.client.Client}. After communicating with the server, the connection to the server can be closed and all the associated resources be released by invoking {@link org.marketcetera.client.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 {@link org.marketcetera.client.ClientManager#init(org.marketcetera.client.ClientParameters)}.

The client can reconnect to the server by invoking {@link org.marketcetera.client.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 {@link org.marketcetera.client.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 {@link org.marketcetera.client.Client} in parallel, along with the module.

The module factory provides a singleton module that is auto-created and auto-started. See {@link org.marketcetera.client.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 {@link org.marketcetera.client.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.

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

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, {@link org.marketcetera.client.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.