Configure the Java environment

Overview

Java-based components require a Java virtual environment (JVM) to run. This includes the following components and plug-ins:

Control-M plug-in
E4JMS (TIBCO EMS) plug-in
IBM i plug-ins
JMX plug-in
REST API plug-in
REST Extractor plug-in
SSO Agent

This topic walks you through the files and setup required before you start configuring Java-based components.

Required files

Before you begin, check that you have the complete set of Netprobe files on the machine where you are running the Java-based plug-in.

These files are bundled in the Netprobe binary package, which you can download from ITRS Downloads. For more information on the files provided, see Files included in the Netprobe package.

In addition, check that you have one of the supported Java Runtimes or Java Development Kits on the machine. These packages are available from their respective vendor sites.

Note: The supported Java version may be different, depending on the plug-in you plan to run. For guidance on supported versions, see Application and plug-in specific information in Geneos Compatibility Matrix.

For Windows platforms, the supported Java installation typically does not require the additional configuration steps outlined in this topic. Please proceed only when you encounter errors with your Java-based plug-in.

Certain plug-ins require additional vendor-specific files to run. You must obtain these from a licensed distribution, as ITRS Group Ltd does not make these files available as part of the Netprobe for this reason. In these cases, refer to the plug-in user guide for the required vendor-specific files.

Java virtual machine parameters

The Netprobe launches the Java virtual machine (JVM) with the following parameters:

Parameter Description

java.class.path This parameter contains a list of third-party and user-defined classes that the JVM needs for running Java applications. The Netprobe uses all the JAR files found in the current directory, as well as the on the GENEOS_JARS environment variable.

Parameter	Description
`java.class.path`	This parameter contains a list of third-party and user-defined classes that the JVM needs for running Java applications. The Netprobe uses all the JAR files found in the current directory, as well as the on the `GENEOS_JARS` environment variable.
`java.library.path`	This parameter provides the path to the native libraries that the JVM requires. Typically, the `java.library.path` is set to the location of the `launchpad` library file, plus the current working directory. When `JAVA_HOME` is defined, the path to the Java library is also included. Therefore, the full value of this parameter follows the format: `.;%JAVA_HOME%\bin` for Windows. `./lib64:.:$JAVA_HOME/lib/amd64` for Linux and Solaris x64. `./lib64:.:$JAVA_HOME/lib/sparcv9` for Solaris Sparc. `./lib64:.:$JAVA_HOME/lib/ppc64le` for Linux on IBM POWER8. `./lib64:.:$JAVA_HOME/lib` for other platforms.
`java.home`	This parameter sets the Java home of the embedded JVM.

java.library.path

This parameter provides the path to the native libraries that the JVM requires.

Typically, the java.library.path is set to the location of the launchpad library file, plus the current working directory. When JAVA_HOME is defined, the path to the Java library is also included. Therefore, the full value of this parameter follows the format:

.;%JAVA_HOME%\bin for Windows.
./lib64:.:$JAVA_HOME/lib/amd64 for Linux and Solaris x64.
./lib64:.:$JAVA_HOME/lib/sparcv9 for Solaris Sparc.
./lib64:.:$JAVA_HOME/lib/ppc64le for Linux on IBM POWER8.
./lib64:.:$JAVA_HOME/lib for other platforms.

java.home This parameter sets the Java home of the embedded JVM.

Once the Netprobe starts, you can find and verify the values of the parameters in the Netprobe log.

Set the environment variables

Once the required files are in place, the next step is to set the environment variables so that the Netprobe can locate them.

Note: Beginning Netprobes version 4.12.0, you only need to set the JAVA_HOME environment variable. From the information carried by that variable, the Netprobe can look for other JAR and library files on its own. For more information on this behaviour, see Configure the Java environment.

Locating resource files for Netprobe versions 4.12.x

Beginning Netprobes version 4.12.0, the Netprobe attempts to locate JAR and library files based on the directory set in JAVA_HOME:

With this behaviour in place, the following environment variables become optional:

LD_LIBRARY_PATH
PATH
GENEOS_JARS
GENEOS_LIBS

Instead, the Netprobe searches for the JAR and library files in the following manner:

The JAR files are searched for in the /jars directory in the Netprobe binary directory.
launchpad.dll (for Windows) or launchpad.so (for Linux and similar platforms) are searched for in the Netprobe binary directory.
jvm.dll (for Windows) or libjvm.so (for Linux and similar platforms) are searched for based on the value of JAVA_HOME:
- JAVA_HOME/bin/server for Windows
- JAVA_HOME/lib/ppc64le/server for Linux on IBM POWER8
- JAVA_HOME/lib/amd64/server for Linux and Solaris x64
- JAVA_HOME/lib/sparcv9/server for Solaris Sparc
- JAVA_HOME/lib/server for IBM AIX

Caution: The 4.12.x Netprobe follows the OracleJDK and OpenJDK 8 structure when searching for jvm.dll or libjvm.so. If you are running OpenJDK 11, then you need to set the corresponding environment variable. For guidance, see Configure the Java environment.

If the Netprobe fails to locate the files in this method, then it attempts to search the files using the optional environment variables.

Note: If you are running a plug-in that requires vendor-specific JAR files, set GENEOS_JARS to point to the directory containing them. For guidance, see Configure the Java environment.

Java library

The Netprobe needs to create a Java virtual machine from which to load and run Java-based plug-ins or processes. To do so, it must locate the requisite library file found in the Java runtime installation directory:

libjvm.so for Linux and similar platforms
jvm.dll for Windows

To direct the Netprobe to the library file, modify the environment variable accordingly:

LD_LIBRARY_PATH for Solaris and Linux platforms.
LIB_PATH for AIX platforms.
PATH for Windows platforms.

When modifying the path environment variable, follow these guidelines:

The path environment variable entry must come before any other entry.
Do not copy the library file directly into the current working directory. The library file relies on relative paths to locate additional resources. If it is moved to the current working directory, then the additional resources will no longer be available, and the Netprobe will fail to create a Java virtual machine.

Caution: Geneos components use the JAVA_HOME environment variable to point to the Java runtime installation directory. It does not use the JRE_HOME environment variable.

On Windows

Via command line

You can set the environment variable on the command line:

set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.8.0_211\jre
set PATH=%JAVA_HOME%\bin\client;%PATH%

Via registry

Alternatively, to prevent conflicts with other Java applications, you can set the Netprobe registry keys, instead. The path to the Netprobe registry is HKEY_LOCAL_MACHINE\SOFTWARE\NetAgent\NetprobeNT.

The JAVA_HOME and JVM_LIBPATH keys should be added in the same location as the other Netprobe registry keys:

JAVA_HOME — points to the Java runtime folder. For example, C:\Program Files (x86)\Java\jdk1.8.0_211\jre.
JVM_LIBPATH — contains the absolute path of the jvm.dll file. For example, C:\Program Files (x86)\Java\jdk1.8.0_211\jre\bin\client\jvm.dll.

Windows registry keys for Java resources

Note: If you set the registry keys, then the Netprobe ignores the values set in the environment.

On Solaris

You can set the environment variables on the command line:

setenv JAVA_HOME /usr/java/jdk1.8.0_211/jre
setenv LD_LIBRARY_PATH $JAVA_HOME/lib/sparc/client
setenv PATH $JAVA_HOME/bin:$PATH

On Linux

You can set the environment variables on the command line:

setenv JAVA_HOME /usr/java/jdk1.8.0_211/jre
setenv LD_LIBRARY_PATH $JAVA_HOME/lib/amd64/server
setenv PATH $JAVA_HOME/bin:$PATH

On IBM AIX

You can set the environment variables on the command line:

setenv JAVA_HOME /usr/java8/jre
setenv LIBPATH $JAVA_HOME/lib/ppc:$JAVA_HOME/lib/ppc/j9vm
setenv PATH $JAVA_HOME/bin:$PATH

JAR files

You can specify the directory where the Netprobe accesses the Geneos JAR files through the GENEOS_JARS environment variable.

If a plug-in requires vendor-specific JAR files, then use GENEOS_JARS to point to that directory, as well.

On Windows

On Windows platforms, you can set the environment variable on the command line:

set GENEOS_JARS=C:\Jars

On Linux, Solaris, and IBM AIX

On Linux and similar platforms, you can set the environment variable on the command line:

setenv GENEOS_JARS /jars

Note: This setting is particularly useful when a plug-in is expected to connect to an application and needs multiple JAR files to be able to connect to it, as it is not always feasible to copy additional JAR files into the current working directory.

Additional directories to shared libraries

To specify additional directories for locating libraries used by the plug-in, use the GENEOS_LIBS environment variable.

On Windows

You can set the environment variable on the command line:

set GENEOS_LIBS=C:\Libs

On Linux, Solaris, and IBM AIX

On Linux and similar platforms, you can set the environment variable on the command line:

setenv GENEOS_LIBS /libs

After you set the environment variables, restart the Netprobe.

Next steps

After you have configured the Java environment, you may proceed to setting up your Java-based plug-in:

If you encounter errors when configuring your Java environment, see Troubleshoot the Java configuration.