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.
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 |
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
void
removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)
Removes the previously registered |
|
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.
Updates the trade values using the given map. |
►
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
.
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). |
►
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.
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). |
►
void
addDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)
Adds a listener object that is called when any of the specified fields are updated.
caplin.trading.trademodel.DataFieldChangedListener | listener | The listener object to add. |
Array | fieldNames | The list of fields to send updates for. |
►
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.
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).
caplin.trading.trademodel.InvalidServerEventListener | listener | The listener to add. |
►
caplin.trading.trademodel.TradeLeg
addLeg(String assetClass)
Creates a new trade leg with the specified asset class.
String | assetClass | The asset class that leg will be trading. |
►
caplin.trading.trademodel.TradeLeg
addLegs(String assetClass, Integer count)
Creates a specified number of new trade legs with of the given asset class.
String | assetClass | The asset class that leg will be trading. |
Integer | count | The number of legs to be added. |
►
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.
caplin.trading.statemachine.StateChangedListener | listener | The listener to add. |
►
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.
caplin.trading.trademodel.StructureChangedListener | listener | The listener to add. |
►
void
addTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)
Adds a listener to listen to trade restored events.
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.
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.
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.
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!
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.
►
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.
►
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.
Boolean | includeLegs | Determines whether the returned object should include legsFieldData |
{
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'.
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.
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).
int | idx | The index of the required leg. |
►
caplin.trading.trademodel.TradeLeg
getLegById(int legId)
Returns the trade leg specified by its ID.
int | legId | The ID of the leg required. |
►
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.
►
int
getMaxLegCount(String tradeType)
Returns the maximum number of legs allowed in a trade of the specified trade type.
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.
►
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. Useful for RFQ which are for trades only.
►
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.
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).
►
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.
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.
►
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).
String | eventName | The name of an executable event. |
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.
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. |
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.
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.
►
void
removeDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)
Removes the previously registered DataFieldChangedListener
.
caplin.trading.trademodel.DataFieldChangedListener | listener | The listener to remove. |
Array | fieldNames | The name of the fields the listener is being deregistered from. |
►
void
removeDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener listener, Array fieldNames)
Removes a listener object from each of the passed fields.
caplin.trading.trademodel.DataFieldChangedListener | listener | The listener object to remove. |
Array | fieldNames | The list of fields to send updates for. |
►
void
removeInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener listener)
Removes the previously registered InvalidServerEventListener
.
caplin.trading.trademodel.InvalidServerEventListener | listener | The listener to remove. |
►
void
removeLeg(caplin.trading.trademodel.TradeLeg leg)
Removes a leg from the trade object.
caplin.trading.trademodel.TradeLeg | leg | The leg to be removed from the trade. |
►
void
removeStateChangedListener(caplin.trading.statemachine.StateChangedListener listener)
Removes the previously registered StateChangedListener
.
caplin.trading.statemachine.StateChangedListener | listener | The listener to remove. |
►
void
removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener listener)
Removes the previously registered StructureChangedListener
.
caplin.trading.trademodel.StructureChangedListener | listener | The listener to remove. |
►
void
removeTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener listener)
Removes the specified listener from listening to trade restored events.
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.
caplin.trading.trademodel.TradingStatusChangedListener | listener | The listener to be removed. |
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.
String | account | The account to set. |
►
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.
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.
String | dt | The date in format YYYYMMDD. |
►
void
setTradingType(String tradingType)
Sets the trading type that this trade will be executed with.
String | tradingType | The trading type. |
►
void
setUserTradedOnBehalfOf(String user)
Sets user this trade will be executed on behalf of.
String | user | The user to set. |
►
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.
Updates the trade values using the given map. Only new values will be updated.
Object. |
newValues |