Caplin Trader 5.1.0

Class: module:ct-fx/trademodel/FxTrade

module:ct-fx/trademodel/FxTrade(legFactory, stateMachine, tradeMessageService, tradeProtocol, tradeType)

new module:ct-fx/trademodel/FxTrade(legFactory, stateMachine, tradeMessageService, tradeProtocol, tradeType)

Constructs a FxTrade.

The FX Trade adds functions specific for FX trades to the generic module:ct-trading/trademodel/Trade class.

Extends:
Parameters:
Name Type Description
legFactory module:ct-trading/trademodel/TradeLegFactory

The Trade leg factory use to create trade legs. Must not be null.
stateMachine module:ct-trading/statemachine/StateMachine

A StateMachine suitable for the trading protocol. Must not be null.
tradeMessageService module:ct-trading/trademodel/TradeMessageService

A TradeMessageService responsible for sending trade data to and from the trading system. Must not be null.
tradeProtocol String

The protocol used for trading, for example ESP, RFQ or RFS.
tradeType String

The type of trading this instance will perform, for example SPOT, FORWARD or SWAP.

Extends

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.
Inherited From:
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.
Inherited From:
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.
Inherited From:

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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:

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.
Inherited From:

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.
Inherited From:

afterLegAdded(leg, legId)

Checks if this is a second leg being added to the trade, and if so sets the instrument to the same value as the first leg. This assumes that a two legged FX trade represents a swap.

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.
Overrides:

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.
Inherited From:

getAccount()

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

Inherited From:
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.

Inherited From:
Returns:

The instrument's asset class

Type
String

getCurrentState()

Returns the current state of this trade.

Inherited From:

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
Inherited From:
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.
Inherited From:

getInitialLegCount(tradeType) → {int}

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

Parameters:
Name Type Description
tradeType String

A string representation of the trade type (SPOT, FWD, SWAP or FWDFWDSWAP).
Overrides:
Returns:

The initial number of legs for this FX trade.

Type
int

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.
Inherited From:
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.
Inherited From:
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.

Inherited From:
Returns:

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

Type
Array

getMaxLegCount(tradeType) → {int}

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

Parameters:
Name Type Description
tradeType String

A string representation of the trade type (SPOT, FWD, SWAP or FWDFWDSWAP).
Overrides:
Returns:

The maximum number of legs for this FX trade.

Type
int

getOverallTimeOut()

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

Inherited From:

getRemainingTimeToTrade()

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

Inherited From:

getRequestID()

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

Inherited From:
See:

getRestorationID() → {String}

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

Inherited From:
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.

Inherited From:

getState() → {String}

Returns the current state of the trade.

Inherited From:
Returns:

The trade's current state

Type
String

getStateMachine()

Returns the state machine associated with this trade.

Inherited From:

getTradeChannelStatus()

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

Inherited From:

getTradeDate() → {String}

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

Inherited From:
See:
Returns:

The trade date

Type
String

getTradeID()

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

Inherited From:
See:

getTradeMeta() → {Object}

Inherited From:
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).

Inherited From:
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.

Inherited From:
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.

Inherited From:
See:
Returns:

The trading type

Type
String

getUserTradedOnBehalfOf() → {String}

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

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:

removeAllLegs()

Removes all legs from the trade object.

Inherited From:
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.
Inherited 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.
Inherited From:
See:

removeInvalidServerEventListener(listener)

Removes the previously registered InvalidServerEventListener.

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

The listener to remove.
Inherited From:
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.
Inherited From:
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.
Inherited From:
See:

removeStructureChangedListener(listener)

Removes the previously registered StructureChangedListener.

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

The listener to remove.
Inherited From:
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.
Inherited From:

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.
Inherited From:
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.

Inherited From:

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.
Inherited From:
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.
Inherited From:

setTradeDate(dt)

Sets the date that the trade was executed.

Parameters:
Name Type Description
dt String

The date in format YYYYMMDD.
Inherited From:
See:

setTradingType(tradingType)

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

Parameters:
Name Type Description
tradingType String

The trading type.
Inherited From:
See:

setUserTradedOnBehalfOf(user)

Sets user this trade will be executed on behalf of.

Parameters:
Name Type Description
user String

The user to set.
Inherited From:
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.

Inherited From:

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.

Inherited From:

update(newValues)

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

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