Creating a RET adapter

This page provides guidance on creating an adapter with the Caplin RET Adapter Toolkit.

Contents:

Overview
Requirements
Create a development project
Configure the adapter’s connection to RET
Setting hostnames for Liberator and Transformer
Export Platform Configuration
Test the adapter
Extend the adapter

Overview

The RET Adapter Toolkit is a framework for creating a suite of adapters that connect to a Refinitiv Electronic Trading backend.

The toolkit supports six types of adapter:

Calendar Adapter
LBN Adapter
Orders Adapter
Permissions Adapter
Pricing Adapter
Trading Adapter

In this guide we will take an in depth look at the Calendar Adapter, and we will cover techniques that can be used in the development of all RET adapters.

Requirements

Prerequisites:

Caplin Deployment Framework (see Installing the Deployment Framework)
Caplin Integration Suite (CIS) 6.2

Files required:

RETAdapterToolkit.zip
RET software libraries: trapi-lib , trapi-rates-plugin

Create a development project

In this section we will create a project based on the CalendarAdapter example packaged with the RET Adapter Toolkit.

Follow the steps below:

Copy the RET Adapter Toolkit’s examples/CalendarAdapter directory to the directory you store your software projects in. For example:
```
$ cp -r ~/RETAdapterToolkit-3.5-3.6.0-6297-3f7c28752/examples/CalendarAdapter ~/src
```

Copy the software libraries in your toolkit’s lib and lib/third-party directories to your project’s Blade/DataSource/lib directory:

$ cp ~/RETAdapterToolkit-3.5-3.6.0-6297-3f7c28752/lib/*.jar ~/src/CalendarAdapter/Blade/DataSource/lib
$ cp ~/RETAdapterToolkit-3.5-3.6.0-6297-3f7c28752/lib/third-party/*.jar ~/src/CalendarAdapter/Blade/DataSource/lib

Copy the Refinitiv software libraries trapi-lib and trapi-rates-plugin to the ~/src/CalendarAdapter/Blade/DataSource/lib directory
Copy your TrAPI licence to the directory ~/src/CalendarAdapter/Blade/DataSource/etc directory.

Configure the adapter’s connection to RET

Open the file ~/src/CalendarAdapter/Blade/overrides/CalendarAdapter/etc/trapi-connection.properties and set the host and port of your SCS Relay, and the username and password of the RET account the adapter should use.

~/src/CalendarAdapter/Blade/overrides/CalendarAdapter/etc/trapi-connection.properties

# See toolkit/documentation/templates/trapi-connection.properties-template
# for a full set of properties
[common]
host=<SCS Relay hostname>
port=<SCS Relay port>
reconnection_exponential_initial_interval=5
reconnection_exponential_max_interval=600

[CalendarConnection]
username=<admin username>
password=<admin password>

If you don’t have access during development to a working RET backend, then you can use a mock version of RET by adding user_mocks=true to the [common] section of the adapter’s trapi-connection.properties file:

~/src/CalendarAdapter/Blade/overrides/CalendarAdapter/etc/trapi-connection.properties

# See toolkit/documentation/templates/trapi-connection.properties-template
# for a full set of properties
[common]
host=<SCS Relay hostname>
port=<SCS Relay port>
reconnection_exponential_initial_interval=5
reconnection_exponential_max_interval=600
user_mocks=true

[CalendarConnection]
username=<admin username>
password=<admin password>

Setting hostnames for Liberator and Transformer

If your development installations of Liberator and Transformer are not running on your development machine (localhost), edit the file ~/src/CalendarAdapter/global_config/hosts-defns.conf and change their hostnames:

hosts-defns.conf

define LIBERATOR_PRIMARY_HOST                 localhost
define TRANSFORMER_PRIMARY_HOST               localhost
define LIBERATOR_SECONDARY_HOST               localhost
define TRANSFORMER_SECONDARY_HOST             localhost

The file hosts-defns.conf is used to generate the file hosts.conf, which resides in the same location. If hosts.conf is missing or empty, it may be the source of connection issues on your development machine. This will not be a problem in deployments that use the Deployment Framework.

Export Platform Configuration

The adapter includes configuration required by Liberator and Transformer to work with your adapter. This is installed automatically when the adapter is deployed as a kit to a Deployment Framework, but during development you must copy this configuration to your Deployment Framework manually.

Follow the steps below:

Run the CIS 6.2 toolkit command below to export your adapter’s configuration files as a configuration blade:

$ java -jar <cis-toolkit-jar> export CalendarAdapter --config-only

You can make running CIS toolkit commands easier by creating a Bash alias. For example, if have unzipped the CIS 6.2.8 to your home directory, then add the following line to your ~/.bashrc file to create a new alias, cis:

alias cis="java -jar ~/CaplinIntegrationSuite-6.2.8-309958/tools/cis-blade-toolkit-6.2.8-309958.jar"

Exporting your CalendarAdapter’s configuration can then be done with the much simpler command line:

$ cis export CalendarAdapter --config-only

Copy the configuration blade’s installation kit to your Deployment Framework’s kits directory and run the command below from the root directory of the Deployment Framework:
```
$ dfw deploy
```

Test the adapter

Run the command below to build and start the adapter:

$ java -jar <cis-toolkit-jar> run CalendarAdapter -m com.caplin.example.ret.CalendarAdapterExample

If the adapter runs successfully, press Ctrl+C to stop the adapter.

If you have trouble running the adapter, follow the troubleshooting steps below:

Use the Liberator status page (http://<liberator-host>:<http-port>/status) to determine whether the adapter is up or down.
Check the console output. Unrecoverable exceptions are displayed here.
Check the adapter logs in ~src/CalendarAdapter/Blade/DataSource/var/, in particular the all-calendar-adapter.log (you can find an all-<adapter_name>.log). Any working adapter should log the message Set status to <UP>. If the adapter status is <DOWN> or no message has been logged, this means the adapter is not ready to receive requests. This could be the result of an error, or the adapter may be initialising. An examination of the log will reveal the cause of the problem. Some common problems are:
- The connection to RET failed
- Network errors or unavailability
- TrAPI license is not valid

All these issues raise exceptions that are written to the adapter’s log files.

Extend the adapter

Now we will extend the Calendar Adapter. Extension points are a key concept in RET Adapter development.

Extension points are adapter features which can be overridden by custom code that is loaded via a Configuration class. Each extension point is defined by an interface that determines the behaviour of a particular feature.

Implement an extension point

One of the extension points for a calendar adapter is a data transformation interface: CalendarDataTransformer.

The RET-AD system responds to requests for settlement and tenor dates with a set of ISO 8601 formatted dates. The example Calendar adapter in the RET Adapter Toolkit includes an implementation of CalendarDataTransformer, ExampleDataTransformer, that demonstrates how to reformat settlement dates to a custom format (yy-D):

ExampleDataTransformer.java

public class ExampleDataTransformer implements CalendarDataTransformer
{
  private static final SimpleDateFormat ISO_FORMAT = new SimpleDateFormat("yyyyMMdd");
  private static final SimpleDateFormat CUSTOM_FORMAT = new SimpleDateFormat("yy-D");

  @Override
  public Set<String> onSettlementDatesReceived(
      final String currencyPair,
      final String year,
      final String month,
      final Set<String> settlementDates)
  {
    final Set<String> modifiedSettlementDates = new HashSet<>();
    for (final String date : settlementDates) {
      try {
        final Date retDate = ISO_FORMAT.parse(date);
        final String customDate = CUSTOM_FORMAT.format(retDate);
        modifiedSettlementDates.add(customDate);
      }
      catch (final ParseException ignored) {

      }
    }
    return modifiedSettlementDates;
  }

  @Override
  public Map<Tenor, String> onTenorDatesReceived(
      final String currencyPair,
      final Map<Tenor, String> tenorDates)
  {
    return tenorDates;
  }
}

The CalendarAdapter class’s constructor registers an instance of ExampleDataTransformer with the CalendarConfigurationBuilder instance:

CalendarConfiguration calendarConfiguration =
  CalendarConfiguration.newConfigurationBuilder()
    .setUserManager(new FileBasedUserManager())
    .setDataTransformer(new ExampleDataTransformer())
    .build();

Some extension points have default implementations that are used if you do not specify your own custom implementation. The source code for the default implementations are packaged with the RET Adapter Toolkit under the src directory and can prove a useful starting point when writing your own implementations.

Test the extension

A simple way to test the effect of the ExampleDataTransformer class is to request a /CALENDAR/TENORDATES/<currency-pair> subject using Liberator Explorer:

Using a browser, navigate to the Liberator Explorer address (http://<liberator-host>:<http-port>/diagnostics/liberatorexplorer).
In the record field, enter the subject /CALENDAR/TENORDATES/<currency-pair> where <currency-pair> is any permitted currency pair for your user. You should receive a response with your custom formatted data in the Tenor field.

The subject /CALENDAR/TENORDATES is configured in the file <workspace>/CalendarAdapter/Blade/overrides/CalendarAdapter/Liberator/etc/rttpd.conf