Activating a component’s JMX interface

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

Contents:

Overview
Activating JMX in Liberator
Activating JMX in Transformer
Activating JMX in a C DataSource (with feature blades)
Activating JMX in a C DataSource (without feature blades)
Activating JMX in a Java DataSource

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:

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

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.

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
```
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
```
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:

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

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>

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
```
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
```
Run the command below to restart Transformer:
```
$ ./dfw start Transformer
```

Activating JMX in a C DataSource (with feature blades)

This section applies to C DataSource adapters with a JMX feature blade (TREP Adapter) that have been deployed to a Deployment Framework. For C DataSource adapters without a JMX feature blade, or for C DataSource adapters deployed outside of a Deployment Framework, see Activating JMX in a C DataSource (without feature blades).

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.

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

Stop the adapter:
```
$ ./dfw stop TREPAdapter
```
Activate the JMX blade for the adapter:
```
$ ./dfw activate TREPAdapterJMX
```
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 configuration variables:
```
define TREPAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT    value
define TREPAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT      value
define TREPAdapter${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME  value
```
For more information on the meaning of the three configuration variables above, see the documentation for rmi-registry-port, rmi-client-port, and Oracle Java: java.rmi system properties.
Restart the adapter:
```
$ ./dfw start TREPAdapter
```

Activating JMX in a C DataSource (without feature blades)

To enable the JMX interface of a C DataSource adapter that does not include a JMX configuration blade, or to enable the JMX interface of a C DataSource adapter deployed outside of a Deployment Framework, add the following configuration items to the adapter’s etc/jmx.conf file:

File: etc/jmx.conf

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

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

# Hostname remote JMX clients should use to connect to this server
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: