Eclipse OpenJ9

Welcome to the user documentation for the Eclipse OpenJ9 virtual machine (VM).

This user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in an OpenJDK runtime. However, due to differences between the Java SE class libraries, specific options might apply only to one Java SE version. Icons are used to indicate where differences apply. For example:

Start of content that applies only to Java 8 (LTS) This sentence applies only to Java 8 binaries that include the OpenJ9 VM. End of content that applies only to Java 8 (LTS)

Start of content that applies only to Java 9 and later This sentence applies only to Java 9 or later binaries that include the OpenJ9 VM. End of content that applies only to Java 9 or later

Note: As a usability aid, the icons for long term service (LTS) releases are a different colour from feature releases.

The following table indicates which Java releases are LTS releases and which are feature releases:

Java SE version LTS release Feature release
8 yes
9 yes
10 yes
11 yes

Note: Documentation to support OpenJ9 is still under construction. The current content covers some high level information about OpenJ9 components together with the command-line options and environment variables that you can use to configure the VM when you start your application. We expect further content to be contributed over time. Because OpenJ9 was contributed to the Eclipse Foundation by IBM, this content contains some links to additional information that forms part of the IBM® SDK, Java™ Technology Edition product documentation in IBM Knowledge Center. That content supplements the documentation here until a more complete set of user documentation is available.

We welcome contributions to the user documentation. If you would like to get involved, please read our Contribution guidelines.

What is OpenJ9

OpenJ9 is a high performance, scalable, Java™ virtual machine (VM) implementation that is fully compliant with the Java Virtual Machine Specification.

At run time, the VM interprets the Java bytecode that is compiled by the Java compiler. The VM acts as a translator between the language and the underlying operating system and hardware. A Java program requires a specific VM to run on a particular platform, such as Linux™, z/OS®, or Windows™.

This reference material provides information about the VM configuration and tuning options, together with the default settings.

You can obtain pre-built OpenJDK binaries from the AdoptOpenJDK project:

Configuring your system

For normal operation, certain environment variables must be set at the operating system level. Depending on your system environment, you might also want to set other configuration options that allow the VM to exploit hardware and operating system features. Read Customizing your system to learn more about the following options:

  • Setting the PATH and CLASSPATH environment variable.
  • Setting the LIBPATH or LD_LIBRARY_PATH environment variable (AIX® and Linux).
  • Setting ulimits on AIX and Linux systems to ensure that the operating system allocates sufficient resources for your application.
  • Setting region size, BPXPRM parameters, and Language Environment® runtime options on z/OS systems.
  • If your application allocates a large amount of memory and frequently accesses that memory, you might want to enable large page support on your system. See Configuring large page memory allocation.
  • Configuring Dynamic LPAR support on AIX systems.

Performance tuning

OpenJ9 is configured to start with a set of default options that provide the optimal runtime environment for Java applications with typical workloads. However, if your application is atypical, you can improve performance by tuning the OpenJ9 VM. You can also improve performance by enabling hardware features or using specific APIs in your application code. Click the links to learn more about the following options:

Choosing a garbage collection policy
J9 includes several garbage collection policies. To learn more about these policies and the types of application workload that can benefit from them, see Garbage Collection.
Improving startup times with class data sharing
You can share class data between running VMs, which can reduce the startup time for a VM once the cache has been created. For more information, see Class Data Sharing.
Dealing with native data
If your Java application manipulates native data, consider writing your application to take advantage of methods in the Data Access Accelerator API.
Optimizing your application for cloud deployments
To improve the performance of applications that run in the cloud, try setting the following tuning options:
  • Use a shared classes cache (-Xshareclasses -XX:SharedCacheHardLimit=200m -Xscmx60m) with Ahead-Of-Time (AOT) compilation to improve your startup time. For more information, see Class Data Sharing and AOT Compiler.
  • Use the idle VM settings to maintain a smaller footprint, which can generate cost savings for cloud services that charge based on memory usage. The idle tuning mechanism detects when the VM is idle, releasing free memory pages to keep the footprint as small as possible and keep your running costs to a minimum. For more information, see -XX:IdleTuningMinIdleWaitTime.
  • Use the -Xtune:virtualized option, which configures OpenJ9 for typical cloud deployments where VM guests are provisioned with a small number of virtual CPUs to maximize the number of applications that can be run. When enabled, OpenJ9 adapts its internal processes to reduce the amount of CPU consumed and trim down the memory footprint. These changes come at the expense of only a small loss in throughput.

Runtime options

Runtime options are specified on the command line and include system properties, standard options, nonstandard (-X) options, and -XX options. For a detailed list of runtime options, see OpenJ9 command-line options

Default settings

If you do not specify any options on the command line at run time, the OpenJ9 VM starts with default settings that define how it operates. For more information about these settings, see Default settings for the OpenJ9 VM.

Supported environments

OpenJDK binaries that contain the OpenJ9 VM are supported on a range of hardware and operating systems. This range is expanding as work progresses at the Eclipse foundation. See the current list of supported environments for details.

Note: This user guide contains information about configuring, tuning, and debugging OpenJ9 on the z/OS® platform. This content was contributed by IBM so that it is available when the work to create OpenJDK binaries for the z/OS platform is complete.

Troubleshooting

The OpenJ9 diagnostic component contains extensive features to assist with problem determination. Diagnostic data is produced under default conditions, but can also be controlled by starting the VM with the -Xdump option or using the com.ibm.jvm.Dump API. You can also trace Java applications, methods, and VM operations by using the -Xtrace option.

To get started, read Diagnostic tools and data.