Pricing Integration Adapter (1)

Integration adapters provide the Caplin Platform with data from a bank's backend systems. In this tutorial, you will create 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 templates for pricing adapters, blotter adapters, notification adapters, trading adapters, and Java Transformer modules. Each template contains working code and configuration.

In this tutorial, you will create a project based on the Pricing Adapter Template. 

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/training.zip
  3. Extract the project:

    unzip training.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-training/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. Choose one of the methods below to resolve project dependencies:
    • Manual download: download the following files from the Caplin Download site and copy them to the libs folder in your project.

      • DataSource for Java: datasource-java-version-jar-with-dependencies.jar

    • Caplin Software Repository: create a gradle.properties file in the root directory of your project and assign your Caplin username and password to the variables below:

      caplinNexusUser=username
      caplinNexusSecret=password

Import the adapter project into your IDE

This section includes instructions for importing your project into Eclipse and IntelliJ.

Import the 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 using Cygwin, your project directory is C:\cygwin64\home\username\src\PricingAdapter
  5. Click Finish

Import the project into IntelliJ

To import your project into IntelliJ, follow the steps below:

  1. Click File > New > Project from existing sources
  2. Select the project's Gradle build file: ~/src/PricingAdapter/build.gradle

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 instructions for running an adapter within an IDE differ depending on whether your adapter runs against components in a local DFW or 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, perform the following steps:

  1. Export your adapter's configuration in a config-only blade
  2. Deploy the config-only blade to your DFW
  3. Create a 'Run Configuration' in your IDE

1. Export your adapter's configuration in 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. Create a 'Run Configuration' in your IDE

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.PricingAdapter
  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 your 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. Re-deploy your adapter's configuration to your Deployment Framework. See Export your adapter's configuration as a config-only only blade and Deploy the config only blade to your DFW above.

    Note: every time you change your adapter's configuration during development, you must re-export and re-deploy the configuration to your Deployment Framework
  5. From the root of your Deployment Framework, run the command below to regenerate the configuration file for the CMC:

    ./dfw mon
  6. 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.

Run the adapter in a Deployment Framework

To run your adapter in a Deployment Framework, export you project as a Caplin Platform Blade and deploy the blade to your Deployment Framework.

Follow the steps below:

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

    ./dfw stop
  3. From the root of your Pricing Adapter project, run the command below to export your project as a full Caplin Platform Blade (binaries and configuration):
    ./gradlew assemble
  4. Copy the exported 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 on which host the new blade should run.

  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

    On any particular server, the DFW only starts components with a primary or secondary server that matches the server's hostname or the special hostname 'localhost'. The hostname 'localhost' acts as a wildcard host in this context. Specifying 'localhost' as a component's primary or secondary server ensures that the component starts on any server on which it is deployed. The level of control the ./dfw hosts command gives you over where a component runs allows you to deploy all components to a single server and then duplicate that DFW to all servers in your environment. This greatly simplifies configuration.

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

Follow the steps below:

  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 specify the fictitious hostname 'nosuchhost' as the PricingAdapter blade's primary and secondary server:

    ./dfw hosts PricingAdapter nosuchhost nosuchhost
    Note: you can use any fictitious hostname to stop the DFW from running the PricingAdapter binaries. The hostname 'nosuchhost' was an arbitrary choice.
  4. Run the command below to start all components in the Deployment Framework:

    ./dfw start

    Notice that the the PricingAdapter is no longer listed among the components started by the DFW. If you check the DFW log ($DEPLOYMENT_FRAMEWORK_ROOT/active_blades/PricingAdapter/DataSource/var/framework.log) you will find an entry explaining that the PricingAdapter component was not started because it is not configured to run on this host.

  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. Start the Pricing Adapter in Eclipse. It should turn blue in the CMC, indicating that it has started up and connected to Transformer successfully.

Review

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

  • How to use the Caplin Project Templates and Eclipse to develop 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.