org.marketcetera.saclient
Interface SAClient

public interface SAClient

The interface to the set of remote services available from a remote strategy agent.

When one is done communicating with the remote strategy agent, close() should be invoked to close the connection to the remote strategy agent.

Since:

2.0.0

Version:

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

Author:

anshul@marketcetera.com

Method Summary

void	addConnectionStatusListener(ConnectionStatusListener inListener) Adds a connection status listener so that it can receive connection status notifications.
void	addDataReceiver(DataReceiver inReceiver) Adds a data receiver so that it can receive all the data received from the remote source that this client is connected to.
void	close() Closes the connection to the remote strategy agent.
ModuleURN	createStrategy(CreateStrategyParameters inParameters) Creates a new strategy module using the given strategy creation parameters.
void	delete(ModuleURN inURN) Deletes the module instance having the supplied URN.
List<ModuleURN>	getInstances(ModuleURN inProviderURN) Returns the list of module instances available.
ModuleInfo	getModuleInfo(ModuleURN inURN) Returns the module information for the module instance with the supplied URN.
SAClientParameters	getParameters() The parameters that were specified when connecting to the remote strategy agent.
Map<String,Object>	getProperties(ModuleURN inURN) Fetches all the available properties of the module with the supplied URN.
List<ModuleURN>	getProviders() Returns the list of providers available.
CreateStrategyParameters	getStrategyCreateParms(ModuleURN inURN) Fetches the strategy creation parameters (including the strategy script) for the strategy with the supplied URN.
void	removeConnectionStatusListener(ConnectionStatusListener inListener) Removes a connection status listener that was added previously so that it no longer receives connection status notifications.
void	removeDataReciever(DataReceiver inReceiver) Removes a data receiver that was previously added so that it no longer receives data from the remote source.
void	sendData(Object inData) Sends the given object to the Strategy Agent where registered listeners will receive it.
Map<String,Object>	setProperties(ModuleURN inURN, Map<String,Object> inProperties) Sets the supplied properties of the module.
void	start(ModuleURN inURN) Starts the module instance having the supplied URN.
void	stop(ModuleURN inURN) Stops the module instance having the supplied URN.

Method Detail

getProviders

List<ModuleURN> getProviders()
                             throws ConnectionException

Returns the list of providers available.

If no providers are available this list is empty.

Returns:

the list of providers available.

Throws:

ConnectionException - if there were errors completing the operation.

getInstances

List<ModuleURN> getInstances(ModuleURN inProviderURN)
                             throws ConnectionException

Returns the list of module instances available.

Parameters:

inProviderURN - the URN of the provider whose instances should be returned. If null, all available instances are returned.

If no instances are found, an empty list is returned.

Returns:

the list of module instances available.

Throws:

ConnectionException - if there were errors completing the operation.

getModuleInfo

ModuleInfo getModuleInfo(ModuleURN inURN)
                         throws ConnectionException

Returns the module information for the module instance with the supplied URN.

Parameters:

inURN - the module instance URN. Cannot be null.

Returns:

the module info.

Throws:

ConnectionException - if there were errors completing the operation.

start

void start(ModuleURN inURN)
           throws ConnectionException

Starts the module instance having the supplied URN.

Only strategy module instances can be started. Attempts to start modules that are not strategy modules will fail.

Parameters:

inURN - the URN of the module that needs to be started. Cannot be null.

Throws:

ConnectionException - if there were errors completing the operation.

stop

void stop(ModuleURN inURN)
          throws ConnectionException

Stops the module instance having the supplied URN.

Only strategy module instances can be stopped. Attempts to stop modules that are not strategy modules will fail.

Parameters:

inURN - the URN of the module that needs to be stopped. Cannot be null.

Throws:

ConnectionException - if there were errors completing the operation.

delete

void delete(ModuleURN inURN)
            throws ConnectionException

Deletes the module instance having the supplied URN.

Only strategy module instances can be deleted. Attempts to delete modules that are not strategy modules will fail.

Parameters:

inURN - the URN of the module that needs to be deleted. Cannot be null.

Throws:

ConnectionException - if there were errors completing the operation.

getProperties

Map<String,Object> getProperties(ModuleURN inURN)
                                 throws ConnectionException

Fetches all the available properties of the module with the supplied URN.

Note that the property values may not be in the same type as is declared on the module's MXBean. The return types are open data types. Refer to the type mapping rules in MXBean documentation to figure out the return type for a particular property type. For example, enum property types are returned as string values.

Parameters:

inURN - the module URN. Cannot be null.

Returns:

All the available properties of that module.

Throws:

ConnectionException - if there were errors completing the operation.

setProperties

Map<String,Object> setProperties(ModuleURN inURN,
                                 Map<String,Object> inProperties)
                                 throws ConnectionException

Sets the supplied properties of the module.

Only the following properties of strategy module can be set. Attempts to set the properties of a module that is not a strategy module or a strategy module property that is not in this list will fail.

• Parameters
• RoutingOrdersToORS

Note: Be sure to verify the values in the returned map to be sure that each property was set successfully. If there's a failure setting a property, the method doesn't fail. Instead, the value of the property that could not be set is a RemoteProperties instance that has details on the error encountered when setting the property.

Parameters:

inURN - the URN of the module whose properties are being set. Cannot be null.

inProperties - the new property values for the module. Cannot be null.

Returns:

the map of properties that were succesfully updated. In case a particular property could not be updated, the value of that property will contain a RemoteProperties instance that has details on the failure.

Throws:

ConnectionException - if there were errors completing the operation.

createStrategy

ModuleURN createStrategy(CreateStrategyParameters inParameters)
                         throws ConnectionException

Creates a new strategy module using the given strategy creation parameters.

Parameters:

inParameters - the strategy creation parameters. Cannot be null.

Returns:

the created module's URN.

Throws:

ConnectionException - if there were errors completing the operation.

getStrategyCreateParms

CreateStrategyParameters getStrategyCreateParms(ModuleURN inURN)
                                                throws ConnectionException

Fetches the strategy creation parameters (including the strategy script) for the strategy with the supplied URN.

This method is made available to enable a client to export strategy script contents. It's recommended that getProperties(ModuleURN) be used for fetching the current values of strategy properties as getStrategyCreateParms(org.marketcetera.module.ModuleURN) may yield stale values for certain strategy attributes like parameters.

Parameters:

inURN - the strategy module instnace URN. Cannot be null.

Returns:

the strategy creation parameters.

Throws:

ConnectionException - if there were errors completing the operation.

sendData

void sendData(Object inData)
              throws ConnectionException

Sends the given object to the Strategy Agent where registered listeners will receive it.

Parameters:

inData - an Object value

Throws:

ConnectionException - if there were errors completing the operation.

addDataReceiver

void addDataReceiver(DataReceiver inReceiver)

Adds a data receiver so that it can receive all the data received from the remote source that this client is connected to.

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

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

Parameters:

inReceiver - the receiver to add. Cannot be null.

removeDataReciever

void removeDataReciever(DataReceiver inReceiver)

Removes a data receiver that was previously added so that it no longer receives data from the remote source.

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

Parameters:

inReceiver - the receiver to remove. Cannot be null.

addConnectionStatusListener

void addConnectionStatusListener(ConnectionStatusListener inListener)

Adds a connection status listener so that it can receive connection status notifications.

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 to add. Cannot be null.

removeConnectionStatusListener

void removeConnectionStatusListener(ConnectionStatusListener inListener)

Removes a connection status listener that was added previously so that it no longer receives connection status notifications.

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

Parameters:

inListener - the listener to remove. Cannot be null.

getParameters

SAClientParameters getParameters()

The parameters that were specified when connecting to the remote strategy agent.

Returns:

the connection parameters.

close

void close()

Closes the connection to the remote strategy agent. The behavior of the client after this method is invoked is undefined. If one needs to reconnect to the server, a new instance of the client should be created.

This operation does not throw any exceptions. If any failures are encountered when closing the connection, they are logged.