Package com.caplin.trading

The Caplin Trading Integration API provides Java classes and interfaces that allow you to create Trading Adapters.

See: Description

Package com.caplin.trading Description

The Caplin Trading Integration API provides Java classes and interfaces that allow you to create Trading Adapters.

A Trading Adapter sits between Caplin Liberator and an external trading system, handling the trade messages that flow between Caplin Platform client applications and the trading system when an end-user trades.

The Trading Integration API is built on top of the Caplin DataSource for Java API (package com.caplin.datasource and its subpackages). It allows Trading Adapters to communicate with Liberator using the DataSource protocol, but without the need to write code at the DataSource API level.

In this API documentation, a Trading Adaptor is sometimes referred to as a Trading DataSource application, or Trading DataSource, for convenience.

For additional information about how to use this API, see the document Trading 6.0: Integrating The Caplin Platform With A Trading System.

Note: Previous versions of this API were called the Caplin Xaqua Trading DataSource API.

SDK Contents

The Caplin Trading Integration API is part of the Caplin Integration Suite Software Development Kit (SDK) and contains the following components:

About the Trading Integration API

Follow the links below for information about the Trading Integration API:

What's new in Caplin Trading Integration API for Java 6.0

The following changes have been made with respect to the previous versions of this API (previously called "Caplin Xaqua Trading DataSource API").

Upgrading to Trading Integration API for Java 6.0

Migrating existing Trading DataSource applications to use Trading Integration API for Java 6.0

The way in which you construct the main Trading Adapter objects has changed in the Trading Integration API for Java 6.0. The following examples illustrate the differences with respect to the equivalent code that uses the Trading DataSource 4.x API.

Construction using Trading DataSource for Java 4.x

public class MyTradingApp implements TradingApplicationListener
{
   static void main(String[] args)
   {
      new MyTradingApp();
   }

   MyTradingApp()
   {
      // Create a factory object for generating the trading state machines.
      StateMachineFactory myTradingStateMachineFactory = new StateMachineFactory();

      // Load the required Trade Models into the factory.

      myTradingStateMachineFactory.loadModels(new File("conf/MyESPStateModel.xml"));
      myTradingStateMachineFactory.loadModels(new File("conf/MyRFSStateModel.xml"));

      // Define the patterns for determining the subjects of Trade objects 
      // that represent messages on Trade Channels, messages on Blotter Channels,
      // and Blotter Items.

      Properties subjectProperties = new Properties();
      subjectProperties.setProperty("tradechannel.patterns", 
                                    "/PRIVATE/%U/TRADE/");
      subjectProperties.setProperty("blotterchannel.patterns", 
                                    "/PRIVATE/%U/TRADEBLOTTER/%1");
      subjectProperties.setProperty("blotteritem.pattern", 
                                    "/TRADE/%U/BLOTTER/%1");

      // Create a DataSource to manage the communication with 
      // other DataSources, such as Caplin Liberator,
      // and hence client applications.

      DataSource dataSource = new DataSource(<dataSourceConfiguration>>, 
                                             <fieldsConfiguration>);

      // Create the Trading DataSource.
      // TradingDataSource implements the standard DataSource callbacks,
      // which allow you to use the Trading API to communicate with 
      // clients in the form of trade messages. 

      tradingDataSource = new TradingDataSource
                          (this,      //Reference to this TradingApplicationListener
                           dataSource,
                           myTradingStateMachineFactory,
                           subjectProperties);

      // Once the TradingDataSource has been created
      // it has to be started explicitly.
      tradingDataSource.start();
   }

   // ...

Construction using Trading Integration for Java 6.0

The main differences with respect to the construction code for Trading DataSource 4.x are highlighted. 

public class MyTradingApp implements TradingApplicationListener
{

   static void main(String[] args) throws Exception
   {

      // Create an argument array. In practice, these arguments 
      // would typically be command line arguments.
      String[] args = new String[3];
      args[0] = "--config-file=conf/datasource.conf"; // DataSource configuration
      args[1] = "--fields-file=conf/fields.conf";     // DataSource message field defs

      new MyTradingApp(args);
   }

   MyTradingApp(String[] arguments) throws Exception
   {
      // Create a DataSource to manage the communication with 
      // other DataSources, such as Caplin Liberator,
      // and hence with client applications.
      DataSource dataSource = DataSourceFactory.createDataSource(arguments);

      // Create a TradingProvider
      // This allows you to use the Trading Integration API to communicate
      // with clients by means of trade messages.
      TradingProvider tradingProvider = new TradingProvider
                       (this,        // Reference to this TradingApplicationListener
                        dataSource); // The DataSource that this TradingProvider uses
      // Once the TradingProvider has been created
      // the DataSource has to be started explicitly.

      dataSource.start();
   }

   // ...
}

You create an instance of TradingProvider, which replaces the TradingDataSource of the Trading DataSource 4.x API.

You no longer need to create a factory object for generating the trading state machines and then explicitly load the required Trade Models into the factory. The required state machines are now specified in a configuration file. The configuration file also contains patterns for determining the subjects of Trade objects that represent messages (Trade Channels messages, Blotter Channel messages, and Blotter Item messages).

The configuration file is specified as a command option (either --config-file or --trading-property-file) supplied to the created DataSource object. The internal code of the Trading Integration library can subsequently access these options as required.

For a detailed description of these options and an example of the typical contents of a configuration file, see Configuration Options.

Compatability Issues

DataSource Version

Trading Integration API 6.0 is not compatible with versions prior to version 6.0.1 of DataSource for Java.

JVM Versions

Versions of the Trading Integration API prior to 6.0 required a minimum JVM version of 1.5. Due to Trading Integration API 6.0 now utilizing DataSource 6.0, the minimum JVM version required is 1.6.

Configuration Options

The TradingProvider instance is configured either from a DataSource configuration file (eg datasource.conf) or a Java properties file which is specified as an additional command option (--trading-property-file) supplied to the created DataSource object. Values in DataSource configuration are given precedence over the properties file in case of duplication.

The configuration options specify:

Option definitions

Options can either be defined in DataSource configuration or a properties file using the option names given below

DataSource Configuration Name Property Name Default Value Required? Description
blotterchannel-patterns blotterchannel.patterns "/TRADEBLOTTER/" No

Allows the Trading Adapter to determine which Trade objects are requests to open (create) Blotter Channels.

For more information on how to specify this property, see "Configuring Trade subjects" in the document Trading 6.0: Integrating The Caplin Platform With A Trading System.

blotteritem-pattern blotteritem.pattern "/BLOTTERITEM" No

Defines how the Trading Adapter must construct a blotter item subject on the completion of a Trade.

For more information on how to specify this property, see "Configuring Trade subjects" in the document Trading 6.0: Integrating The Caplin Platform With A Trading System.

tradechannel-patterns tradechannel.patterns "/TRADE/,/FT/TRADE/" No

Allows the Trading Adapter to determine which Trade objects belong to which Trade Channels. For example if the pattern is set to "/PRIVATE/%U/TRADE", when a request comes in for the subject "/PRIVATE/john-0/TRADE", this subject will match the pattern.

For more information on how to specify this property, see "Configuring Trade subjects" in the document Trading 6.0: Integrating The Caplin Platform With A Trading System.

trading-audit-logger-pattern trading.audit.logger.pattern "logs/audit-%u.log" No

The pattern that defines the location and name of the audit log.

The pattern can include the %u token. This is a unique number that is automatically generated upon log file roll over in order to prevent filename conflicts (as defined by the java.util.logging.FileHandler class).

trading-models trading.models (none) Yes

Defines the names and locations of the Trade Model configuration XML files. If there is more than one Trade Model, and hence more than one file, separate the file names with commas. For example: trading.models=conf/MyESPStateModel.xml,conf/MyRFSStateModel.xml

For more information about Trade Models, see Trade Model Configuration. The format of the Trade Model XML is defined in the document Caplin Trading: Trade Model Configuration XML Reference.

use-generic-message use.generic.message false No

Toggles use of the generic message type for trade messages. Generic messages simplify configuration as they do not require a fields.conf file to be maintained.

Configuration example

The following options can be specified in datasource.conf

[... General Adapter Configuration ...]

# XML configuration files defining trade models used by the Trading Adapter.
trading-models                  conf/MyESPStateModel.xml,conf/MyRFSStateModel.xml

# Define subject patterns for TradeChannels, BlotterChannels, and BlotterItems.
tradechannel-patterns           /PRIVATE/%U/TRADE/
blotterchannel-patterns         /PRIVATE/%U/TRADEBLOTTER/%1
blotteritem-pattern             /TRADE/%U/BLOTTER/%1

# Define the pattern for the audit log filename and location.
trading-audit-logger-pattern    myLogsDirectory/audit-%u.log

Properties example

Here is an example of a complete properties file:

#  Specify the XML configuration files defining
#  the trade models to be used by the Trading Adapter.
trading.models=conf/MyESPStateModel.xml,conf/MyRFSStateModel.xml

# Define subject patterns for TradeChannels,
# BlotterChannels, and BlotterItems.
tradechannel.patterns=/PRIVATE/%U/TRADE/
blotterchannel.patterns=/PRIVATE/%U/TRADEBLOTTER/%1
blotteritem.pattern=/TRADE/%U/BLOTTER/%1

# Define the pattern for the audit log filename and location.
trading.audit.logger.pattern=myLogsDirectory/audit-%u.log

Trade Model Configuration

CreatingTrade Model configuration XML files

You must create a configuration XML file that represents the Trade Model to be used. If your Trading Adapter uses more than one Trade Model, create a separate XML file for each model.

An example of an ESP trade model is shown below. The conf directory of the kit contains further examples of trade models that are used with Caplin Trader. 

<?xml version="1.0" encoding="UTF-8" ?>
<tradeModels>
   <tradeModel name="ESP" initialState="Initial">
      <state name="Initial">
         <transition target="OpenSent" trigger="Open" source="client"/>
      </state>
      <state name="Timeout"/>
      <state name="OpenSent" timeout="10" timeoutState="Timeout">
         <transition target="Opened" trigger="OpenAck" source="server"/>
      </state>
      <state name="Opened" timeout="10" timeoutState="Timeout">
         <transition target="TradeConfirmed" trigger="TradeConfirmation" source="server"/>
         <transition target="TradePassed" trigger="Pass" source="server"/>
         <transition target="TradeExpired" trigger="Expired" source="server"/>
      </state>
      <state name="TradeConfirmed"/>
      <state name="TradePassed"/>
      <state name="TradeExpired"/>
   </tradeModel>
</tradeModels>

For more information about Trade Models, see the document Trading 6.0: Integrating The Caplin Platform With A Trading System. The format of the Trade Model XML is defined in Caplin Trading: Trade Model Configuration XML Reference.

Configuring the Trading Adapter

Constructing the Trading Adapter

First you must specify the names and paths of the files that define the DataSource configuration, and the DataSource message fields TradingProvider. 

...
// Create an argument array. In practice these arguments
// would typically be the command line arguments.
String[] args = new String[3];
args[0] = "--config-file=conf/datasource.conf"; // DataSource configuration
args[1] = "--fields-file=conf/fields.conf";     // DataSource message field defs
...

Then create a DataSource object by passing the configuration args to the DataSource constructor. 

...
// Create a DataSource.
DataSource dataSource = DataSourceFactory.createDataSource(args);
...

Create the TradingProvider, passing in a TradingApplicationListener and DataSource.

Then start the DataSource.

Example Trading Adapter

The example package contains a working example showing the integration of the Trading Provider with a simulated Trading System. This example is designed to work out-of-the-box with the Reference Implementation of Caplin Trader.

Below is an example of only the bare essential code needed to implement a Trading Provider. 

import java.io.IOException;
import java.util.logging.Logger;

import org.xml.sax.SAXException;

import com.caplin.datasource.DataSource;
import com.caplin.datasource.DataSourceFactory;
import com.caplin.trading.BlotterChannel;
import com.caplin.trading.TradeChannelListener;
import com.caplin.trading.Trade;
import com.caplin.trading.TradeChannel;
import com.caplin.trading.TradeException;
import com.caplin.trading.TradingApplicationListener;
import com.caplin.trading.TradingProvider;

public class ExampleTradingProvider implements TradingApplicationListener, TradeChannelListener
{
        private static final Logger logger = Logger.getAnonymousLogger();
        
        public ExampleTradingProvider(String[] args) throws IOException, SAXException
        {
                DataSource dataSource = DataSourceFactory.createDataSource(args, logger);
                
                TradingProvider tradingProvider = new TradingProvider(this, dataSource);
                
                dataSource.start();
        }
        
        public static void main(String[] args) throws IOException, SAXException
        {
                new ExampleTradingProvider(args);
        }
        
        /*
        * The following methods allow you to integrate your trading logic with the
        * TradingProvider
        */
        @Override
        public void channelCreated(TradeChannel channel) throws TradeException
        {
                channel.setChannelListener(this);
        }
        
        @Override
        public void channelClosed(TradeChannel channel)
        {
        }
        
        @Override
        public void blotterChannelCreated(BlotterChannel blotterChannel)
        {
        }
        
        @Override
        public void blotterChannelClosed(BlotterChannel blotterChannel)
        {
        }
        
        @Override
        public void peerUp(int peerIndex)
        {
        }
        
        @Override
        public void peerDown(int peerIndex)
        {
        }
        
        @Override
        public void tradeCreated(Trade trade) throws TradeException
        {
        }
        
        @Override
        public void tradeClosed(Trade trade)
        {
        }
        
}

Recommended Liberator configuration options

The objects used to represent Trade and Blotter Channels should be configured in the Liberator with some particular settings to ensure that they behave correctly. These options are used to map objects (so that unique channels are created for every user session), to disable throttling (conflation) and to ensure that the objects are discarded immediately following a user un-subscription or logout.

The following settings are applied within add-object sections of the rttpd.conf configuration file:

For example: 

...
#trade channel object map
object-map /FT/TRADE/FX /FT/TRADE/FX/%U

#blotter channel object map
object-map /FT/TRADEHISTORY /FT/TRADEHISTORY/%U
...

#trade channels
add-object
        name    /FT/TRADE
        type    20
        throttle-times 0
        discard-timeout 0
end-object

#blotter channels
add-object
        name    /FT/TRADEHISTORY
        type    20
        throttle-times 0
        discard-timeout 0
end-object
...

For more information on the use of these and other Liberator configuration options, please refer to the Liberator Administration Guide.

Shared Blotters

In a system where multiple trading systems are integrated using multiple TradingProviders (typically, one TradingProvider per trading system), the client application can request one blotter from the Liberator and see all trades from all integrated trading systems in that single blotter. This means that the same client code can handle the blotter regardless of how many TradingProviders provide trading services to the client.

Logging

Application Log

The Trading Adapter uses the DataSource's logger for logging all application messages. For examples of how to set up a logger, see the package com.caplin.datasource.

Audit Log

All trade events sent and received are logged to an audit log file. The location and name of the log file can be defined as a pattern using the option trading-audit-logger-pattern or trading.audit.logger.pattern. For more details, see Configuration Options. 

trading.audit.logger.pattern=myLogsDirectory/audit-%u.log

If an audit logger pattern has not been set within the configuration file, the default pattern is set to logs/audit-%u.log. %u is a unique number that is automatically generated upon log file roll over, in order to prevent file name conflicts (as defined by the java.util.logging.FileHandler class).

For each event sent and received, two log entries are created: one before processing the event, and one when the event has been processed. If the event has been generated by the client, the second log entry is created after the TradeListener.receiveEvent() callback has returned. If the event has been generated by the server, the second log entry is created after the message has been sent.

Note: The audit logging is independent of the standard application logging, which is logged to the named logger as described in Application Log.

Packet Log

All messages received from peers are logged in a packet log file. These messages are stored in a binary format. To render packet logs in a human readable format, the logcat or jlogcat tools should be used. Please refer to the DataSourceJava documentation for more information about packet logging.

Trade Legs and Locking

As creation and deletion of trade legs can occur on both the client and server, it's important to note the possibility that simultaneous operations may occur on the same leg. For example, both the client and server may attempt to delete the same leg. To overcome this, a simple locking mechanism should be implemented so that only the client or server can perform add/remove operations at one time.

This can easily be achieved by implementing a "Lock" transition in your state model, where a transition back to the current state occurs to signify to the other party that it should prevent any operations until an "Unlock" transition occurs.

Please send bug reports and comments to Caplin support