JSDoc: Class: module:caplin/trading/trademodel/Trade

Class: module:caplin/trading/trademodel/Trade

module:caplin/trading/trademodel/Trade

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

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

Constructs an instance of caplin.trading.trademodel.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:caplin/trading/trademodel/TradeLegFactory	The trade leg factory used to create new trade legs.
`stateMachine`	module:caplin/trading/statemachine/StateMachine	A state machine suitable for the trading protocol being used.
`tradeMessageService`	module:caplin/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.

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

Parameters:

Name	Type	Attributes	Description
`listener`	module:caplin/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:caplin/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:caplin/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:caplin/trading/trademodel/InvalidServerEventListener	The listener to add.

See:

module:caplin/trading/trademodel/Trade#removeInvalidServerEventListener

addLeg(assetClass) → {module:caplin/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.

Returns:

The newly created leg.

Type: module:caplin/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.

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:caplin/trading/statemachine/StateChangedListener	The listener to add.

See:

module:caplin/trading/trademodel/Trade#removeStateChangedListener

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:caplin/trading/trademodel/StructureChangedListener	The listener to add.

See:

module:caplin/trading/trademodel/Trade#removeStructureChangedListener

addTradeRestoredListener(listener)

Adds a listener to listen to trade restored events.

Parameters:

Name	Type	Description
`listener`	module:caplin/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:caplin/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:caplin/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:caplin/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:caplin/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:

module:caplin/trading/trademodel/Trade#setAccount

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:caplin/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:caplin/trading/trademodel/TradeLeg

getLegById(legId) → {module:caplin/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:caplin/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:caplin/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:

module:caplin/trading/trademodel/Trade#getTradeID

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:

module:caplin/trading/trademodel/Trade#setTradeDate

Returns:

The trade date

Type: String

getTradeID()

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

See:

module:caplin/trading/trademodel/Trade#getRequestID

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:caplin/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:

module:caplin/trading/trademodel/Trade#setTradingType

Returns:

The trading type

Type: String

getUserTradedOnBehalfOf() → {String}

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

See:

module:caplin/trading/trademodel/Trade#setUserTradedOnBehalfOf

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.

Returns:

true if the event is allowed, otherwise false.

Type: boolean

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

This method is called by the client code to request a state transition. The module: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 module: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 module:caplin/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.

Returns:

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

Type: module:caplin/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:caplin/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.

removeDataFieldChangedListener(listener, fieldNames)

Removes the previously registered DataFieldChangedListener.

Parameters:

Name	Type	Description
`listener`	module:caplin/trading/trademodel/DataFieldChangedListener	The listener to remove.
`fieldNames`	Array	The name of the fields the listener is being deregistered from.

See:

module:caplin/trading/trademodel/Trade#addDataFieldChangedListener

removeDataFieldsChangedListener(listener, fieldNames)

Removes a listener object from each of the passed fields.

Parameters:

Name	Type	Description
`listener`	module:caplin/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:caplin/trading/trademodel/InvalidServerEventListener	The listener to remove.

See:

module:caplin/trading/trademodel/Trade#addInvalidServerEventListener

removeLeg(leg)

Removes a leg from the trade object.

Parameters:

Name	Type	Description
`leg`	module:caplin/trading/trademodel/TradeLeg	The leg to be removed from the trade.

Throws:

if the leg cannot be found.

removeStateChangedListener(listener)

Removes the previously registered StateChangedListener.

Parameters:

Name	Type	Description
`listener`	module:caplin/trading/statemachine/StateChangedListener	The listener to remove.

See:

module:caplin/trading/trademodel/Trade#addStateChangedListener

removeStructureChangedListener(listener)

Removes the previously registered StructureChangedListener.

Parameters:

Name	Type	Description
`listener`	module:caplin/trading/trademodel/StructureChangedListener	The listener to remove.

See:

module:caplin/trading/trademodel/Trade#addStructureChangedListener

removeTradeRestoredListener(listener)

Removes the specified listener from listening to trade restored events.

Parameters:

Name	Type	Description
`listener`	module:caplin/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:caplin/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:caplin/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:

module:caplin/trading/trademodel/Trade#getAccount

setFieldValue(fieldName, fieldValue)

Sets the specified field to the specified value. Any associated module:caplin/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:

module:caplin/trading/trademodel/Trade#getTradeDate

setTradingType(tradingType)

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

Parameters:

Name	Type	Description
`tradingType`	String	The trading type.

See:

module:caplin/trading/trademodel/Trade#getTradingType

setUserTradedOnBehalfOf(user)

Sets user this trade will be executed on behalf of.

Parameters:

Name	Type	Description
`user`	String	The user to set.

See:

module:caplin/trading/trademodel/Trade#getUserTradedOnBehalfOf

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:caplin/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:caplin/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>