Caplin Trader 5.1.0

Class: module:ct-trading/trademodel/Trade

module:ct-trading/trademodel/Trade(tradingAssetClass, tradeLegFactory, stateMachine, tradeMessageService, tradingProtocol, tradingType, assetClass)

A Trade represents the exchange of a number of financial instruments between counter-parties. Each exchange is represented by a module:ct-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 module:ct-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

new module:ct-trading/trademodel/Trade(tradingAssetClass, tradeLegFactory, stateMachine, tradeMessageService, tradingProtocol, tradingType, assetClass)

Constructs an instance of Trade.

Parameters:
Name Type Description
tradingAssetClass String

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.
tradeLegFactory module:ct-trading/trademodel/TradeLegFactory

The trade leg factory used to create new trade legs.
stateMachine module:ct-trading/statemachine/StateMachine

A state machine suitable for the trading protocol being used.
tradeMessageService module:ct-trading/trademodel/TradeMessageService

The object responsible for sending trade data to and from the trading system.
tradingProtocol String

The protocol the trade will be performed with — e.g. ESP, RFQ or RFS.
tradingType String

The type of trading that will be performed — e.g. SPOT, FORWARD or SWAP.
assetClass String

The asset class that will be traded — e.g. FX (this must not be null for non-exotic trading types).
Throws:

if any of the specified arguments are omitted or are of the wrong type.

Type
module:ct-core/Error

Methods

addDataFieldChangedListener(listener, fieldName, notifyImmediateopt)

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 module:ct-trading/trademodel/DataFieldChangedListener#dataFieldChanged method may be with an undefined value.

Parameters:
Name Type Attributes Description
listener module:ct-trading/trademodel/DataFieldChangedListener

The listener object to add.
fieldName String

The field to listen to.
notifyImmediate boolean <optional>

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 after the field changes value.
See:

addDataFieldsChangedListener(listener, fieldNames)

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

Parameters:
Name Type Description
listener module:ct-trading/trademodel/DataFieldChangedListener

The listener object to add.
fieldNames Array

The list of fields to send updates for.
See:

addDerivation(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:
Name Type Description
derivation module:ct-trading/derivation/Derivation

The derivation instance to add.

addInvalidServerEventListener(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:
Name Type Description
listener module:ct-trading/trademodel/InvalidServerEventListener

The listener to add.
See:

addLeg(assetClass) → {module:ct-trading/trademodel/TradeLeg}

Creates a new trade leg with the specified asset class.

Parameters:
Name Type Description
assetClass String

The asset class that leg will be trading.
Throws:

if legs cannot be created.

Type
module:ct-core/Error
Returns:

The newly created leg.

Type
module:ct-trading/trademodel/TradeLeg

addLegs(assetClass, count) → {Array}

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

Parameters:
Name Type Description
assetClass String

The asset class that leg will be trading.
count Integer

The number of legs to be added.
Throws:

if legs cannot be created.

Type
module:ct-core/Error
Returns:

An array of the newly created leg references.

Type
Array

addStateChangedListener(listener)

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

Parameters:
Name Type Description
listener module:ct-trading/statemachine/StateChangedListener

The listener to add.
See:

addStructureChangedListener(listener)

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

Parameters:
Name Type Description
listener module:ct-trading/trademodel/StructureChangedListener

The listener to add.
See:

addTradeRestoredListener(listener)

Adds a listener to listen to trade restored events.

Parameters:
Name Type Description
listener module:ct-trading/restoration/TradeRestoredListener

The listener to add.

addTradingStatusChangedListener(listener)

Adds a specified TradingStatusChangedListener to the trade.

The listener will be notified immediately of current trading state.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/TradingStatusChangedListener

The listener to be added.

addValidator(state, 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:
Name Type Description
state String

The state that will cause the validator to be invoked.
validator module:ct-trading/validation/Validator

The validator to be invoked.

afterLegAdded(leg, 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:
Name Type Description
leg module:ct-trading/trademodel/TradeLeg

The leg about to be added to the trade.
legId int

The identifier of the leg being added.

beforeLegAdded(leg, 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:
Name Type Description
leg module:ct-trading/trademodel/TradeLeg

The leg about to be added to the trade.
legId int

The identifier of the leg being added.

getAccount()

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

See:

getAssetClass() → {String}

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:

The instrument's asset class

Type
String

getCurrentState()

Returns the current state of this trade.

getDataAsStructuredMap(includeLegs) → {Object}

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

Parameters:
Name Type Description
includeLegs Boolean

Determines whether the returned object should include legsFieldData
Returns:

All the trade information as a plain JS object of the form:

{ fieldData: {}, legsFieldData: [ {}, // L1 field data {}, // L2 field data ... ] }
Type
Object

getFieldValue(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:
Name Type Description
fieldName String

The unique identifier for the field.

getInitialLegCount(tradeType)

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

Parameters:
Name Type Description
tradeType String

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

getLeg(idx) → {module:ct-trading/trademodel/TradeLeg}

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

Parameters:
Name Type Description
idx int

The index of the required leg.
Returns:

The located trade leg.

Type
module:ct-trading/trademodel/TradeLeg

getLegById(legId) → {module:ct-trading/trademodel/TradeLeg}

Returns the trade leg specified by its ID.

Parameters:
Name Type Description
legId int

The ID of the leg required.
Returns:

The located trade leg.

Type
module:ct-trading/trademodel/TradeLeg

getLegs() → {Array}

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:

A list of module:ct-trading/trademodel/TradeLeg objects.

Type
Array

getMaxLegCount(tradeType)

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

Parameters:
Name Type Description
tradeType String

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

getOverallTimeOut()

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

getRemainingTimeToTrade()

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

getRequestID()

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

See:

getRestorationID() → {String}

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

Returns:

The restoration id as sent from the server.

Type
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.

getState() → {String}

Returns the current state of the trade.

Returns:

The trade's current state

Type
String

getStateMachine()

Returns the state machine associated with this trade.

getTradeChannelStatus()

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

getTradeDate() → {String}

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

See:
Returns:

The trade date

Type
String

getTradeID()

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

See:

getTradeMeta() → {Object}

Returns:

All the trade information as a plain JS object. The legs will be stored in an array un-prefixed.

Type
Object

getTradingProtocol() → {String}

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:

An identifier representing the trading protocol used by this trade.

Type
String

getTradingStatus() → {int}

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 module:ct-trading/trademodel/TradingStatus enumeration.

Returns:

TradingStatus.AVAILABLE if it is possible to trade, TradingStatus.PRICING_STALE if pricing is unavailable, otherwise TradingStatus.UNAVAILABLE.

Type
int

getTradingType() → {String}

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

See:
Returns:

The trading type

Type
String

getUserTradedOnBehalfOf() → {String}

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

See:
Returns:

The user

Type
String

isEventAllowed(eventName) → {boolean}

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

Parameters:
Name Type Description
eventName String

The name of an executable event.
Throws:

if the event name is not a string.

Type
module:ct-core/Error
Returns:

true if the event is allowed, otherwise false.

Type
boolean

processClientEvent(eventName, tradeFieldsMapopt) → {module:ct-trading/validation/ValidationResult}

This method is called by the client code to request a state transition. The module:ct-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 module:ct-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 module:ct-trading/trademodel/Trade#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:
Name Type Attributes Description
eventName String

The name of the transition to be executed.
tradeFieldsMap Map <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:

if the state transition fails for any reason.

Type
module:ct-core/Error
Returns:

A ValidationResult that indicates whether the state transition was successful or not.

Type
module:ct-trading/validation/ValidationResult

processServerEvent(eventName, 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 module:ct-trading/trademodel/Trade#addInvalidServerEventListener) of any problems.

Parameters:
Name Type Description
eventName String

The name of the transition to be executed — this is the same as the message type sent to the server.
serverReturnedData Map

The message content data sent by the server.

removeAllLegs()

Removes all legs from the trade object.

Throws:

if the leg cannot be found.

Type
module:ct-core/Error

removeDataFieldChangedListener(listener, fieldNames)

Removes the previously registered DataFieldChangedListener.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/DataFieldChangedListener

The listener to remove.
fieldNames Array

The name of the fields the listener is being deregistered from.
See:

removeDataFieldsChangedListener(listener, fieldNames)

Removes a listener object from each of the passed fields.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/DataFieldChangedListener

The listener object to remove.
fieldNames Array

The list of fields to send updates for.
See:

removeInvalidServerEventListener(listener)

Removes the previously registered InvalidServerEventListener.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/InvalidServerEventListener

The listener to remove.
See:

removeLeg(leg)

Removes a leg from the trade object.

Parameters:
Name Type Description
leg module:ct-trading/trademodel/TradeLeg

The leg to be removed from the trade.
Throws:

if the leg cannot be found.

Type
module:ct-core/Error

removeStateChangedListener(listener)

Removes the previously registered StateChangedListener.

Parameters:
Name Type Description
listener module:ct-trading/statemachine/StateChangedListener

The listener to remove.
See:

removeStructureChangedListener(listener)

Removes the previously registered StructureChangedListener.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/StructureChangedListener

The listener to remove.
See:

removeTradeRestoredListener(listener)

Removes the specified listener from listening to trade restored events.

Parameters:
Name Type Description
listener module:ct-trading/restoration/TradeRestoredListener

The listener to remove.

removeTradingStatusChangedListener(listener) → {boolean}

Removes the most recently added TradingStatusChangedListener from the trade.

Parameters:
Name Type Description
listener module:ct-trading/trademodel/TradingStatusChangedListener

The listener to be removed.
Returns:

true if the listener has been removed, otherwise false.

Type
boolean

resume()

Resumes a previously suspended indicative subscription held by the trade.

This method invocation is propagated to the module:ct-trading/trademodel/TradeLeg#resume method on each of the trade legs.

setAccount(account)

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

Parameters:
Name Type Description
account String

The account to set.
See:

setFieldValue(fieldName, fieldValue)

Sets the specified field to the specified value. Any associated module:ct-trading/trademodel/DataFieldChangedListeners will be notified of the field change.

Parameters:
Name Type Description
fieldName String

The name of the field to set.
fieldValue String

The value to set the field to.

setTradeDate(dt)

Sets the date that the trade was executed.

Parameters:
Name Type Description
dt String

The date in format YYYYMMDD.
See:

setTradingType(tradingType)

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

Parameters:
Name Type Description
tradingType String

The trading type.
See:

setUserTradedOnBehalfOf(user)

Sets user this trade will be executed on behalf of.

Parameters:
Name Type Description
user String

The user to set.
See:

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 module:ct-trading/trademodel/TradeLeg#stop method on each of the trade legs.

suspend()

Temporarily suspends any indicative subscriptions held by the trade.

This method invocation is propagated to the module:ct-trading/trademodel/TradeLeg#suspend method on each of the trade legs.

update(newValues)

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

Parameters:
Name Type Description
newValues Object.<String, String>