Pricing Integration Adapter (1)

Integration adapters provide the Caplin Platform with data from a bank's backend systems. In this tutorial, you will create and run an integration adapter that provides FX pricing data.

This tutorial assumes that you have already set up the development environment described in Setting up the Development Enviroment.

Objectives

Over the next two tutorials, you will create an adapter that provides FX pricing data to the Caplin Platform. By the end of this tutorial, the adapter will connect to Liberator but not provide any data. In the next tutorial, you will add code to supply FX prices to Liberator.

At the end of this tutorial, you will know how to perform the following tasks:

  • Create an adapter project from a Caplin project template
  • Import the adapter project into your IDE
  • Run the adapter in your IDE
  • Export and deploy your adapter
  • Enable JMX for the adapter.

Create an adapter project from a template

The Caplin Project Templates project in Caplin's GitHub repository provides template projects for pricing adapters, blotter adapters, notification adapters, trading adapters, and Java Transformer modules. Each template contains working code and configuration to get you started.

In this tutorial, you will create a project based on the Pricing Adapter Template. The template includes a working code for a basic pricing adapter. 

To create the project, follow the steps below:

  1. Open a Bash command line
  2. Download the latest version of the Caplin Project Templates project to your home directory:

    wget http://github.com/caplin/project-templates/archive/master.zip
  3. Extract the project:

    unzip master.zip
  4. Create a directory to store this, and future, adapter projects:

    mkdir ~/src
  5. Run the command below to copy the Pricing Adapter Template directory to your src directory and rename it to PricingAdapter:

    cp -r ~/project-templates-master/pricing-template ~/src/PricingAdapter
  6. Edit the file ~/src/PricingAdapter/settings.gradle. Change the value of the variable rootProject.name to 'PricingAdapter':

    rootProject.name = "PricingAdapter"
  7. Manage the project's dependencies:
    1. To configure Gradle to download project dependencies automatically, you need a Caplin account and access to the Caplin repository.

      Edit the file build.gradle, and enter your Caplin account credentials into the block below:

      maven {
          credentials {
              username "user"         //insert your caplin artifactory username here
              password "secret"       //insert your caplin artifactory password here
          }
          url "https://clientartifactory.caplin.com/artifactory/caplin-artifactory-caplin-qa-cache"
      }
      Note: the Caplin repository is planned for release in the second half of 2017.
    2. To download project dependencies manually, you need a Caplin account and access to the Caplin Product Downloads site.

      1. Download the latest Caplin Integration Suite ZIP file from the Caplin Product Downloads site.

      2. Extract the ZIP file to your home directory:

        unzip -qoa ~/CaplinIntegrationSuite-version.zip
      3. Copy the file datasource-java-version-jar-with-dependencies.jar to your adapter project's lib directory:

        cp ~/CaplinIntegrationSuite-version/lib/datasource-java-version-jar-with-dependencies.jar ~/src/PricingAdapter/lib

Import the adapter project into Eclipse

Follow the steps below to import your project into Eclipse:

  1. In Eclipse, click File > Import. The Import dialog opens.
  2. From the Import dialog, click Existing Gradle Project. The Import Gradle Project dialog opens.
  3. Under Project location, deselect Use default location

  4. In the Location field, select your pricing adapter's project directory.

    Tip: if you are following this tutorial on Cygwin, your project directory is C:\cygwin64\home\username\src\PricingAdapter

  5. Click Finish

Run the adapter from within your IDE

Integration adapters are designed to be deployed and run in the context of a Deployment Framework (DFW), not an IDE. To run your adapter within an IDE requires some extra steps, but this will save you time and allow you to use your IDE's debugging tools.

Note: the steps differ depending on whether your adapter runs against components in a local DFW (on your development computer) or components in a remote DFW. This course uses the local DFW that you installed in the previous tutorial. For instructions on how to run your adapter against a remote DFW, see the README.md file in the Pricing Adapter Template.

To run your adapter in your IDE, you perform the following steps:

  1. Export your project as a config-only blade
  2. Deploy the config-only blade to your DFW
  3. Customise how Eclipse runs your adapter

1. Export your project as a config-only blade

A config-only blade contains all of your adapter's files except for its binary files.

Note: blades that contain only configuration files have other uses in the Caplin Platform. Liberator and Transformer use configuration blades for convenient activation and deactivation of built-in features.

To export your project as a config-only blade, follow the steps below:

  1. Open a Bash shell
  2. From the root directory of your project, run the command below to export your adapter's configuration as a configuration blade:

    ./gradlew assemble -PconfigOnly

    The new configuration blade is created under your project's build/distributions directory.

2. Deploy the config-only blade to your DFW

Deploying the config-only blade creates your adapter's directory structure in the DFW, and deploys configuration files required by the adapter, Liberator, and Transformer. The configuration files provide the adapter with details of the component it should connect to, and provide Liberator and Transformer with details of the data served by the adapter.

To deploy your adapter's configuration to your Deployment Framework (DFW), follow the steps below:

  1. From the root directory of your DFW, run the command below to stop all running Platform components:

    ./dfw stop
  2. Copy the blade ~/src/PricingAdapter/build/distributions/PricingAdapter-version.zip to your DFW's kits directory:

    cp ~/src/build/distribution/PricingAdapter-version.zip ~/DeploymentFramework-version/kits
  3. From the root directory of your DFW, run the command below to deploy your blade:

    ./dfw deploy
  4. From the root directory of your DFW, run the command below to start all Platform components:

    ./dfw start
Note: any time you change the configuration of your adapter during development, you must re-export and re-deploy a config-only blade.

3. Customise how Eclipse runs your adapter

To run your adapter in Eclipse for the first time, follow the steps below:

  1. In Eclipse, click Run > Run Configurations. The Run Configurations dialog appears.
  2. From the list of configuration types, right-click Java Application and select New
  3. In the Name box, type 'PricingAdapter'.
  4. In the Project box, select the PricingAdapter project.
  5. In the Main class box, select com.caplin.template.PricingAdapterTemplate
  6. Click the Arguments tab
  7. In the Working directory box, select Other, click File System, and select the path to your adapter's DataSource directory in your Deployment Framework.

    If you're running Eclipse on Linux or MacOS, which both recognise the symlinks in the Deployment Framework, then select the logical path to your adapter's DataSource directory:

    /path_to_deployment_framework/active_blades/PricingAdapter/DataSource

    If you're running Eclipse on Microsoft Windows, which does not recognise the symlinks in the Deployment Framework, then select the physical path to your adapter's DataSource directory:

    C:\path_to_deployment_framework\kits\PricingAdapter\PricingAdapter-0.0.0\DataSource
  8. Under the Environment tab, click New, and set a new environment variable CONFIG_BASE with the absolute path to your DFW's global config directory.
  9. Under the Common tab, in Display in favorites menu, select Run.
  10. Click Run

To run your adapter on subsequent occasions, click Run > Run, or press Ctrl-F11.

Monitor your adapter in the CMC during development

To monitor your adapter in the Caplin Management Console (CMC), enable your adapter's JMX interface and then manually add the details of your adapter to the CMC.

Note: you manually supply your adapter's details to the CMC in this instance because you have not deployed a full blade to your DFW and the ./dfw mon command will not detect your adapter. 

To enable JMX for your adapter, follow the steps below:

  1. If the integration adapter is running, click the stop icon () in the Eclipse console to stop it.
  2. In your Eclipse project, open the file blade/DataSource/etc/datasource.conf
  3. Add the following lines to the end of the file:

    define PricingAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT ${THIS_LEG}1005
    rmi-registry-port ${PricingAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT}
    
    define PricingAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT ${THIS_LEG}1006
    rmi-client-port ${PricingAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT}
  4. Click Run > Run to start your adapter

To add the details of your adapter to the CMC, follow the steps below:

  1. Right-click in the CMC overview screen and select Add new datasource
  2. Enter the following details for the adapter:

  3. Click OK. A new box will appear in the CMC representing your integration adapter. If the adapter is currently running in Eclipse, then the box will be blue. You can try stopping and starting your adapter in Eclipse, and watch the box go from red to blue in the CMC.

Deploying a complete integration adapter blade

So far we have only exported the configuration for the blade into the Deployment Framework, and we have run it from source in Eclipse. This is ideal for development, where you want to make code changes and see them take effect immediately without have to export your blade into the framework.

However, eventually you will want to export the complete blade, including the compiled source code and start scripts, so that it can run inside the Deployment Framework. This section will show you how to build and deploy the adapter into the Deployment Framework so that it can run outside Eclipse.

Follow the steps below:

  1. If the Pricing Adapter is running in Eclipse, stop it. Note that it goes red in the CMC. Now close the CMC and run ./dfw stop to stop the Deployment Framework.
  2. From the root of your Pricing Adapter project, run the command below to export your project as a full blade:

    ./gradlew assemble
  3. From the root directory of your DFW, run the command below to stop all running Platform components:

    ./dfw stop
  4. Copy the blade ~/src/PricingAdapter/build/distributions/PricingAdapter-version.zip to your DFW's kits directory:

    cp ~/src/build/distribution/PricingAdapter-version.zip ~/DeploymentFramework-version/kits
  5. From the root directory of your DFW, run the command below to deploy your blade:

    ./dfw deploy

    Answer Yes when prompted to replace the previous blade. You can also suppress this prompt in future by running ./dfw deploy -f.

    You will see a warning informing you that the Deployment Framework does not know which host the new blade should run on.

  6. Run ./dfw hosts and you will see that Liberator and Transformer are configured to run on localhost, but there is no entry for your blade.

    $ ./dfw hosts
    
       Core components                Primary          Secondary
       -------------------------------------------------------------
       Liberator                      localhost        localhost
       Transformer                    localhost        localhost
    
       Blades                         Primary          Secondary
       -------------------------------------------------------------
       LiberatorDemoDataSource        localhost        localhost
       TransformerDemoDataSource      localhost        localhost
    
  7. Run the command below to specify 'localhost' as the server on which the PricingAdapter blade should run:

    ./dfw hosts PricingAdapter localhost localhost
  8. Run ./dfw hosts again, and you will see that the PricingAdapter blade is now configured to run on localhost.
  9. Run ./dfw mon to refresh the configuration for the deployed PricingAdapter blade.
  10. Run ./dfw start. This time you will see the message "Starting PricingAdapter" in addition to the usual "Starting Liberator" and "Starting Transformer".
  11. Run ./dfw cmc to relaunch the CMC. You should see that the PricingAdapter is blue, indicating that it is running inside the Deployment Framework.
Tip: you can start and stop components in the Deployment Framework by name. Try running ./dfw start PricingAdapter and ./dfw stop PricingAdapter and see what happens.

Reverting back to running the blade from Eclipse

Now that you understand how to deploy a complete integration adapter blade, it's time to revert back to running from Eclipse so that you can continue development in the forthcoming tutorials.

Steps

  1. Close the CMC
  2. In the root directory of your DFW, run the command below to stop all running Caplin Platform components:

    ./dfw stop
  3. In the root directory of your DFW, run the command below to register the fictitious hostname 'eclipse' as the PricingAdapter blade's primary and secondary server:

    ./dfw hosts PricingAdapter eclipse eclipse
  4. Run the command below to start all components in the Deployment Framework:

    ./dfw start

    Notice that the message "Starting PricingAdapter" no longer appears

  5. Run the command below to re-launch the CMC:

    ./dfw cmc

    Notice that the PricingAdapter is red, indicating that it is not running.

  6. Run the Pricing Adapter from Eclipse. It should turn blue in the CMC, indicating that it has started up and connected to Transformer successfully.

You can also have a look at the contents of the file $DEPLOYMENT_FRAMEWORK_ROOT/active_blades/PricingAdapter/DataSource/var/framework.log. This file is generated by the Deployment Framework, and tells you that it deliberately has not started the PricingAdapter because it isn't configured to run on this host.

 

Understand

The Deployment Framework uses the concept of a host file to determine which components should start up on which machine. It only starts components that are configured to run on either "localhost" or the actual name of the machine (as returned by the hostname command).

This greatly simplifies the deployment process, because it allows customers to zip up their Deployment Framework and deploy that same artifact on every machine in their environment. For example, if the host file specifies that Liberator should run on "linuxserver1" and Transformer should run on "linuxserver2", then the same Deployment Framework artifact can be started up on both servers and the components within it will only run on the appropriate server.

This slightly increases the amount of disk usage, because the Deployment Framework artifact contains blades which may never actually run on some machines in the environment, but it makes the deployment process much easier because customers do not have to build and configure different Deployment Framework artifacts tailored to each machine in their environment.

Review

Having completed this tutorial you should now be familiar with the following tasks:

  • How to use the Caplin Project Templates and Eclipse to developer integration adapters
  • How to export integration adapter blades and deploy them to the Deployment Framework.

In the next tutorial we will be focusing on the specific implementation of a Pricing Integration Adapter and looking at the blade we’ve just created in more detail. We will also create more integration adapters in subsequent tutorials.