The order state container components provide an action-based interface to the standard com.apama.oms.* event interface for order management. For a CMF-based application, order state containers implement and enforce well-defined semantics on top of the event protocol. The application does not need to directly route and listen for com.apama.oms.* events. This means that all users of the containers agree on the meaning of, for example, a specific OrderUpdate event. This level of agreement is very difficult to achieve if each application constructs and interprets the events according to its own rules.

There are three different order state container objects in the com.apama.oms package:

In a typical algorithmic trading application, where the application strategy is submitting orders to an external venue via an adapter, the application will use an OrderPublisherStateContainer to encapsulate each order it submits, while the adapter will use an OrderReceiverStateContainer to represent the state of each order on the external venue and to report updates back to the application. In the case of an application accepting client orders, the application itself should use an OrderReceiverStateContainer while the adapter delivering the orders to the application is likely to use an OrderPublisherStateContainer for each client order. The OrderMonitorStateContainer is typically used by services to track the state of all the orders in the system, including those that were submitted through other applications.

As the APIs provided by the order state container objects are all quite similar, this section focuses on the OrderPublisherStateContainer and mentions significant differences to the other containers when these are relevant.

The OrderPublisherStateContainer object can be used to submit new orders, amend or cancel submitted orders, and query order state. To create a new order, an application should first construct a new com.apama.oms.OrderPublisherStateContainer then call either the submit() or submitQuick() action. Orders can also be submitted through the risk firewall. The submit() action takes a fully-initialized com.apama.oms.NewOrder event as its argument whereas submitQuick() avoids the need to construct the NewOrder event but only allows a limited set of order parameters to be controlled. The following example how to submit a new order using the order publisher state container. This example uses the submitQuick() action to create a new market order to sell 1 million EUR/USD at a price of 1.20365, and submit the order to the venue with the serviceId of FIX and marketId of CNX:

Applications can register a callback with the publisher which will be called when the state of the order changes. A string is used to uniquely identify an update callback, so that it may be removed at a later date. The callback that you define will contain the unique identifier of the publisher that has called the action, and the current state of the order. The unique id will match that obtained by calling getPubId() on the publisher, so an application can identify the publisher that sent the update. This object encapsulates the complete state of the order and is used by all of the order state containers.

The OrderState object provides a large set of actions for querying the internal state of the order being handled. These are described in detail in the ApamaDoc for the OrderState object. In order to determine what the current state of the order is in, and to determine when the order makes a state transition, two sets of query actions are provided. The is*() and just*() actions allow an application to query the status of an order, for example, whether the order is "final" or not. The results of the is*() actions indicate whether or not the order is currently in that state, so isCancelled() will return true if the order has been canceled. The just*() actions are similar but their results indicate whether the queried status was true only for the most recent update processed by the container. For example, justAcknowledged() will return true for the update immediately after the order is acknowledged, but not on any subsequent updates, whereas isAcknowledged() will always return true after the order has been acknowledged.

Many of the OrderState actions of the OrderPublisherStateContainer are mirrored on the container itself for convenience.

The OrderReceiverStateContainer differs mainly in that the application is responsible for setting the state of the order rather than querying it. An instance of the OrderReceiverStateContainer object should be created whenever a service receives a NewOrder event with appropriate addressing information. In the example below, a new order receiver state container object is created for every new order that is received and receiveOrder is called to start handling the state of that order. The quantity of the order is then checked for a maximum limit, and the order is either filled or rejected accordingly.

There are a number of actions that can be called on the order receiver to change the state of the order. These include actions to handle amends, cancels, rejections, fills, etc. State-changing actions such as acknowledge() will cause the container to route an OrderUpdate event. If the application used an OrderPublisherStateContainer object to submit the order, any update handler callbacks it registered will be called. The OrderReceiverStateContainer also has the same set of is*() and just*() actions as the OrderPublisherStateContainer object that can be used to query the current state of the order being managed.

The OrderMonitorStateContainer is very similar to the both the OrderPublisherStateContainer and the OrderReceiverStateContainer but does not have the ability to actually submit, amend or cancel orders. The OrderMonitorStateContainer also has is* and just* actions that can be used to query the current state of the order being monitored.

In the example below, a new order monitor state container object is created for every new order that is received and monitorOrder() is called to start monitoring the state of that order. The addUpdateListener() action is called to register a callback action with the monitor state container that will be called whenever the state of the order changes. A string is used to uniquely identify an update callback, so that it may be removed at a later date. The callback that the user defines will contain the unique identifier of the order monitor that has called the action, and the current state of the order.

See the ApamaDoc for the order state container and OrderState objects for more details on the available actions.