# Create a Java-based Transformer Service blade

Here we explain how to create a simple Service blade for Transformer, where the blade is written as a Transformer modulein the Java programming language. The core of Transformer is written in C, so to create a module in Java, you use Transformer’s Java Module API.

 If you’ve already read How Can I…​ Create a Lua-based Transformer Service blade, you’ll notice that the Lua blade described there does exactly the same thing as the blade we create here. This is entirely deliberate, and should allow you to see the differences and similarities between using Java and Lua for creating Transformer Service blades.

## Before you start

You’ll need a Transformer and Liberator to help test your Service blade while you develop it, and a Pricing Adapter that can supply the Bid and Ask prices. In this example we’ve assumed that the corresponding record fields are called bidPrice and askPrice respectively.

If you don’t have Transformer and Liberator already deployed on a machine for this purpose, you’ll need to deploy one or both of these components to the Deployment Framework on your development machine. To do this, follow the instructions in How can I…​ Deploy Platform components to the Framework. You won’t need to set up HTTPS connections or KeyMaster while you’re developing the blade, so you can ignore the topics about those things.

If you need to develop a suitable Pricing Adapter first, see How can I…​ Create a Java-based Adapter blade.

• the blade type and blade compatibility information are in the control file

• Liberator related configuration for the blade is in Liberator/etc/rttpd.conf

• Transformer related configuration for the blade is in Transformer/etc/java.conf and Transformer/etc/spreadjava.conf

• the Transformer module’s Java JAR file compiled from the Java source file is in Transformer/lib/java

## Overview

In brief, you create the blade using the following steps, which are given in more detail further down the page:

## Create the blade’s directory structure

In a directory that’s outside the Deployment Framework (say Temp_Java_blade), create the following directory structure:

At this stage, you don’t need to create the control file and the .conf and .jar files that are also shown in the structure - you’ll do that in subsequent steps.

## Define the new fields

The blade must define any new fields that it will use, which in this instance means our new Spread field.

2. Using a suitable text editor, add the following configuration to fields.conf

#
#
 You don’t have to use the field number we’ve shown here; you can choose your own value as long as it’s unique within your particular Caplin Platform installation.

For more about defining fields, see Field definitions in the DataSource Features and Concepts, and Field definition format.

## Include configuration for Liberator and Transformer

The new blade has to include configuration for the core Platform components that it interacts with. In this case, the core components are: Liberator, which will subscribe to data supplied by the Transformer module, and Transformer, which houses the module.

Configuration details for the Liberator are stored in the rttpd.conf file

2. Using a suitable text editor, add the following configuration to rttpd.conf

#
# Liberator configuration for data from
#
service-name SpreadJavaBlade${THIS_LEG} include-pattern ^/FX/ add-source-group required true add-priority remote-label transformer${THIS_LEG}
end-priority
if "${FAILOVER}" == "ENABLED" add-priority remote-label transformer${OTHER_LEG}
end-priority
endif
end-source-group
end-data-service

This configuration defines a data service through which the Liberator requests the data supplied by the SpreadJavaBlade. It also defines, through the add-source-group …​ end-source-group block, how the Liberator should fail the data service over to an alternate Liberator (this only applies if failover has been enabled for the deployment - see How can I…​ Set up server failover capability).

This is fairly standard configuration. The important points to note are:

• The service-name configuration item defines the name of the data service, which in this case is (by convention) the name of the blade, SpreadJavaBlade, that supplies the data.

• The include-pattern item specifies that the data service is to supply data for all subscriptions whose subjects start with the string /FX/

• The macros THIS_LEG and OTHER_LEG are used to differentiate the configuration of primary and secondary failover legs.

### Define the Java module configuration in Transformer

Configuring Transformer for a Java module is a bit more involved than doing so for a Lua module, as the Transformer has to know the location of the Java Virtual Machine (JVM) in order to start it.

2. Using a suitable text editor, add the following configuration to java.conf

#
# Java module configuration for the
#
jvm-location       "${JVM_LOCATION}" jvm-global-classpath %r/lib/java/transformermodule.jar modules-dir${ccd}/../lib

classpath  "${ccd}/../lib/java/SpreadModule.jar" end-javaclass The important points to note about this configuration are: jvm-location defines the path of the JVM. It refers to the master definition through the macro JVM_LOCATION, which is defined in <Framework-root>/global_config/environment-defaults.conf jvm-global-classpath defines the classpath of the Java library underlying Transformer’s Java Module API. ** modules-dir defines the directory path to the java directory, which contains the Java module’s JAR file. + NOTE: The ccd macro in the path name defines the current directory path of the file in which it is referenced. So in this example, because the ccd reference is in the file SpreadLuaBlade/Transformer/etc/java.conf, the macro defines the path SpreadLuaBlade/Transformer/etc/ The directory path for the Java Module is therefore SpreadLuaBlade/Transformer/lib • add-module defines an identifier for the Transformer Java module. This must be the blade name, so in this example it’s SpreadJavaBlade. • add-javaclass defines: • The fully qualified name of the Java class that implements the Java module (class-name example.spreadmodule.SpreadModule). • class-id — a short identifier of the Java class. For blade implementations this must be the blade name, so in this example it’s set to SpreadJavaBlade. • The classpath on which the module’s JAR file can be found (classpath "${ccd}/../lib/java/SpreadModule.jar"). You generate the JAR from the SpreadModule.java file where the Java source code for the module resides.

include-file ${ENV:CONFIG_BASE}bootstrap.conf module-logfile spreadjava.log module-classid spreadjava include-file${BASE}/global_config/overrides/SpreadJavaBlade/Transformer/etc/spreadjava.conf

• module-logfile specifies the name of the log file in Transformer/var that the spreadjava module writes errror and information messages to at run time.

• module-classid specifies the class ID of the Java Module. This must match the class-id defined in java.conf.

• The final include-file item allows you to override the blade’s standard configuration after it has been deployed, by putting a different spreadjava.conf configuration file in the Deployment Framework’s overrides directory for the blade.

The Deployment Framework needs to take some specific actions to allow a Java Transformer module blade to work correctly. So the Framework needs to have a way of knowing the blade is a Java Transformer module. This is done through a blade control file located in the root directory of the blade.

This is the blade control file

3. You would normally also record any blade compatibility information in the control file as well (for details, see the Reference information about the blade control file), but for this simple example there’s nothing to record.

That’s all the configuration changes you need for the time being.

## Deploy configuration to the Deployment Framework

Now you’ve created the initial configuration for the core components that use your Transformer Service blade, you can deploy this configuration in your development environment.

1. ZIP up the blade directory structure in your temporary work area into a skeleton blade kit. The .zip file must have a name of the form <blade_name>-<version_number>.zip

The topmost directory in the .zip file must be the top level directory of the blade.

2. Navigate to <Framework-root> and deploy the skeleton blade kit:

The ./dfw deploy command should respond with:

Boot-strapping the Deployment Framework

And then ./dfw versions should show the new blade:

Deployment Framework           6.0.4-267113

Core components                Version
-----------------------------------------------------------
Liberator                      6.1.0-275608
Transformer                    6.1.0-275716

-----------------------------------------------------------

-----------------------------------------------------------
BlotterExport                                     Inactive
DemoDataSource                                    Inactive
DirectConnection                                  Active
HTTP                                              Active
HTTPS                                             Inactive
JavaOpenPermissioning                             Inactive
LiberatorJMX                                      Active
LiberatorWebsite                                  Active
MinimalLiberatorWebsite                           Inactive
OpenPermissioning                                 Active
ServerIdentification                              Active
TransformerJMX                                    Active

Note that deploying the skeleton SpreadJavaBlade has automatically put it in the active state.

./dfw start

At this stage, the Liberator and Transformer are running with the new configuration. The new blade won’t run of course, because no executable code has been written for the Java module.

In a Web browser, navigate to the Liberator’s status page, where you should see the SpreadJavaBlade data service:

 The URL of the Liberator is of the form http://:. You can find the and by entering the command ./dfw info. In a development enviroment, the URL would typically be http://localhost:18080. When the Liberator home page is displayed, select the View Status button.

## Write the Java module

This is the functional part of the Java module that defines the actions you need it to perform. In this example, the Java source is in a single file called SpreadModule.java. Create this file in a suitable place within your development environment.

The example code is quite long, so we’ll break it up into sections in order to explain it. It uses Transformer’s Java Module API.

Section 1:

import com.caplin.transformer.module.*;

public class SpreadModule  implements TransformerModule, SubscriptionListener
{
private int bidFieldNumber;

@Override
public void initialise(String moduleName, TransformerAccessor transformerAccessor)
{
bidFieldNumber = transformerAccessor.getFieldManager().getFieldByName("BidPrice").getNumber();

}

This first section identifies defines the SpreadModule class which implements the TransformerModule and SubscriptionListener interfaces of the Transformer Java Module API. It defines three integers to contain the numbers of the relevant record fields, and, in the initialise() method, populates these integers using the getFieldByName() method. initialise() also creates a subscription listener, to listen for messages from the Pricing Adapter that have subjects in the "/FX/" namespace.

Section 2:

@Override
}

@Override
public void shutdown() {
}

@Override
public String getLoggerName() {
}

@Override
public void objectDeleted(String objectName) {
}

@Override
public void status(String objectName, ObjectStatus objectStatus) {
}

The above method implementations just define the default settings for some methods of the TransformerModule and SubscriptionListener interfaces.

Section 3:

@Override
public void update(DataSourceUpdateEvent dataSourceUpdateEvent) {
String bidValue =
dataSourceUpdateEvent.getTransformerData().getFieldByFieldNumber(bidFieldNumber).getValue();

This implementation of the SubscriptionListener interface’s update() method obtains the AskPrice and BidPrice field values from an incoming record message with a subject that begins with "/FX/". It uses the field numbers obtained when the module was initialised (see section 1 of the example).

Section 4:

if ( askValue != null && bidValue != null ) {
}
}
}

Having retrieved the AskPrice and BidPrice field values, the subscription listener’s update() method checks that neither of them are null, calculates spreadValue, by subtracting one value from the other, and uses the addData() method to add this calculated spread value to the Spread field that was defined earlier.

When you’ve completed the code in the SpreadModule.java file, follow the steps below:

1. Compile the file and package it as a JAR file (SpreadModule.jar).

 Ensure that the JAR containing the Transformer’s Java Module API is in the compilation classpath. This JAR is called transformermodule.jar and it’s located in the lib/java directory of the deployed Transformer in the Deployment Framework.

## Start the new Transformer Service blade

1. Follow one of the steps below to restart components on the Deployment Framework:

• If you have exclusive use of the Deployment Framework, run the command below to restart all components on the Deployment Framework:

./dfw start
• If you don’t have exclusive access to the Deployment Framework, run the command below to restart just Liberator and Transformer:

./dfw start Liberator Transformer
2. Look at the Liberator’s status page to check that the Liberator is connected to the Transformer and can see the data service (SpreadJavaBlade in our example) for which the new Java-based Transformer Service blade supplies data.

3. Use the Liberator’s Liberator Explorer to request data for the relevant subjects supplied by the Transformer Service blade, and check that the data is returned (via Transformer) as expected, with a correctly calculated Spread field included.