Programming Guide

Introduction

OnixS CME Straight Through Processing Handler allows clients to connect to CME for retrieval of FIXML messages containing NYMEX, COMEX, Gulf Mercantile Exchange (GME), CBOT via CMD, CME cleared trades, CME Globex, BrokerTec Direct, EBS, CME cleared trades and registered external deals information.

Services

  • Easy-to-use API.
  • Manages the session layer (for the delivery of application messages).
  • Manages the application layer (defines business-related data content).
  • Creates (outgoing) Request messages.
  • Parses (incoming) Reports messages.
  • Flexible logging.

Note: We recommend reading the “CME STP API” alongside this guide. Additionally, reviewing the source code of the sample project included in the library distributive package is advised.

System Requirements

  • JDK 1.8 (or higher).

Getting Started

All handler classes are located in the biz.onixs.cme.stp.handler package.

The typical way of using the handler is as follows:

  1. Create the biz.onixs.cme.stp.handler.Session object and set corresponding settings.
  2. Requesting reports using biz.onixs.cme.stp.handler.TradeCaptureReportRequest with biz.onixs.cme.stp.handler.SubscriptionRequestType Snapshot(0) (query) Subscription(1).
  3. Receiving and processing reports with implementation of
biz.onixs.cme.stp.handler.MessageListener
  1. Disconnect the session.

Example

29
30
31
32
33
34
35
36
37
38
final String url = "https://servicesnr.cmegroup.com/cmestp/query";
final String senderCompId = "SenderCompId";
final String senderSubId = "SenderSubId";
final String password = "Password";
Session.setLicenseDirectory("d:\\licenses");
try {
    final Session session = new Session(new URL(url), senderCompId, senderSubId, password);
} catch (LicenseException | MalformedURLException e) {
    throw new RuntimeException(e);
}

Check also following chapters:

  1. Error Reporting
  2. Licensing

Working With Handler

The main class for working with Handler is biz.onixs.cme.stp.handler.Session.

To create a Session object, four parameters (obtained from CME) are required:

  • CME Straight Through Processing Service URI
  • SenderCompID - Identifies the customer firm sending a message.
  • SenderSubID - The user ID assigned to the sender (must be in uppercase).
  • Password - CME assigned password.

Example

35
36
37
38
39
40
41
try {
    final Session session = new Session(new URL(url), senderCompId, senderSubId, password);
    session.subscribe();
    session.close();
} catch (InterruptedException | MalformedURLException | LicenseException e) {
    throw new RuntimeException(e);
}

Application Level

There are two ways to receive biz.onixs.cme.stp.handler.TradeCaptureReport messages:

  • Query for historical data.
  • Subscription for real-time data.

Both methods can be used with or without filters, which are defined using the

biz.onixs.cme.stp.handler.TradeCaptureReportRequest message.

Note: Relationship between filters is “AND”.

Example Filtering

The following example filters for NYMEX Crude Oil futures only:

Example

27
28
29
30
31
32
public static void main(final String[] args) {
    TradeCaptureReportRequest req = new TradeCaptureReportRequest();
    req.getInstrument().setSecurityID("CL");
    req.getInstrument().setSecurityType(SecurityType.Future);
    req.getInstrument().setSecurityExchange("NYMEX");
}

Subscription

Understanding Message Sequencing

For real-time data retrieval:

Use

for unfiltered data.

Use

for filtered data.

Handler automatically renews subscription requests every 3 seconds (this interval is configurable).

Query

For historical data retrieval, use

biz.onixs.cme.stp.handler.Session.query(TradeCaptureReportRequest).

Example

The following example requests historical data filtering for CME product “EC”:

38
39
40
41
42
43
44
45
46
47
48
49
Session session = new Session(new URL(url), senderCompId, senderSubId, password);
session.registerErrorListener(this);
session.registerMessageListener(this);
session.registerFixmlMessageListener(this);
  
TradeCaptureReportRequest req = new TradeCaptureReportRequest();
req.setStartTime(ZonedDateTime.parse("2025-02-22"));
req.setEndTime(ZonedDateTime.parse("2025-02-28"));
req.getInstrument().setSecurityID("EC");
req.getInstrument().setSecurityExchange("CME");
  
session.query(req);

Controlling Handler Logging

Controlling Handler Logging

By default, the handler logs all important aspects of its activity while working. The SLF4J(Simple Logging Facade for Java) is used by Handler internally. The SLF4J detects and uses the concrete logging implementation configured by the user. By default, the Logback logging implementation is recommended.

Please see Logging section for more details.

The logging configuration should be set up at the start of the application. Example Logback configuration:

<logger name="biz.onixs.cme.stp.handler.samples" level="DEBUG"/>
<logger name="biz.onixs.cme.stp.handler" level="INFO"/>

Error Reporting

An exception is used as a fundamental error-reporting mechanism. In the event of any error the biz.onixs.cme.stp.handler.ErrorListener is triggered once exception is thrown while processing inbound/outbound messages.

Licensing

The handler requires a valid license key file for its execution. If there is no license file available or the handler is not able to locate it, the

biz.onixs.cme.stp.handler.LicenseException exception will be thrown.

The pre-defined license file name is “OnixS.lic”. The license file is loaded during handler initialization as described in the Unified Resource Loading.

The default license file name can be changed using LicenseFile parameter in the

biz.onixs.cme.stp.handler.Session.setLicenseFile(String) method.

The following table explains different options to keep the license file.

License File Location License File Name LicenseFile Property Note
application classpath OnixS.lic no change required
current directory *.lic no change required Any file with the “.lic” extension in the current directory is checked automatically.
user home directory *.lic no change required Any file with the “.lic” extension in the user home is checked automatically.
application classpath AltName.ext AltName.ext
absolute path “/foo/bar” AltName.ext /foo/bar/AltName.ext
relative path “foo/bar” AltName.ext foo/bar/AltName.ext

Unified Resource Loading

By default, any external resource is looked for at the following places and in the following order (if other is not set explicitly):

  1. Classpath
  2. Absolute file path
  3. Current directory
  4. User home directory

If it can’t be found at the 1st location then the 2nd one is checked, etc.

Events and Listeners

The events and their listeners of the biz.onixs.cme.stp.handler.Session class are listed below:

Example

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
public void run(final String[] args) {
    TradeCaptureReportRequest req = new TradeCaptureReportRequest();
    req.getInstrument().setSecurityID("CL");
    req.getInstrument().setSecurityType(SecurityType.Future);
    req.getInstrument().setSecurityExchange("NYMEX");
    try {
        Session session = new Session(new URL(url), senderCompId, senderSubId, password);
        session.registerErrorListener(this);
        session.registerMessageListener(this);
        session.registerFixmlMessageListener(this);
  
    } catch (LicenseException e) {
        throw new RuntimeException(e);
    } catch (MalformedURLException e) {
        throw new RuntimeException(e);
    }
}
  
@Override
public void onError(ErrorEventArgs args) {
    LOG.error("Error: {}", args.toString());
}
  
@Override
public void onMessageSent(FixmlMessageEventArgs args) {
    LOG.info("FIXML message sent: {}", args.getFixmlMessage());
}
  
@Override
public void onMessageReceived(FixmlMessageEventArgs args) {
    LOG.info("FIXML message received: {}", args.getFixmlMessage());
}
  
@Override
public void onTradeCaptureReportRequestSent(TradeCaptureReportRequestEventArgs args) {
    LOG.info("TradeCaptureReportRequest sent with ID = {}", args.getTradeCaptureReportRequest().getTradeRequestID());
}
  
@Override
public void onTradeCaptureReportRequestAcknowledgmentReceived(TradeCaptureReportRequestAcknowledgmentEventArgs args) {
    LOG.info("TradeCaptureReportRequestAck received for ID = {}", args.getTradeCaptureReportRequestAcknowledgment().getTradeRequestID());
}
  
@Override
public void onTradeCaptureReportReceived(TradeCaptureReportEventArgs args) {
    LOG.info("TradeCaptureReport received with ID = {}", args.getTradeCaptureReport().getTradeReportID());
}
  
@Override
public void onCollateralReportReceived(CollateralReportEventArgs args) {
    LOG.info("CollateralReport received for SecurityID = {}", args.getCollateralReport().getInstrument().getSecurityID());
}
  
@Override
public void onEndOfQuery(TradeCaptureReportRequestEventArgs args) {
    LOG.info("Last report received for the query with ID = {}", args.getTradeCaptureReportRequest().getTradeRequestID());
}

Support

OnixS provides online support resources to customers and development partners.

Jira

Jira is an issue logging and tracking system with release version control, records of issues/fixes and enhancements, and access to useful resource and FAQ information.

Email

We recommend using Jira for issue logging/tracking. Registration requests for Jira access and technical support are also available via email at support@onixs.biz.