Configure Runtime Java options

Semarchy xDI Runtime starts by running a Java command that includes command-line options. You can set your own Java options for xDI Runtime in three ways:

  1. Add Java options to the initvariables startup script.

  2. Add Java options to environment variables that xDI recognizes.

  3. Set Java options in the runtime configuration file, engineParameters.xml.

The first two methods are more reliable, as they pass arguments to Java at startup. You must use command-line syntax such as -D<property>=<value> or other valid arguments. Separate multiple arguments with spaces, and use quotes to delimit values that contain spaces.

The third method does not work with options that only work when Java starts, such as memory settings. Options must be entered as XML attributes.

Make sure your runtime is not running before changing the configuration or environment.

How to set Java options

With the initvariables script

The initvariables script takes Java options that apply to all xDI Runtime actions.

  1. In the runtime install directory, find the initvariables.bat (Windows) or initvariables.sh (Linux, macOS) file.

  2. Open the file for editing.

  3. Go to the line that starts with XDI_RUNTIME_VM_PROPERTIES or set XDI_RUNTIME_VM_PROPERTIES.

  4. Add your Java arguments alongside the existing commands, in command-line format.

With environment variables

The environment variables that xDI Runtime looks for work in different situations, and you can set one or both as needed:

  • XDI_COMMAND_OPTS: Applies to the Runtime startcommand.bat and startcommand.sh scripts.

  • XDI_RUNTIME_OPTS: Applies to all other Runtime runnable scripts.

Both environment variables take space-separated Java options in command-line format.

In the configuration file

In the runtime installation directory, open the properties/engineParameters.xml file, and find the <javaConfiguration> node. For each Java option you want, add a property node with name and value attributes, and use the attributes to hold the Java option name and value.

Example 1. Configuration example.
<parameters>
  <...>
  <javaConfiguration>
    <property name="myOption01" value="value01"/>
    <property name="myOption02" value="value02"/>
    <...>
  </javaConfiguration>
  <...>
</parameters>

Save the file and restart the runtime for the options to take effect.

List of Runtime Java options

This section lists Java settings or properties that are of particular use to xDI Runtime.

Set runtime memory capacity

By default, Runtime allows the Java Virtual Machine to manage memory automatically. The default should work in most cases, but you can use -X Java arguments to set Runtime memory usage.

To change Runtime memory usage, set these in the initvariables script or in environment variables.

Example 2. Example arguments
# Minimum heap size
-Xms512m
# Maximum heap size
-Xmx2048m
# Stack size
-Xss4m

Set the runtime shutdown delay

xDI Runtime understands a custom Java property that controls its shutdown delay.

To configure the runtime’s shutdown delay, use the com.semarchy.xdi.graceful-shutdown-delay property, and set its value to an integer followed by a time designator.

Example 3. Example
-Dcom.semarchy.xdi.graceful-shutdown-delay=30s

Manage runtime monitoring with Java Management Extensions

Java Management Extensions (JMX) is a technology for managing and monitoring Java applications. It allows you to follow memory or class usage with utilities like jmap or external tools such as Visual VM. Java enables JMX features by default, but only on the local machine unless explicitly set otherwise. In this way, you can make use of JMX to monitor the xDI Runtime locally.

For more information about JMX, see the Oracle documentation.

If you want to prevent tools from monitoring the xDI Runtime, you can disable JMX in one of two ways.

Block monitoring with an environment variable (recommended)

  1. Stop the xDI Runtime.

  2. Edit or create the XDI_RUNTIME_OPTS environment variable for your machine or user session.

  3. Append the parameter -XX:+DisableAttachMechanism to this variable.

  4. Start the xDI Runtime

Block monitoring in the startup file

  1. Stop the xDI Runtime.

  2. Edit the initvariable.bat (Windows) or initvariable.sh (Linux, macOS) file.

  3. Add the parameter -XX:+DisableAttachMechanism to the XDI_RUNTIME_VM_PROPERTIES variable in the file.

  4. Start the xDI Runtime