Hello world: creating an order trade

The Trading Library provides a simple state based communication mechanism for sending trades to a corresponding server component. The XML state model definition provides a protocol outlining the states and transitions that both the frontend and backend must adhere to, reducing boilerplate error management code. In this example we will demonstrate the basic concepts of the Trading Library by creating a workflow for the submission of an Order trade. This will include defining our state model, trade submission and simple event management.

Configuring the model

Firstly, we’ll start by defining our XML state model for an Order trade. The model will outline a workflow for submitting an order and receiving an event that will indicate that the order submission was successful.

<?xml version="1.0" encoding="UTF-8" ?>
<tradeModels>
    <tradeModel name="Order" initialState="Initial">
        <state name="Initial">
            <transition target="Submitted" trigger="Submit" source="client"/>
        </state>
        <state name="Submitted">
            <transition target="OrderReceived" trigger="Received" source="server"/>
        </state>
        <state name="OrderReceived" />
    </tradeModel>
</tradeModels>

We can see that our model has 3 states; Initial, Submitted and a final state of OrderReceived. We’ve also defined 2 transitions on Initial and Submitted, with a trigger of Submit and Received respectively. The trigger will be used to fire a state change into a particular state. Since the submission occurs on the client, we’ve defined the source of the Submit trigger as "client". In contrast, we expect the Received trigger to be fired from the server. Assuming that the XML has been located in the resources/xml folder of an aspect, bladeset or blade, we can expect that it will be loaded automatically for us.

Sending the Trade

Now that we’ve got our model defined, we can create a trade object with some fields that we wish to send to the server.

var mTradeFields = {
"AssetClass": "FX",
"TradingProtocol": "Order",
"InstrumentName": "/FX/GBPUSD",
"Price": "1.123"
};

var oTradeService = caplin.core.ServiceRegistry.getService("caplin.trade-service");
var oTrade = oTradeService.createNewTrade(mTradeFields);
oTrade.processClientEvent("Submit");

Here we’ve invoked a method processClientEvent() on the trade object, specifying the trigger Submit which corresponds to the transition defined in our trade model. This will cause the trade to be submitted to the server, which will be supplied with the fields defined in mTradeFields. Note that the setup of the TradeService will be covered in another tutorial.

Receiving Server Events

Once the server has deemed the submission successful, it will respond by sending an event with a trigger of Received. To listen to this event, we can add ourselves as a listener to the trade with the following invocation:

oTrade.addStateChangedListener(this);

Once the server has sent the Received event, the stateChanged() method will be invoked which will allow us to respond to the user with an appropriate message.

Order.prototype.stateChanged = function(oState, sTrigger)
{
    if (sTrigger == "Received")
    {
        alert("Order " + oTrade.getTradeID() + " successfully submitted.");
    }
};

You’ll also find it easy to use the Trading Library with Presenter given their tight integration. Automatic binding of trade fields to presenter properties makes UI update painless, whist state change events can be bound to property listeners allowing for a unified presentation model.