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 sTradingAssetClass, caplin.trading.trademodel.TradeLegFactory oTradeLegFactory, caplin.trading.statemachine.StateMachine oStateMachine, caplin.trading.trademodel.TradeMessageService oTradeMessageService, String sTradingProtocol, String sTradingType, String sAssetClass)
Constructs an instance of |
Attributes | Name and Description |
---|---|
|
void
addDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, String sFieldName, boolean bNotifyOfCurrentValue)
Adds a listener that is called when the specified field is updated. |
|
void
addDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Adds a listener object that is called when any of the specified fields are updated. |
|
void
addDerivation(caplin.trading.derivation.Derivation oDerivation)
Appends a field derivation to the trade model. |
|
void
addInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener oListener)
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 sAssetClass)
Creates a new trade leg with the specified asset class. |
|
void
addStateChangedListener(caplin.trading.statemachine.StateChangedListener oListener)
Adds a listener that will have its callback method invoked when the state of the trade is updated. |
|
void
addStructureChangedListener(caplin.trading.trademodel.StructureChangedListener oListener)
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 oListener)
Adds a listener to listen to trade restored events. |
|
void
addTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener oListener)
Adds a specified TradingStatusChangedListener to the trade. |
|
void
addValidator(String sStateName, caplin.trading.validation.Validator oValidator)
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 oLeg, int nLegId)
Invoked immediately after a leg is added to the trade. |
|
void
beforeLegAdded(caplin.trading.trademodel.TradeLeg oLeg, int nLegId)
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. |
|
Variant
getFieldValue(String sFieldName)
Returns the field value with the specified name. |
|
int
getInitialLegCount(String sTradeType)
Returns the initial number of legs to be completed in a trade based on the trade type. |
|
caplin.trading.trademodel.TradeLeg
getLeg(int nIndex)
Returns the trade leg at the specified index (zero based). |
|
Array
getLegs()
Returns a copy of the list of trade legs. |
|
int
getMaxLegCount(String sTradeType)
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
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 sEventName)
Returns |
|
caplin.trading.validation.ValidationResult
processClientEvent(String sEventName, Map mTradeFieldsMap)
This method is called by the client code to request a state transition. |
|
void
processServerEvent(String sEventName, Map)
This method is called by the trade subscriber when messages are received from the server. |
|
void
removeDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Removes the previously registered |
|
void
removeDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Removes a listener object from each of the passed fields. |
|
void
removeInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener oListener)
Removes the previously registered |
|
void
removeLeg(caplin.trading.trademodel.TradeLeg oLeg)
Removes a leg from the trade object. |
|
void
removeStateChangedListener(caplin.trading.statemachine.StateChangedListener oListener)
Removes the previously registered |
|
void
removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener oListener)
Removes the previously registered |
|
void
removeTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener oListener)
Removes the specified listener from listening to trade restored events. |
|
boolean
removeTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener oListener)
Removes the most recently added TradingStatusChangedListener from the trade. |
|
void
resume()
Resumes a previously suspended indicative subscription held by the trade. |
|
void
setAccount(String sAccount)
Sets the financial account used for the transfer of funds when the trade is settled. |
|
void
setFieldValue(String sFieldName, String sFieldValue)
Sets the specified field to the specified value. |
|
void
setTradeDate(String sDate)
Sets the date that the trade was executed. |
|
void
setTradingType(String sTradingType)
Sets the trading type that this trade will be executed with. |
|
void
setUserTradedOnBehalfOf(String sUser)
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. |
►
caplin.trading.trademodel.Trade(String sTradingAssetClass, caplin.trading.trademodel.TradeLegFactory oTradeLegFactory, caplin.trading.statemachine.StateMachine oStateMachine, caplin.trading.trademodel.TradeMessageService oTradeMessageService, String sTradingProtocol, String sTradingType, String sAssetClass)
Constructs an instance of caplin.trading.trademodel.Trade
.
String | sTradingAssetClass | 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 | oTradeLegFactory | The trade leg factory used to create new trade legs. |
caplin.trading.statemachine.StateMachine | oStateMachine | A state machine suitable for the trading protocol being used. |
caplin.trading.trademodel.TradeMessageService | oTradeMessageService | The object responsible for sending trade data to and from the trading system. |
String | sTradingProtocol | The protocol the trade will be performed with — e.g. ESP, RFQ or RFS. |
String | sTradingType | The type of trading that will be performed — e.g. SPOT, FORWARD or SWAP. |
String | sAssetClass | 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 oListener, String sFieldName, boolean bNotifyOfCurrentValue)
Adds a listener that is called when the specified field is updated.
N.b. If the bNotifyOfCurrentValue
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 | oListener | The listener object to add. |
String | sFieldName | The field to listen to. |
boolean | bNotifyOfCurrentValue | if set to true then the listener will be immediately notified of
the fields current value, otherwise the listener will first be notified immediately the field changes value
(Optional). |
►
void
addDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Adds a listener object that is called when any of the specified fields are updated.
caplin.trading.trademodel.DataFieldChangedListener | oListener | The listener object to add. |
Array | pFieldNames | The list of fields to send updates for. |
►
void
addDerivation(caplin.trading.derivation.Derivation oDerivation)
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 | oDerivation | The derivation instance to add. |
►
void
addInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener oListener)
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 | oListener | The listener to add. |
►
caplin.trading.trademodel.TradeLeg
addLeg(String sAssetClass)
Creates a new trade leg with the specified asset class.
String | sAssetClass | The asset class that leg will be trading. |
►
void
addStateChangedListener(caplin.trading.statemachine.StateChangedListener oListener)
Adds a listener that will have its callback method invoked when the state of the trade is updated.
caplin.trading.statemachine.StateChangedListener | oListener | The listener to add. |
►
void
addStructureChangedListener(caplin.trading.trademodel.StructureChangedListener oListener)
Adds a listener that will have its callback method invoked when legs are added or removed from the trade.
caplin.trading.trademodel.StructureChangedListener | oListener | The listener to add. |
►
void
addTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener oListener)
Adds a listener to listen to trade restored events.
caplin.trading.restoration.TradeRestoredListener | oListener | The listener to add. |
►
void
addTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener oListener)
Adds a specified TradingStatusChangedListener to the trade. The listener will be notified immediately of current trading state.
caplin.trading.trademodel.TradingStatusChangedListener | oListener | The listener to be added. |
►
void
addValidator(String sStateName, caplin.trading.validation.Validator oValidator)
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 | sStateName | The state that will cause the validator to be invoked. |
caplin.trading.validation.Validator | oValidator | The validator to be invoked. |
►
void
afterLegAdded(caplin.trading.trademodel.TradeLeg oLeg, int nLegId)
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 | oLeg | The leg about to be added to the trade. |
int | nLegId | The identifier of the leg being added. |
►
void
beforeLegAdded(caplin.trading.trademodel.TradeLeg oLeg, int nLegId)
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 | oLeg | The leg about to be added to the trade. |
int | nLegId | 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.
►
Variant
getFieldValue(String sFieldName)
Returns the field value with the specified name.
The field name follows the java beans naming convention. For any methods
getXxx()
/setXxx()
there should be a field with the corresponding name, 'xxx'.
String | sFieldName | The unique identifier for the field. |
►
int
getInitialLegCount(String sTradeType)
Returns the initial number of legs to be completed in a trade based on the trade type.
String | sTradeType | The trade type for which the initial leg count is being requested. |
►
caplin.trading.trademodel.TradeLeg
getLeg(int nIndex)
Returns the trade leg at the specified index (zero based).
int | nIndex | The index 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 sTradeType)
Returns the maximum number of legs allowed in a trade of the specified trade type.
String | sTradeType | 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
getTradeChannelStatus()
Returns only the status of the trade channel and not the pricing channel. Useful for RFQ which are for trades only.
►
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
at the moment, caplin.trading.trademodel.TradingStatus.PRICING_STALE
if the
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 sEventName)
Returns true
if the specified event name is currently executable, and false
otherwise
(including if the event is unknown).
String | sEventName | The name of an executable event. |
►
caplin.trading.validation.ValidationResult
processClientEvent(String sEventName, Map mTradeFieldsMap)
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 mTradeFieldsMap
argument is used, the values
will be sent to the trading system, however they will not be committed to the trade model.
String | sEventName | The name of the transition to be executed. |
Map | mTradeFieldsMap | (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 the state transition was
successful or not.
►
void
processServerEvent(String sEventName, Map)
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 | sEventName | The name of the transition to be executed — this is the same as the message type sent to the server. |
Map | oServerReturnedData The message content data sent by the server. |
►
void
removeDataFieldChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Removes the previously registered DataFieldChangedListener
.
caplin.trading.trademodel.DataFieldChangedListener | oListener | The listener to remove. |
Array | pFieldNames | The name of the fields the listener is being deregistered from. |
►
void
removeDataFieldsChangedListener(caplin.trading.trademodel.DataFieldChangedListener oListener, Array pFieldNames)
Removes a listener object from each of the passed fields.
caplin.trading.trademodel.DataFieldChangedListener | oListener | The listener object to remove. |
Array | pFieldNames | The list of fields to send updates for. |
►
void
removeInvalidServerEventListener(caplin.trading.trademodel.InvalidServerEventListener oListener)
Removes the previously registered InvalidServerEventListener
.
caplin.trading.trademodel.InvalidServerEventListener | oListener | The listener to remove. |
►
void
removeLeg(caplin.trading.trademodel.TradeLeg oLeg)
Removes a leg from the trade object.
caplin.trading.trademodel.TradeLeg | oLeg | The leg to be removed from the trade. |
►
void
removeStateChangedListener(caplin.trading.statemachine.StateChangedListener oListener)
Removes the previously registered StateChangedListener
.
caplin.trading.statemachine.StateChangedListener | oListener | The listener to remove. |
►
void
removeStructureChangedListener(caplin.trading.trademodel.StructureChangedListener oListener)
Removes the previously registered StructureChangedListener
.
caplin.trading.trademodel.StructureChangedListener | oListener | The listener to remove. |
►
void
removeTradeRestoredListener(caplin.trading.restoration.TradeRestoredListener oListener)
Removes the specified listener from listening to trade restored events.
caplin.trading.restoration.TradeRestoredListener | oListener | The listener to remove. |
►
boolean
removeTradingStatusChangedListener(caplin.trading.trademodel.TradingStatusChangedListener oListener)
Removes the most recently added TradingStatusChangedListener from the trade.
caplin.trading.trademodel.TradingStatusChangedListener | oListener | The listener to be removed. |
►
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 sAccount)
Sets the financial account used for the transfer of funds when the trade is settled.
String | sAccount | The account to set. |
►
void
setFieldValue(String sFieldName, String sFieldValue)
Sets the specified field to the specified value. Any associated caplin.trading.trademodel.DataFieldChangedListeners will be notified of the field change.
String | sFieldName | The name of the field to set. |
String | sFieldValue | The value to set the field to. |
►
void
setTradeDate(String sDate)
Sets the date that the trade was executed.
String | sDate | The date in format YYYYMMDD. |
►
void
setTradingType(String sTradingType)
Sets the trading type that this trade will be executed with.
String | sTradingType | The trading type. |
►
void
setUserTradedOnBehalfOf(String sUser)
Sets user this trade will be executed on behalf of.
String | sUser | 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.