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

Getting started with 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 material provides information about the VM configuration and tuning options, together with the default settings. Follow the links provided for more detailed information.

Configuring your system

Most Java applications should run on an OpenJDK that contains the OpenJ9 VM without changing anything on the underlying system. However, to get the most out of your system you might want to consider some configuration options. Read Configuring your system to learn more about the following options:

  • Setting operating system environment variables, such as PATH and CLASSPATH.
  • Increasing resource limits for running Java applications.
  • 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.

Garbage collection policies

OpenJ9 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 policies.

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 Introduction to class data sharing.

Native data operations

If your Java application manipulates native data, consider writing your application to take advantage of methods in the Data Access Accelerator (DAA) API.

The following functions are provided:

  • Arithmetic, comparison, shifting, and validation operations for packed decimal data.
  • Conversion operations between different binary coded decimal and Java binary types.
  • Marshalling operations: marshalling and unmarshalling Java binary types, such as short, int, long, float, and double, to and from byte arrays.

You can gain a number of benefits by using the APIs provided:

  • Improved application performance by avoiding object creation and intermediate processing, which can also put pressure on the Java heap.
  • Hardware acceleration by automatically exploiting available hardware features on specific platforms.
  • Platform independence for applications that are developed to take advantage of Data Access Acceleration.

For more information, see the API documentation.

Cloud optimizations

To improve the performance of applications that run in containers, 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 persistence, store the cache in a volume that you map to your container. For more information, see Inroduction to class data sharing and AOT Compiler.

  • 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.

The OpenJ9 VM automatically detects when it is running in a docker container and uses a mechanism to detect when the VM is idle. When an idle state is detected, OpenJ9 runs a garbage collection cycle and releases free memory pages back to the operating system. The object heap is also compacted to make best use of the available memory for further application processing. Compaction is triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction.

For cloud services that charge based on memory usage, maintaining a small footprint can generate cost savings. For more information about tuning options that control this process, see -XX:IdleTuningMinIdleWaitTime.

Cryptographic operations

OpenJDK uses the in-built Java cryptographic implementation by default. However, native cryptographic implementations typically provide better performance. OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which is well established and used with many enterprise applications. The OpenSSL V1.0.x, V1.1.x, and V3.0.x implementations are currently supported for the Digest, CBC, GCM, and RSA algorithms. The OpenSSL V1.1.x and V3.0.x implementations are also supported for the ChaCha20 and ChaCha20-Poly1305 algorithms.

On Linux and AIX operating systems, the OpenSSL 1.0.x or 1.1.x library is expected to be found on the system path. If you use a package manager to install OpenSSL, the system path will be updated automatically. On other operating systems, the OpenSSL 1.1.x library is typically bundled. Later levels of some Linux operating systems might bundle OpenSSL 3.0.x.

If you have multiple versions of OpenSSL on your system, the OpenJ9 VM uses the latest version.

Note: OpenSSL 3.0.x does not support initialization vector (IV) sizes above 16 Bytes for the GCM algorithm. (In earlier OpenSSL versions, you can use such sizes but they might cause unpredictable behavior.) If you need to use a larger size, disable OpenSSL support for the GCM algorithm.

OpenSSL support is enabled by default for all supported algorithms. If you want to limit support to specific algorithms, a number of system properties are available for tuning the implementation.

Each algorithm can be disabled individually by setting the following system properties on the command line:

  • To turn off Digest, set -Djdk.nativeDigest=false
  • To turn off ChaCha20 and ChaCha20-Poly1305, set -Djdk.nativeChaCha20=false. Note: Start of content that applies to Java 8 (LTS) These algorithms are not supported on Java 8 End of content that applies only to Java 8 (LTS)
  • To turn off CBC, set -Djdk.nativeCBC=false
  • To turn off GCM, set -Djdk.nativeGCM=false
  • To turn off RSA, set -Djdk.nativeRSA=false

You can turn off all the algorithms by setting the following system property on the command line:

-Djdk.nativeCrypto=false

To build a version of OpenJDK with OpenJ9 that includes OpenSSL support, follow the steps in our detailed build instructions:

Note: If you obtain an OpenJDK with OpenJ9 build that includes OpenSSL or build a version yourself that includes OpenSSL support, the following acknowledgements apply in accordance with the license terms:

  • This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/).
  • This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).

Exploiting GPUs

OpenJ9 provides both the CUDA4J API and the GPU API, which enables you to develop applications that can take advantage of graphics processing unit (GPU) processing for suitable functions, such as sorting arrays. You can also enable the JIT compiler to offload certain processing tasks to a GPU by specifying the -Xjit:enableGPU option on the command line. When enabled, the JIT compiler determines when to offload tasks based on performance heuristics.

GPU processing is supported only on Linux little-endian systems, such as x86-64 and IBM Power LE, and Windows x86-64 systems. For more information about enabling GPU processing, see Exploiting graphics processing units.

Special consideration is needed when using the WDDM driver model for GPUs on Windows. Using the WDDM driver model means the GPU is also used as a display device and as such is subject to the Timeout Detection and Recovery (TDR) mechanism of Windows. If you are running demanding GPU workloads, you should increase the timeout from the default 2 seconds. More detail may be found in NVIDIA's Installation Guide for Windows.

Hardware acceleration

On AIX® systems that contain the Nest accelerator (NX) co-processor, OpenJ9 can take advantage of the zlibNX library. This library is an enhanced version of the zlib compression library that supports hardware-accelerated data compression and decompression. The zlibNX library is supported on AIX version 7.2 TL4 and later and must be installed on the system. The Nest accelerator (NX) co-processor is available on IBM POWER9® systems. To learn more about zlibNX, see Data compression by using the zlibNX library.

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.

On Java 11 and later, you can use the jlink utility to create a custom OpenJ9 runtime image, which allows you to optimize image size. If you do not require translations from the English language, the translation files can be removed to further optimize the size. You can achieve this by specifying the --exclude-files=**java_**.properties option when you run jlink. The default English java.properties file is unaffected.

Start of content that applies to Java 16 and later Using jpackage

(Linux, macOS, and Windows only)

You can use the jpackage utility to package a Java application into a platform-specific package that includes all of the necessary dependencies. Full details of the tool are available at JEP 392: Packaging Tool. Instructions for using it and the various options available, are documented in the Oracle Tool Specifications: The jpackage Command.

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.