Creating a RET 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:

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:

  1. 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
  2. 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
  3. Copy the Refinitiv software libraries trapi-lib and trapi-rates-plugin to the ~/src/CalendarAdapter/Blade/DataSource/lib directory

  4. 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:

  1. 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
  2. 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:

  1. Use the Liberator status page (http://<liberator-host>:<http-port>/status) to determine whether the adapter is up or down.

  2. Check the console output. Unrecoverable exceptions are displayed here.

  3. 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:

  1. Using a browser, navigate to the Liberator Explorer address (http://<liberator-host>:<http-port>/diagnostics/liberatorexplorer).

  2. 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