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 two ways:

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

  2. Add Java options to the initvariables startup script.

Both methods 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 first method is the most reliable and compatible, and you should use it where possible.

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

How to set Java options

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.

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.

Useful Java options for Runtime

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

Adjust the 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 1. 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 2. Example
-Dcom.semarchy.xdi.graceful-shutdown-delay=30s

Adjust limits for XML and XPath processing

The Java Virtual Machine sets limits for processing XML and XPath data. If you work with large datasets, you may get an error such as org.xml.sax.SAXParseException, warning about exceeding processing limits.

To work around these limits, you must set Java properties to modify the limits. These properties are set with the -D argument, and you can find the full list on the Java API for XML Processing (JAXP) Security Guide.

Example

Suppose xDI Runtime cannot process your XML data because it has more entities than Java allows. You could set the jdk.xml.totalEntitySizeLimit system property to raise the entity limit, or even remove it entirely:.

# This option doubles the default entity limit
-Djdk.xml.totalEntitySizeLimit=100000000

# This option removes the entity limit entirely
-Djdk.xml.totalEntitySizeLimit=0

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