Skip to content

CAUTION: This site hosts draft documentation for the next release. For published content of the latest release, visit www.eclipse.org/openj9/docs

Switching to Eclipse OpenJ9

If you are already familiar with HotSpot command-line options but want the advantages of Eclipse OpenJ9™, the following information will prove helpful. In all cases, check individual topics for minor discrepancies in the way these options might work.

Note: For information about HotSpot equivalences and differences for items other than command-line options, see New to Eclipse OpenJ9?

Compatible options

You can use the following command-line options in OpenJ9, just as you did in HotSpot; you can continue to use the HotSpot option in OpenJ9 without having to change your code:

Option Usage
-X Displays help on nonstandard options.
-Xbootclasspath Specifies the search path for bootstrap classes and resources.
-Xcheck:jni Runs additional checks for JNI functions during VM startup.
-Xfuture Turns on strict class-file format checks.
-Xint Runs an application in interpreted-only mode.
-Xlog Some forms of -Xlog that enable garbage collection logging are recognized. (Equivalent to -Xverbosegclog).
-Xmn Sets the initial and maximum size of the new area when using -Xgcpolicy:gencon.
-Xms Sets the initial size of the heap. (Equivalent to -XX:InitialHeapSize)
-Xmx Specifies the maximum size of the object memory allocation pool. (Equivalent to -XX:MaxHeapSize)
-Xnoclassgc Disables class garbage collection (GC).
-Xrs Prevents the OpenJ9 run time environment from handling signals.
-Xss Sets the Java™ thread stack size. (Equivalent to -XX:ThreadStackSize). Note: Unlike HotSpot, this option applies only to the Java stack. OpenJ9 has a separate native stack for operating system threads (see -Xmso)
-Xverify:mode Enables or disables the verifier.
-XX:ConcGCThreads Configures the number of GC mutator background threads.
-XX:[+|-]AlwaysPreTouch Enables/disables committing of memory during initial heap inflation or heap expansion.
-XX:[+|-]CompactStrings Enables/disables String compression. Note: Unlike HotSpot, this option is disabled by default in OpenJ9.
Start of content that applies to Java 16 plus -XX:DiagnoseSyncOnValueBasedClasses=<number> Configure warnings for value-based classes.
-XX:[+|-]DisableExplicitGC Enables/disables explicit System.gc() calls. (Alias for -Xdisableexplicitgc / -Xenableexplicitgc)
-XX:[+|-]ExitOnOutOfMemoryError Triggers VM shutdown on out-of-memory conditions.
-XX:[+|-]HeapDumpOnOutOfMemory Enables/disables dumps on out-of-memory conditions.
-XX:HeapDumpPath Specifies a directory for all VM dumps including heap dumps, javacores, and system dumps. (Alias for -Xdump:directory)
-XX:[+|-]IgnoreUnrecognizedVMOptions Specifies whether to ignore unrecognized top-level VM options.
-XX:InitialHeapSize Sets the initial size of the heap. (Alias for -Xms)
-XX:InitialRAMPercentage Sets the initial size of the Java heap as a percentage of total memory.
-XX:MaxDirectMemorySize Sets a limit on the amount of memory that can be reserved for all direct byte buffers.
-XX:MaxHeapSize Specifies the maximum size of the object memory allocation pool. (Alias for -Xmx)
-XX:MaxRAMPercentage Sets the maximum size of the Java heap as a percentage of total memory.
-XX:OnOutOfMemoryError Runs specified commands when a java.lang.OutOfMemoryError is thrown. (Equivalent to -Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,exec=)
-XX:ParallelCMSThreads Configures the number of GC mutator background threads.
-XX:ParallelGCThreads Configures the number of GC threads.
-XX:[+|-]PrintCodeCache Prints code cache usage when the application exits.
-XX:[+|-]ShowHiddenFrames Specifies whether generated hidden MethodHandle frames are displayed in a stack trace. Note: Unlike HotSpot, this option doesn't require the +UnlockDiagnosticVMOptions option.
-XX:[+|-]UseCompressedOops Disables compressed references in 64-bit JVMs. (See also -Xcompressedrefs)
-XX:[+|-]UseContainerSupport Sets a larger fraction of memory to the Java heap when the VM detects that it is running in a container.

Equivalent options

These HotSpot command-line options have equivalents in OpenJ9 that are not specified in the same way, but perform a related function:

HotSpot Option OpenJ9 Option Usage
-Xcomp -Xjit:count=01 -Xcomp disables interpreted method invocations.
-Xgc -Xgcpolicy2 Configuring your garbage collection policy.
-XX:+UseNUMA -Xnuma:none3 Controls non-uniform memory architecture (NUMA) awareness.

Notes:

  1. HotSpot uses -Xcomp to force compilation of methods on first invocation. However, this option is deprecated. Whilst it can be used for compatibility, using -Xjit:count=0 is preferred.

  2. HotSpot uses -Xgc to both select policies and configure them; OpenJ9 uses -Xgcpolicy to select policies, reserving -Xgc for configuration.

  3. In HotSpot, NUMA awareness is turned off by default and is turned on by using the -XX:+UseNUMA option. Conversely, the OpenJ9 VM automatically enables NUMA awareness and uses -Xnuma:none to turn it off.

    • If you were previously using HotSpot in its default mode, you must now explicitly turn off NUMA awareness in OpenJ9.
    • If you are used to using -XX:+UseNUMA in HotSpot, you no longer need to explicitly turn on NUMA awareness; it's on by default.

Creating compatible behavior

You can set the following options to make OpenJ9 behave in the same way as HotSpot.

Option Usage
Start of content that applies only to Java 8 (LTS) -Djava.lang.string.substring.nocopy=true Avoid String sharing by String.substring().
-Xnuma:none Disable non-uniform memory architecture (NUMA) awareness.
Start of content that applies only to Java 11+ (LTS)-XX:+CompactStrings Enables String compression.
-XXHandleSIGABRT Force handling of SIGABRT signals to be compatible with HotSpot.

Compatible environment variables

The JAVA_TOOL_OPTIONS environment variable can be used to set command line options as described in OpenJ9 command-line options and Environment variables.