Activating a component’s JMX interface

This page describes how to enable Java Management Extensions (JMX) monitoring for Liberator, Transformer, and other DataSources.

Overview

The Caplin Management Console (CMC) connects to monitorable components via Java Remote Method Invocation (RMI).

By default, a DataSource’s RMI interface is not enabled and so the DataSource is not available for monitoring. To activate a DataSource’s RMI interface, you define values for the configuration items rmi-registry-port and rmi-client-port.

How you define values for rmi-registry-port and rmi-client-port differs between DataSources. Some DataSources require you to set these configuration items indirectly via macro definitions; other require you to set the configuration items directly.

Activating JMX in Liberator

Liberator’s JMX interface is not activated by default. Follow the steps below to activate it:

  1. Run the command below to stop Liberator:

    ./dfw stop Liberator
  2. Run the command below to activate the LiberatorJMX blade:

    ./dfw activate LiberatorJMX
  3. In the file global_config/environment.conf, set Liberator’s Java RMI hostname to the hostname or IP address of Liberator’s host:

    define LIBERATOR${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME     <hostname>
    If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Liberator.
  4. Liberator’s JMX registry port and client port default to ${THIS_LEG}1001 and ${THIS_LEG}2001 respectively. To override these defaults, redefine the following variables in the Deployment Framework file global_config/environment.conf:

    define LIBERATOR${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1001
    define LIBERATOR${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2001
  5. Liberator’s JMX interface is password protected, and the username and password default to admin and admin respectively. To override these defaults, redefine the following variables in the Deployment Framework file global_config/environment.conf:

    define LIBERATOR_MONUSER    admin
    define LIBERATOR_MONPASS    admin
  6. Run the command below to restart Liberator:

    ./dfw start Liberator

Activating JMX in Transformer

Transformer’s JMX interface is not enabled by default. Follow the steps below to activate it:

  1. Run the command below to stop Transformer:

    ./dfw stop Transformer
  2. Run the Deployment Framework command below to activate the TransformerJMX blade:

    ./dfw activate TransformerJMX
  3. In the file global_config/environment.conf, set Transformer’s Java RMI hostname to the hostname or IP address of Transformer’s host:

    define TRANSFORMER${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME     <hostname>
    If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Transformer.
  4. Transformer’s JMX registry port and client port default to ${THIS_LEG}1002 and ${THIS_LEG}2002 respectively. To override these defaults, redefine the following variables in the Deployment Framework file global_config/environment.conf:

    define TRANSFORMER${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1002
    define TRANSFORMER${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2002
  5. Transformer’s JMX interface is password protected, and the username and password default to admin and admin respectively. To override these defaults, redefine the following variables in the Deployment Framework file global_config/environment.conf:

    define TRANSFORMER_MONUSER    admin
    define TRANSFORMER_MONPASS    admin
  6. Run the command below to restart Transformer:

    ./dfw start Transformer

Activating JMX in a C DataSource (with feature blades)

Caplin-supplied C DataSource adapter blades package their JMX configuration in a JMX blade, which can be activated and deactivated from the command line.

The following Caplin adapters include JMX blades:

  • Caplin TREP adapter

  • Caplin RMDS adapter

The steps for enabling the JMX interface of the above adapters are similar to the steps for enabling the JMX interfaces of Liberator and Transformer, but you override the values for the RMI ports and hostname in the file global_config/overrides/bladename/DataSource/etc/environment.conf.

For example, to enable the JMX interface of the Caplin TREP adapter, follow the steps below:

  1. Stop the adapter:

    ./dfw stop TREPAdapter
  2. Activate the JMX blade for the adapter:

    ./dfw activate TREPAdapterJMX
  3. To change the TREP adapter’s default RMI settings, edit the file global_config/overrides/TREPAdapter/DataSource/etc/environment.conf, and change the values assigned to the following macros:

    • TREPAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT

    • TREPAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT

    • TREPAdapter${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME

  4. Restart the adapter:

    ./dfw start TREPAdapter

Activating JMX in a C DataSource (without feature blades)

To enable the JMX interface of a C DataSource that does not include a JMX configuration blade, add the following configuration items to the file global_config/overrides/bladename/etc/datasource-overrides.conf:

# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

# RMI hostname
jvm-options -Djava.rmi.server.hostname=<hostname>

For more information on the configuration items above, see the links below:

Activating JMX in a Java DataSource

To enable the JMX interface of a Java DataSource, add the following lines to the file global_config/overrides/bladename/etc/datasource.conf:

# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

add-monuser
    user    admin
    pass    admin
end-monuser

Add the JMX hostname to the script used by the Deployment Framework to run the Java DataSource: kits/bladename/bladename-version/DataSource/bin/start-jar.sh. This script varies between DataSources; the example script below is taken from Caplin’s Pricing Adapter Template (see start-jar.sh):

#!/bin/bash
#
# Start the Pricing Template Java Adapter.
#
# $1 - Path to java executable
# $2 - Path to datasource XML file
# $3 - Path to fields XML file
# $4 - Java definitions ( optional )
#
# Returns the process id of the Java process.
#

BLADENAME=MyPricingAdapter5

if [ "$1" = "CONFREADER" ]; then
   shift
   confreading=1
   jar=`ls "$BINARY_ROOT"/lib/datasource*.jar|head -1`
else
   confreading=0
   jar=`ls "$BINARY_ROOT"/lib/$BLADENAME*.jar|head -1`
   classpath="${BINARY_ROOT}/lib/*"

   echo "Classpath: $jar"
fi

if [ $confreading = 1 ]; then
   java -jar "$jar" "$@"
   exit $?
else
   java \ (1)
    -Djava.rmi.server.hostname=<hostname>
    -cp "$classpath" \
    -jar "$jar" "$@" 2> "$LOGDIR"/java-$BLADENAME.log >/dev/null &
   echo $!
fi
1 Original command split onto multiple lines for clarity

For more information on the configuration items above, see the links below: