Implementing the OpenJ9 shared class cache for applications in containers

The Eclipse OpenJ9 shared class cache (SCC) enables the VM to store Java classes, JIT compiled code, and profiling data in an optimized form that can load quickly. Multiple VMs can share the SCC, which reduces total memory consumption.

WebSphere Liberty container images contain an SCC and (by default) add the application's specific data to the SCC at image build time when your Dockerfile runs the RUN configure.sh command.

Some content in the SCC is sensitive to heap geometry. If we change the heap geometry after the SCC is created, server restarts can result in fluctuations in start-up performance and such content not being used. Specifying a smaller -Xmx value increases the chances of obtaining a heap geometry that is compatible with the AOT code.

To control this feature, use the following variable:

OPENJ9_SCC (environment variable)

If true, cache application-specific data in an SCC and include it in the image. A new SCC is created if needed, otherwise data are added to the existing SCC. The default value is true.

TRIM_SCC (environment variable)

If true, the application-specific SCC layer is sized-down to accommodate only the data populated during image build process. To allow the application to add more data to the SCC at runtime, set the TRIM_SCC environment variable to false and ensure that the SCC is not marked as read-only in the OPENJ9_JAVA_OPTIONS environment variable. The following example sets the OPENJ9_JAVA_OPTIONS environment variable in the application Dockerfile.

OPENJ9_JAVA_OPTIONS="-XX:+IgnoreUnrecognizedVMOptions -XX:+IdleTuningGcOnIdle -Xshareclasses:name=openj9_system_scc,cacheDir=/opt/java/.scc,nonFatal -Dosgi.checkConfiguration=false"

The OPENJ9_JAVA_OPTIONS environment variable is defined in the base Liberty image Dockerfile, but includes the readonly sub-option. The default value is true.

SCC_SIZE (environment variable)

The size of the application-specific SCC layer in the image. The value of the SCC_SIZE environment variable is only used if the TRIM_SCC environment variable is set to false. The default value is 80m.

WARM_ENDPOINT (environment variable)

If true, curl is used to access the WARM_ENDPOINT_URL environment variable during the population of the SCC. The amount of information in the SCC increases and first request time in subsequent starts of the image improves. The default value is true.

WARM_ENDPOINT_URL (environment variable)

The URL to access during SCC population if the WARM_ENDPOINT environment variable is set to true. The default value is localhost:9080/.

WARM_OPENAPI_ENDPOINT (environment variable)

If true, curl is used to access the WARM_OPENAPI_ENDPOINT_URL environment variable during the population of the SCC. The amount of information in the SCC increases and first request time in subsequent starts of the image improves. The default value is true.

WARM_OPENAPI_ENDPOINT_URL (environment variable)

The URL to access during SCC population if the WARM_OPENAPI_ENDPOINT environment variable is true. The default value is localhost:9080/openapi.