Create a RET Adapter

This page will guide you on creating your own RET Adapter Suite. In this guide, you will be shown how to create a Calendar Adapter.

Adapter Tutorial

The RET Adapter Suite is a set of integration adapters that supply data from RET-AD to the Caplin Platform. There are six points where integration occurs:

  1. Calendar Adapter
  2. LBN Adapter
  3. Orders Adapter
  4. Permissions Adapter
  5. Pricing Adapter
  6. Trading Adapter

The role of each adapter is to respond to outgoing requests from the Platform on their related subjects. In this guide we will take an in depth look at the Calendar Adapter, and we will cover techniques which can be used in the development of all RET adapters.

Objectives

  • Create a Calendar Adapter
  • Configure and connect the adapter to TrAPI
  • Create an extension which will modify tenor dates
  • Make and view subject requests

What you will need...

Prerequisites:

Files required:

  • RETAdapterToolkit.zip
  • RET Libraries: trapi-lib / trapi-rates-plugin

You are now going to set up a development environment by preparing a workspace and tools.

Create a Workspace

The first step is to create a blade which includes the necessary RET config; for simplicity we can copy one of the examples from the RET Adapter Toolkit to use as a starting point. Go to the CalendarAdapter in <RETAdapterToolkit>/examples/CalendarAdapter/. You can create a copy of the file if you wish.

Before we can compile the existing blade, we require a few libraries. These can be found in <RETAdapterToolkit>/lib/. Copy the contents of this directory into the existing lib/ directory in the CalendarAdapter workspace <workspace>/CalendarAdapter/Blade/DataSource/lib/.

Important notes

  1. You should choose either lib/3_4 or lib/3_5. This will depend on the version of TrAPI your adapters will be connecting to.
  2. You may have a number of .jar files that are not supplied by Caplin; you will need trapi-lib and trapi-rates-plugin - these are TrAPI libraries which the adapters depend upon. They should also be copied into the lib/ directory.
  3. You can satisfy dependency requirements using a tool such as ant or maven however in this tutorial we will be using the Caplin Integration Suite blade tool - so by convention, dependencies are kept in the lib/ directory.

Let's begin!

To compile the adapter code, we will use the CaplinIntegrationSuite blade tool's build command. The blade tool is available from the Caplin Integration Suite. The adapter must be configured to connect to TrAPI and to the Caplin Platform.

Connecting to TrAPI

Modifying the configuration

Open the file <workspace>/CalendarAdapter/etc/trapi-connection.properties and update the following values:

host=host_name

The above should be set to the hostname of your SCS relay.

port=1234

The above should be set to the port number of your SCS relay.

username=calendar_user
password=abcd

The above needs to be an existing RET username and password. TrAPI requires a valid license to use. Copy your license file to <workspace>/CalendarAdapter/etc/trapi.lic

Note: It's possible (and often simpler) to connect to the mock version of TrAPI built into the Caplin RET Adapter Suite. This requires only a configuration change for each adapter. Open the file <workspace>/CalendarAdapter/etc/trapi-connection.properties and add the following:

use_mocks=true

Connecting to Caplin Platform

Open the file <workspace>/CalendarAdapter/global_config/hosts-defns.conf and set the name of each host to the correct location for your Caplin Platform deployment. The default is localhost.

Note: hosts-defns.conf` is used to generate the file hosts.conf which resides in the same location. If you use the blade tool, this will be generated automatically. 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

Finally, export the configuration and deploy it in your Deployment Framework:

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

followed by:

dfw deploy <path-to-exported-configuration>

This will configure the Deployment Framework to send requests for calendar data to your adapter.

Do a Test Run

Using the CaplinIntegrationSuite blade tool's run command:

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

You can use the steps above to confirm that the adapter is working. Finally use <CTRL+ C> to stop the adapter.

Note: If at any point you have trouble running the adapter, the following debugging steps can be helpful:

  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 will be displayed here.
  3. Check the adapter logs in <workspace>/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:
    • Connection to TrAPI failed
    • The network is not available
    • TrAPI license is not valid - these issues can be identified by the exceptions that are logged.

Create an Extension

Now we will extend the Calendar Adapter to add custom behaviour. 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 which determines the behaviour of that particular feature.

Extending the Calendar

The RET-AD system responds to requests for settlement and tenor dates with a set of ISO 8601 formatted dates. The CalendarDataTransformer extension allows us to make changes to these dates in more or less any way we like, but it is particularly useful for altering the data format which will be sent to the client.

In the following example we will make a small change to the format of tenor dates:

  1. Open the file src/main/java/com/caplin/example/ret/ExampleDataTransformer.java

  2. We are going to transform the date String values in the Tenor String map, tenorDates. Instead of an ISO 8601 date, we will provide dates in year, day-of-year format. To do this, update the onTenorDatesReceived()method; the following code can be used to transform the map:

    @Override
    public Map<Tenor, String> onTenorDatesReceived(String currencyPair, Map<Tenor, String> tenorDates)
    {
        for (Map.Entry<Tenor, String> date : tenorDates.entrySet()) {
            try {
                Date retDate = ISO_FORMAT.parse(date.getValue());
                date.setValue(CUSTOM_FORMAT.format(retDate));
            } catch (ParseException ignored) {}
        }
        return tenorDates;
    }
    
  3. Save the file

  4. Rebuild the adapter:

    java -jar <cis-blade-toolkit> build CalendarAdapter
  5. Run the adapter:

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

The adapter is ready to receive a request!

Each adapter is configured in exactly the same way: a builder, named CalendarConfigurationBuilder in this case, is created by calling the newConfigurationBuilder() method on CalendarConfiguration and extensions are added via methods on this interface. Once all extensions have been set, we call build() on the builder to create a CalendarConfiguration object. Every extension point has a default implementation, so a CalendarAdapterExample which had the following in its main method:

new CalendarAdapter().start()

Would run according to default behaviour. The CalendarConfiguration should be passed as an argument to the CalendarAdapter constructor if defaults have been overridden. When start() is called the adapter will be initialised, and all of the extensions as well as any defaults will be created.

Note: The source code of the default extensions is available in <RETAdapterToolkit>/src/, and may be a useful starting-point for development.

Making and Receiving Requests

A simple way to test the adapter is to make a request via the Liberator Explorer, however sending a request may require a change to permissions. Assuming a default Deployment Framework setup, logging into Liberator Explorer as admin, you can make the following changes:

  1. Open the file logins.xml in the Permissioning Adapter and add the group Global to the admin users's set of groups. It should be similar to the following:

    <admins>
        <user ssoName="admin" password="admin" groups="Global LiberatorStatus" />
    </admins>
    
  2. Restart the Permissioning Adapter and Liberator.

  3. Using a browser, navigate to the Liberator Explorer address (http://<liberator-host>:<http-port>/diagnostics/liberatorexplorer). In the record input, 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.

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