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 OpenJ9

If you are already familiar with HotSpot command-line options but want the advantages of 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 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.
-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:[+|-]CompactStrings Enables/disables String compression
-XX:[+|-]DisableExplicitGC Enables/disables 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:[+|-]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(). End of content that applies only to Java 8
-Xnuma:none Disable non-uniform memory architecture (NUMA) awareness.
-XXhandleSIGABRT Force handling of SIGABRT signals to be compatible with HotSpot