Class
caplin.trading.trademodel

Trade

A Trade represents the exchange of a number of financial instruments between counter-parties. Each exchange is represented by a caplin.trading.trademodel.TradeLeg instance, where the trade forms a transactional wrapper around one or more trade legs.

To execute a trade, a number of messages (dependent on the trading protocol) are passed between the trade and a trading-server (via Liberator). The messages are sent and received using a caplin.trading.trademodel.TradeMessageService. The receipt and sending of messages cause the trade to transition between discrete states. The state defines both the behaviour of the trade, and the possible states the trade can move into. The state handling is delegated to a state machine.

Constructor Summary

Attributes Name and Description
caplin.trading.trademodel.Trade(String tradingAssetClass, caplin.trading.trademodel.TradeLegFactory tradeLegFactory, caplin.trading.statemachine.StateMachine stateMachine, caplin.trading.trademodel.TradeMessageService tradeMessageService, String tradingProtocol, String tradingType, String assetClass)

Constructs an instance of caplin.trading.trademodel.Trade.

Method Summary

Attributes Name and Description
void addDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, String fieldName, boolean notifyImmediate)

Adds a listener that is called when the specified field is updated.

void addDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Adds a listener object that is called when any of the specified fields are updated.

void addDerivation(caplin.trading.derivation.Derivation derivation)

Appends a field derivation to the trade model.

void addInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener listener)

Adds a listener that will have its callback method invoked when the server returns data that is somehow invalid.

caplin.trading.trademodel.TradeLeg addLeg(String assetClass)

Creates a new trade leg with the specified asset class.

caplin.trading.trademodel.TradeLeg addLegs(String assetClass, Integer count)

Creates a specified number of new trade legs with of the given asset class.

void addStateChangedListener(caplin.trading.statemachine.StateChangedListener listener)

Adds a listener that will have its callback method invoked when the state of the trade is updated.

void addStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)

Adds a listener that will have its callback method invoked when legs are added or removed from the trade.

void addTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)

Adds a listener to listen to trade restored events.

void addTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener listener)

Adds a specified TradingStatusChangedListener to the trade.

void addValidator(String state, caplin.trading.validation.Validator validator)

Adds a validator object that is invoked whenever the trade data is being modified, so it can verify the changes before they are committed.

void afterLegAdded(caplin.trading.trademodel.TradeLeg leg, int legId)

Invoked immediately after a leg is added to the trade.

void beforeLegAdded(caplin.trading.trademodel.TradeLeg leg, int legId)

Invoked before a leg is added to the trade.

String getAccount()

Returns the financial account used for the transfer of funds when the trade is settled.

String getAssetClass()

Returns the type of the financial instrument(s) to be traded — e.g FX, FI, EQUITY or COMMODITIES.

caplin.trading.statemachine.State getCurrentState()

Returns the current state of this trade.

Object getDataAsStructuredMap(Boolean includeLegs)

Takes data from the trade and trade legs and returns it inside a single DataHolder.

Variant getFieldValue(String fieldName)

Returns the field value with the specified name.

int getInitialLegCount(String tradeType)

Returns the initial number of legs to be completed in a trade based on the trade type.

caplin.trading.trademodel.TradeLeg getLeg(int idx)

Returns the trade leg at the specified index (zero based).

caplin.trading.trademodel.TradeLeg getLegById(int legId)

Returns the trade leg specified by its ID.

Array getLegs()

Returns a copy of the list of trade legs.

int getMaxLegCount(String tradeType)

Returns the maximum number of legs allowed in a trade of the specified trade type.

String getOverallTimeOut()

Returns the time allowed before the trade will timeout and move to an expired state.

void getRemainingTimeToTrade()

Returns the time that is left until the trade stops being executable

String getRequestID()

Returns the unique identifier assigned by the trade subscriber to track this trade instance.

String getRestorationID()

Returns the ID sent from the server that is used to restore trades.

String getServerFailureMessage()

Returns an error message containing the reason for a failure if the trade is in an error state — caused by a failure in the server or the network.

String getState()

Returns the current state of the trade.

void getStateMachine()

Returns the state machine associated with this trade.

void getTradeChannelStatus()

Returns only the status of the trade channel and not the pricing channel.

String getTradeDate()

The date the trade is/was executed in YYYYMMDD format.

String getTradeID()

Returns the unique identifier assigned by the trading system to track this trade instance.

String getTradingProtocol()

Returns the trading protocol that the trade is being executed with.

int getTradingStatus()

Returns a number indicating whether trading and/or pricing is currently available for this Trade or not.

String getTradingType()

Returns the trading type that this trade is currently executing — e.g.

String getUserTradedOnBehalfOf()

Returns the user this trade will be executed on behalf of.

boolean isEventAllowed(String eventName)

Returns true if the specified event name is currently executable, and false otherwise (including if the event is unknown).

caplin.trading.validation.ValidationResult processClientEvent(String eventName, Map tradeFieldsMap)

This method is called by the client code to request a state transition.

void processServerEvent(String eventName, Map serverReturnedData)

This method is called by the trade subscriber when messages are received from the server.

void removeAllLegs()

Removes all legs from the trade object.

void removeDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Removes the previously registered DataFieldChangedListener.

void removeDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Removes a listener object from each of the passed fields.

void removeInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener listener)

Removes the previously registered InvalidServerEventListener.

void removeLeg(caplin.trading.trademodel.TradeLeg leg)

Removes a leg from the trade object.

void removeStateChangedListener(caplin.trading.statemachine.StateChangedListener listener)

Removes the previously registered StateChangedListener.

void removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)

Removes the previously registered StructureChangedListener.

void removeTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)

Removes the specified listener from listening to trade restored events.

boolean removeTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener listener)

Removes the most recently added TradingStatusChangedListener from the trade.

void resume()

Resumes a previously suspended indicative subscription held by the trade.

void setAccount(String account)

Sets the financial account used for the transfer of funds when the trade is settled.

void setFieldValue(String fieldName, String fieldValue)

Sets the specified field to the specified value.

void setTradeDate(String dt)

Sets the date that the trade was executed.

void setTradingType(String tradingType)

Sets the trading type that this trade will be executed with.

void setUserTradedOnBehalfOf(String user)

Sets user this trade will be executed on behalf of.

void stop()

Releases any resources held by the trade.

void suspend()

Temporarily suspends any indicative subscriptions held by the trade.

void update(Object. newValues)

Updates the trade values using the given map.

Constructor Detail

caplin.trading.trademodel.Trade(String tradingAssetClass, caplin.trading.trademodel.TradeLegFactory tradeLegFactory, caplin.trading.statemachine.StateMachine stateMachine, caplin.trading.trademodel.TradeMessageService tradeMessageService, String tradingProtocol, String tradingType, String assetClass)

Constructs an instance of caplin.trading.trademodel.Trade.

Parameters
String tradingAssetClass The name of the asset class that this trade will be recorded against. This must be defined within the Liberator license — please see the documentation on User Licensing for more information.
caplin.trading.trademodel.TradeLegFactory tradeLegFactory The trade leg factory used to create new trade legs.
caplin.trading.statemachine.StateMachine stateMachine A state machine suitable for the trading protocol being used.
caplin.trading.trademodel.TradeMessageService tradeMessageService The object responsible for sending trade data to and from the trading system.
String tradingProtocol The protocol the trade will be performed with — e.g. ESP, RFQ or RFS.
String tradingType The type of trading that will be performed — e.g. SPOT, FORWARD or SWAP.
String assetClass The asset class that will be traded — e.g. FX (this must not be null for non-exotic trading types).
Throws
caplin.core.Error
if any of the specified arguments are omitted or are of the wrong type.

Method Detail

void addDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, String fieldName, boolean notifyImmediate)

Adds a listener that is called when the specified field is updated.

N.b. If the notifyImmediate flag is set to true and there is a possibility that the field in question does not have a value at the point the listener is registered, then the first call to the caplin.trading.trademodel.DataFieldChangedListener#dataFieldChanged method may be with an undefined value.

Parameters
caplin.trading.trademodel.DataFieldChangedListener listener The listener object to add.
String fieldName The field to listen to.
boolean notifyImmediate if set to true then the listener will be immediately notified of the field's current value, otherwise the listener will first be notified immediately the field changes value (Optional).
See
#addDataFieldsChangedListener
#removeDataFieldChangedListener

void addDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Adds a listener object that is called when any of the specified fields are updated.

Parameters
caplin.trading.trademodel.DataFieldChangedListener listener The listener object to add.
Array fieldNames The list of fields to send updates for.
See
#addDataFieldChangedListener
#removeDataFieldChangedListener

void addDerivation(caplin.trading.derivation.Derivation derivation)

Appends a field derivation to the trade model.

Client side field derivations allow new fields to be calculated in response to changes in server-side, or other client-side derived fields.

Parameters
caplin.trading.derivation.Derivation derivation The derivation instance to add.

void addInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener listener)

Adds a listener that will have its callback method invoked when the server returns data that is somehow invalid. It is expected the client will examine the error and decide on what action to take (e.g. aborting the trade).

Parameters
caplin.trading.trademodel.InvalidServerEventListener listener The listener to add.
See
#removeInvalidServerEventListener

caplin.trading.trademodel.TradeLeg addLeg(String assetClass)

Creates a new trade leg with the specified asset class.

Parameters
String assetClass The asset class that leg will be trading.
Throws
caplin.core.Error
if legs cannot be created.
Returns
{caplin.trading.trademodel.TradeLeg} The newly created leg.

caplin.trading.trademodel.TradeLeg addLegs(String assetClass, Integer count)

Creates a specified number of new trade legs with of the given asset class.

Parameters
String assetClass The asset class that leg will be trading.
Integer count The number of legs to be added.
Throws
caplin.core.Error
if legs cannot be created.
Returns
{Array} An array of the newly created leg references.

void addStateChangedListener(caplin.trading.statemachine.StateChangedListener listener)

Adds a listener that will have its callback method invoked when the state of the trade is updated.

Parameters
caplin.trading.statemachine.StateChangedListener listener The listener to add.
See
#removeStateChangedListener

void addStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)

Adds a listener that will have its callback method invoked when legs are added or removed from the trade.

Parameters
caplin.trading.trademodel.StructureChangedListener listener The listener to add.
See
#removeStructureChangedListener

void addTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)

Adds a listener to listen to trade restored events.

Parameters
caplin.trading.restoration.TradeRestoredListener listener The listener to add.

void addTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener listener)

Adds a specified TradingStatusChangedListener to the trade.

The listener will be notified immediately of current trading state.

Parameters
caplin.trading.trademodel.TradingStatusChangedListener listener The listener to be added.

void addValidator(String state, caplin.trading.validation.Validator validator)

Adds a validator object that is invoked whenever the trade data is being modified, so it can verify the changes before they are committed.

Parameters
String state The state that will cause the validator to be invoked.
caplin.trading.validation.Validator validator The validator to be invoked.

void afterLegAdded(caplin.trading.trademodel.TradeLeg leg, int legId)

Invoked immediately after a leg is added to the trade.

This method can be overridden to provide specific functionality for a particular trade type.

Parameters
caplin.trading.trademodel.TradeLeg leg The leg about to be added to the trade.
int legId The identifier of the leg being added.

void beforeLegAdded(caplin.trading.trademodel.TradeLeg leg, int legId)

Invoked before a leg is added to the trade.

This method can be overridden to provide specific functionality for a particular trade type. N.b. At the point at which this call is made, the new leg will not yet be available within the trade object!

Parameters
caplin.trading.trademodel.TradeLeg leg The leg about to be added to the trade.
int legId The identifier of the leg being added.

String getAccount()

Returns the financial account used for the transfer of funds when the trade is settled.

See
#setAccount

String getAssetClass()

Returns the type of the financial instrument(s) to be traded — e.g FX, FI, EQUITY or COMMODITIES.

The asset class is only defined at the trade level if all of the trade legs have the same asset class. For exotic trades (cross asset), the asset class is only defined within the leg.

Returns
{String} The instrument's asset class

caplin.trading.statemachine.State getCurrentState()

Returns the current state of this trade.

Object getDataAsStructuredMap(Boolean includeLegs)

Takes data from the trade and trade legs and returns it inside a single DataHolder. This is the inverse operation of decodeData.

Parameters
Boolean includeLegs Determines whether the returned object should include legsFieldData
Returns
{Object} All the trade information as a plain JS object of the form: { fieldData: {}, legsFieldData: [ {}, // L1 field data {}, // L2 field data ... ] }

Variant getFieldValue(String fieldName)

Returns the field value with the specified name.

Field names follow the java beans naming convention. For any methods getXxx()/setXxx() there should be a field with the corresponding name, 'xxx'.

Parameters
String fieldName The unique identifier for the field.

int getInitialLegCount(String tradeType)

Returns the initial number of legs to be completed in a trade based on the trade type.

Parameters
String tradeType The trade type for which the initial leg count is being requested.

caplin.trading.trademodel.TradeLeg getLeg(int idx)

Returns the trade leg at the specified index (zero based).

Parameters
int idx The index of the required leg.
Returns
{caplin.trading.trademodel.TradeLeg} The located trade leg.

caplin.trading.trademodel.TradeLeg getLegById(int legId)

Returns the trade leg specified by its ID.

Parameters
int legId The ID of the leg required.
Returns
{caplin.trading.trademodel.TradeLeg} The located trade leg.

Array getLegs()

Returns a copy of the list of trade legs.

To prevent corruption, or change of the list by some external party, a copy of the list is returned, rather than the original list itself.

Returns
{Array} A list of caplin.trading.trademodel.TradeLeg objects.

int getMaxLegCount(String tradeType)

Returns the maximum number of legs allowed in a trade of the specified trade type.

Parameters
String tradeType The trade type for which the maximum leg count is being requested.

String getOverallTimeOut()

Returns the time allowed before the trade will timeout and move to an expired state.

void getRemainingTimeToTrade()

Returns the time that is left until the trade stops being executable

String getRequestID()

Returns the unique identifier assigned by the trade subscriber to track this trade instance.

See
#getTradeID

String getRestorationID()

Returns the ID sent from the server that is used to restore trades.

Returns
{String} The restoration id as sent from the server.

String getServerFailureMessage()

Returns an error message containing the reason for a failure if the trade is in an error state — caused by a failure in the server or the network.

String getState()

Returns the current state of the trade.

Returns
{String} The trade's current state

void getStateMachine()

Returns the state machine associated with this trade.

void getTradeChannelStatus()

Returns only the status of the trade channel and not the pricing channel. Useful for RFQ which are for trades only.

String getTradeDate()

The date the trade is/was executed in YYYYMMDD format.

Returns
{String} The trade date
See
#setTradeDate

String getTradeID()

Returns the unique identifier assigned by the trading system to track this trade instance.

See
#getRequestID

String getTradingProtocol()

Returns the trading protocol that the trade is being executed with.

The trading protocol defines the set of messages that must be passed between the client and server to execute a trade. The actual definitions of the messages, and how the messages are created and consumed is defined within the state machine.

Common examples of trading protocols are ESP (Executable Streaming Price) and RFQ (Request For Quote).

Returns
{String} An identifier representing the trading protocol used by this trade.

int getTradingStatus()

Returns a number indicating whether trading and/or pricing is currently available for this Trade or not. Trading is considered to be unavailable when access to the trading system has been lost. Pricing is considered to be unavailable if access to the pricing system has been lost - this may be used to disable trading if the prices are executable.

The possible return values are provided by the caplin.trading.trademodel.TradingStatus enumeration.

Returns
{int} caplin.trading.trademodel.TradingStatus.AVAILABLE if it is possible to trade, caplin.trading.trademodel.TradingStatus.PRICING_STALE if pricing is unavailable, otherwise caplin.trading.trademodel.TradingStatus.UNAVAILABLE.

String getTradingType()

Returns the trading type that this trade is currently executing — e.g. SPOT, FORWARD or SWAP.

Returns
{String} The trading type
See
#setTradingType

String getUserTradedOnBehalfOf()

Returns the user this trade will be executed on behalf of.

Returns
{String} The user
See
#setUserTradedOnBehalfOf

boolean isEventAllowed(String eventName)

Returns true if the specified event name is currently executable, and false otherwise (including if the event is unknown).

Parameters
String eventName The name of an executable event.
Throws
caplin.core.Error
if the event name is not a string.
Returns
{boolean} true if the event is allowed, otherwise false.

caplin.trading.validation.ValidationResult processClientEvent(String eventName, Map tradeFieldsMap)

This method is called by the client code to request a state transition. The caplin.trading.validation.ValidationResult#getValidationSuccessful method of the result returned by this method indicates whether the transition was successful or not. If the transition was successful the appropriate message will be sent to the trading system. If it failed, the caplin.trading.validation.ValidationResult#getErrors method will return the reason(s) why.

The client code should register itself as a state changed listener to be informed when the state transition occurs using the #addStateChangedListener method.

Please note that if the optional tradeFieldsMap argument is used, the values will be sent to the trading system, however they will not be committed to the trade model.

Parameters
String eventName The name of the transition to be executed.
Map tradeFieldsMap (Optional) A map of the trade field names/values that will be validated and then sent to the trading system. If this is omitted or is null then all of the fields stored within the Trade will be sent to the trading system.
Throws
caplin.core.Error
if the state transition fails for any reason.
Returns
{caplin.trading.validation.ValidationResult} A ValidationResult that indicates whether the state transition was successful or not.

void processServerEvent(String eventName, Map serverReturnedData)

This method is called by the trade subscriber when messages are received from the server.

The internal state and the data contained by the Trade are updated to reflect the data sent by the server. If the sent data is invalid then the trade informs any registered listeners (added via #addInvalidServerEventListener) of any problems.

Parameters
String eventName The name of the transition to be executed — this is the same as the message type sent to the server.
Map serverReturnedData The message content data sent by the server.

void removeAllLegs()

Removes all legs from the trade object.

Throws
caplin.core.Error
if the leg cannot be found.

void removeDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Removes the previously registered DataFieldChangedListener.

Parameters
caplin.trading.trademodel.DataFieldChangedListener listener The listener to remove.
Array fieldNames The name of the fields the listener is being deregistered from.
See
#addDataFieldChangedListener

void removeDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)

Removes a listener object from each of the passed fields.

Parameters
caplin.trading.trademodel.DataFieldChangedListener listener The listener object to remove.
Array fieldNames The list of fields to send updates for.
See
#addDataFieldChangedListener
#removeDataFieldChangedListener

void removeInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener listener)

Removes the previously registered InvalidServerEventListener.

Parameters
caplin.trading.trademodel.InvalidServerEventListener listener The listener to remove.
See
#addInvalidServerEventListener

void removeLeg(caplin.trading.trademodel.TradeLeg leg)

Removes a leg from the trade object.

Parameters
caplin.trading.trademodel.TradeLeg leg The leg to be removed from the trade.
Throws
caplin.core.Error
if the leg cannot be found.

void removeStateChangedListener(caplin.trading.statemachine.StateChangedListener listener)

Removes the previously registered StateChangedListener.

Parameters
caplin.trading.statemachine.StateChangedListener listener The listener to remove.
See
#addStateChangedListener

void removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)

Removes the previously registered StructureChangedListener.

Parameters
caplin.trading.trademodel.StructureChangedListener listener The listener to remove.
See
#addStructureChangedListener

void removeTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)

Removes the specified listener from listening to trade restored events.

Parameters
caplin.trading.restoration.TradeRestoredListener listener The listener to remove.

boolean removeTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener listener)

Removes the most recently added TradingStatusChangedListener from the trade.

Parameters
caplin.trading.trademodel.TradingStatusChangedListener listener The listener to be removed.
Returns
{boolean} true if the listener has been removed, otherwise false.

void resume()

Resumes a previously suspended indicative subscription held by the trade.

This method invocation is propagated to the caplin.trading.trademodel.TradeLeg#resume method on each of the trade legs.

void setAccount(String account)

Sets the financial account used for the transfer of funds when the trade is settled.

Parameters
String account The account to set.
See
#getAccount

void setFieldValue(String fieldName, String fieldValue)

Sets the specified field to the specified value. Any associated caplin.trading.trademodel.DataFieldChangedListeners will be notified of the field change.

Parameters
String fieldName The name of the field to set.
String fieldValue The value to set the field to.

void setTradeDate(String dt)

Sets the date that the trade was executed.

Parameters
String dt The date in format YYYYMMDD.
See
#getTradeDate

void setTradingType(String tradingType)

Sets the trading type that this trade will be executed with.

Parameters
String tradingType The trading type.
See
#getTradingType

void setUserTradedOnBehalfOf(String user)

Sets user this trade will be executed on behalf of.

Parameters
String user The user to set.
See
#getUserTradedOnBehalfOf

void stop()

Releases any resources held by the trade.

This method must be called when the trade is no longer needed, otherwise resource leaks may occur. This method invocation is propagated to the caplin.trading.trademodel.TradeLeg#stop method on each of the trade legs.

void suspend()

Temporarily suspends any indicative subscriptions held by the trade.

This method invocation is propagated to the caplin.trading.trademodel.TradeLeg#suspend method on each of the trade legs.

void update(Object. newValues)

Updates the trade values using the given map. Only new values will be updated.

Parameters
Object. newValues