com.caplin.trading

Interface Trade

public interface Trade

A single Trade active in the system.

A Trade is initiated by a client and is tied to a TradeChannel. The lifecycle of a Trade consists of a number of messages, represented by TradeEvents, being sent between the client and the Trading System in both directions. These messages cause the Trade to transition between a number of predefined states.

Trades are comprised of one or more trade legs, which each leg representing the exchange of a financial instrument and the resultant cashflow. It is possible to add, remove and update trades from the client or from the TradingDataSource.

A Trade is uniquely identified in two ways: by RequestId set by the client and a TradeId set by the Trading System.

Method Summary

Modifier and Type	Method and Description
TradeErrorEvent	createErrorEvent(java.lang.String errorType, java.lang.String errorDescription) Creates an error event for this Trade.
TradeEvent	createEvent(java.lang.String type) Creates an event for this Trade.
Leg	createLeg() Creates a new trade leg on this trade.
TradeEvent	createRestoreEvent(java.lang.String restoreToState) Creates an event that will restore a trade into the specified state.
TradeChannel	getChannel() Gets the Trade Channel for this Trade.
java.lang.String	getField(java.lang.String fieldName) Gets a stored field value from this Trade.
java.util.Map<java.lang.String,java.lang.String>	getFields() Gets the fields of this Trade as a Map.
java.util.List<Leg>	getLegs() Gets a copy of the list of legs that comprise this trade, in the correct order.
java.lang.String	getRequestId() Gets the unique RequestId for this Trade.
java.lang.String	getState() Gets the current state of this Trade.
TradeListener	getTradeListener() Gets the TradeListener that is set on this Trade.
java.lang.String	getType() Gets the type of this Trade.
void	sendErrorEvent(TradeErrorEvent errorEvent) Sends a TradeErrorEvent created by this Trade.
void	sendEvent(TradeEvent event) Sends an TradeEvent created by this Trade.
void	setTradeListener(TradeListener listener) Sets the TradeListener for this trade.

Method Detail

getState

java.lang.String getState()

Gets the current state of this Trade.

Returns:

The name of the current state.

getType

java.lang.String getType()

Gets the type of this Trade. The Type of a Trade represents the Trade Protocol/Model for this Trade.

Returns:

The type of this Trade.

getChannel

TradeChannel getChannel()

Gets the Trade Channel for this Trade.

Returns:

The TradeChannel.

createEvent

TradeEvent createEvent(java.lang.String type)
                throws TradeException

Creates an event for this Trade. The created TradeEvent is tied to this Trade and is set up with the correct RequestId and TradeId.

Parameters:

type - The type of the event.

Returns:

The new event.

Throws:

TradeException - Thrown if the type is invalid or the event cannot be created.

sendEvent

void sendEvent(TradeEvent event)
        throws TradeException

Sends an TradeEvent created by this Trade. The TradeEvent is processed by the Trade Model for this Trade and if appropriate is sent to the client.

Parameters:

event - The event to send.

Throws:

TradeException - Thrown if the event cannot be sent.

getRequestId

java.lang.String getRequestId()

Gets the unique RequestId for this Trade. The RequestId represents a unique identifier set by the client for this Trade, or set by the TradingDataSource if the trade is a restored trade.

Returns:

The RequestId.

Throws:

java.lang.IllegalStateException - Thrown if the RequestId is not set.

setTradeListener

void setTradeListener(TradeListener listener)

Sets the TradeListener for this trade. The TradeListener will be notified when TradeEvents are received for this Trade.

Parameters:

listener - The TradeListener.

getTradeListener

TradeListener getTradeListener()

Gets the TradeListener that is set on this Trade.

Returns:

The TradeListener, or null if no TradeListener is set.

getField

java.lang.String getField(java.lang.String fieldName)

Gets a stored field value from this Trade. This will typically be the context fields that have been stored as a result of the aggregated affect of all the processed TradeEvents.

Parameters:

fieldName - the String field name identifier to retrieve

Returns:

The field value for the provided field name, or null if there is no value stored.

getFields

java.util.Map<java.lang.String,java.lang.String> getFields()

Gets the fields of this Trade as a Map.

Returns:

A map of the fields.

createErrorEvent

TradeErrorEvent createErrorEvent(java.lang.String errorType,
                                 java.lang.String errorDescription)
                          throws TradeException

Creates an error event for this Trade. The created TradeErrorEvent is tied to this Trade and is set up with the correct RequestId and TradeId.

Parameters:

errorType - they type of Error, which correlates to an error transition in the underlying state-model.

errorDescription - an informative message that summarises the error.

Returns:

The new event.

Throws:

TradeException - Thrown if the type is invalid or the event cannot be created.

sendErrorEvent

void sendErrorEvent(TradeErrorEvent errorEvent)
             throws TradeException

Sends a TradeErrorEvent created by this Trade. The TradeErrorEvent is processed by the Trade Model for this Trade and is always sent to the client.

Parameters:

errorEvent - The error event to send.

Throws:

TradeException - Thrown if the event cannot be sent.

createRestoreEvent

TradeEvent createRestoreEvent(java.lang.String restoreToState)
                       throws TradeException

Creates an event that will restore a trade into the specified state. The trade must be created with TradeChannel.restoreTrade(String, String, String).

Parameters:

restoreToState - The name of the state to restore into. This must correspond to a state within the state model.

Returns:

The trade event to restore a trade into the specified state.

Throws:

TradeException - Thrown if this trade was not constructed with TradeChannel.restoreTrade(String, String, String) or if an attempt to restore a trade that is not currenly in the initial state.

createLeg

Leg createLeg()

Creates a new trade leg on this trade. Note that in order to notify trading clients that the leg has been added it is necessary to follow these steps:

• Add a Leg by calling createLeg().
• Create a LegAction representing the addition by calling Leg.createAddLegAction().
• Add any fields that are required on the new leg using the LegAction.addField(String, int) or LegAction.addField(String, String) methods.
• Create a TradeEvent by calling createEvent(String).
• Add the leg action to the event by calling TradeEvent.addLegAction(LegAction).
• Send the event using the sendEvent(TradeEvent) method.

Returns:

The new trade leg.

getLegs

java.util.List<Leg> getLegs()

Gets a copy of the list of legs that comprise this trade, in the correct order.

Returns:

The list of legs.