65 Introduction to Coherence Applications and GraalVM Native Image

Use GraalVM Native Image to compile Oracle Coherence applications into native executables. Core Coherence supports Native Image, including cache, persistence, federation, Elastic Data, Extend, security and TLS use cases, subject to the module limitations and application reachability requirements described in this chapter.

For a list of Coherence features with limited support for GraalVM Native Image technology, see Limitations of GraalVM Native Image Support.

The base Coherence JAR includes a GraalVM native feature that allows the GraalVM native compiler to identify classes in a Coherence application that should be marked for reachability, reflection or serialization. This means there is less work required for application developers to identify the classes required. As long as coherence.jar is in the application classpath, the GraalVM native compiler uses the Coherence Native feature.

It can be difficult to identify the exact set of classes that are required for a specific Coherence application because the application's configuration can be changed at runtime using different configuration files and system properties. Therefore, the Coherence native feature marks far more Coherence classes as reachable than an application might require. Although this produces a slightly larger image size, it ensures that the image has all of the required classes, regardless of the runtime configuration.

Note:

The Coherence native feature is best used with GraalVM 25 or later. It uses the new format for reachability-metadata files, which may not work in earlier versions of GraalVM.

Security Prerequisites

Native-image reachability metadata and Coherence application security metadata serve different purposes. Generate and include both when the application uses custom models or executable types. A class included by the native-image build still needs the normal serialization and execution policy when it crosses a Coherence boundary.

For the complete configuration and policy, see Generating Application Security Configuration, Developing Classified Application Types in the Security Guide.

Native Image Toolchain and Release Scope

The 26.1.0.0.0 Native Image examples target GraalVM for JDK 25 and the matching Coherence artifacts. Java 21 is the JVM runtime minimum; that does not establish earlier GraalVM Native Image qualification. Keep reachability metadata, generated application security metadata and native-library packaging in the native build, and test the resulting executable’s actual application paths.

• Mixing JVM and Native Image Processes
  You can create a Coherence cluster that consists of a mixture of JVM and Native Image cluster members.
• Best Practices
  When working with Coherence applications and GraalVM Native Image, consider following these recommendations.
• Limitations of GraalVM Native Image Support
  The following Coherence features have limited to no functionality with GraalVM Native Image, though this may change in the future.

Mixing JVM and Native Image Processes

You can create a Coherence cluster that consists of a mixture of JVM and Native Image cluster members.

Note the following:

• Cluster members should be running the same Java version. For Native Image cluster members, use the same GraalVM version that you used when compiling the native executables.

• Compatible Native Image Extend clients can connect to JVM-based proxies, and JVM Extend clients can connect to Native Image proxies. Both directions still require matching supported protocol, serializer and application metadata.

• All the client and proxy configurations, and discovery mechanisms work with Native Image.

• Extend clients from older Coherence releases running in a JVM can connect to a Native Image proxy.

Best Practices

When working with Coherence applications and GraalVM Native Image, consider following these recommendations.

Serialization

For serialization, use Portable Object Format (POF) instead of Java serialization. Classes that implement PortableObject are automatically marked for reachability and reflection by the Coherence native feature.

With Java serialization, the native image compiler must be notified of any classes that use Java serialization. You can use Java serialization with Coherence native images and subclasses of some Coherence types are automatically marked as serializable by the Coherence native feature, but it may require additional work and testing to ensure all classes are marked as serializable in reachability metadata files.

Lambdas

Some Coherence API methods can take lambdas as parameters. These lambdas are serialized and sent to the server. Coherence has two modes of lambda support, static and dynamic but only static lambdas are supported with native images. For information on configuring Coherence to use static lambdas, see Configuring Lambda Serialization Mode.

Management and Metrics

Coherence management and metrics rely on MBeans for some of the data. When building a native image, the following build arguments are recommended, but not required. If you choose not to include them, some JVM-level metrics and features such as thread dumps are not available.

Table 65-1 Build Arguments

Build Argument	Description
--enable-monitoring=jmxserver,jmxclient,jvmstat	Required to enable MBean functionality so that some of the JVM MBeans that Coherence uses are available. They are also required if connecting to Coherence using JMX.
--enable-monitoring=threaddump	Required to enable thread dumps, both manual thread dumps and those created by the Coherence service guardian.
--enable-monitoring=heapdump	Required for applications that expect to take heap dumps.
--enable-http	Required for HTTP endpoints such as health checks, management over REST, and metrics.
--enable-https	Required when using HTTPS.
--enable-monitoring=jfr	Required if using the JFR functionality in Coherence Management Over REST, or just using normal JFR functionality.

Limitations of GraalVM Native Image Support

The following Coherence features have limited to no functionality with GraalVM Native Image, though this may change in the future.

Coherence JSON Serialization

Coherence JSON Serialization is predominantly used when supporting non-Java gRPC clients. The current Coherence JSON implementation uses the ASM library for certain operations and it does not work reliably. Due to this unreliability, we cannot currently recommend its use with Native Image.

Coherence JSON is also used for Coherence Management Over REST and this feature works correctly.

Coherence REST

The Coherence REST module provides a REST API for Coherence caches. This module is not supported with Native Image due to its use of Jersey and other injection frameworks. Coherence REST is rarely used because most users build REST APIs on top of Coherence using other frameworks such as Helidon, Micronaut, or Spring. Therefore, there are no plans to provide Coherence REST support for Native Image.

HotCache

The Coherence HotCache modules are deployed with Oracle GoldenGate so it does not make sense for these to support native image compilation.

HotCache deployed into GoldenGate can communicate with a Coherence cluster that is running as a native image.

Coherence*Web

The Coherence*Web module is not supported with Native Image.

Coherence Concurrent

Currently, some parts of the Coherence Concurrent modules use lambdas which do not work properly when serialized in a native image.

Coherence CDI

Coherence CDI support was built to integrate with Helidon MicroProfile. Due to issues in Helidon when using Native Image, Coherence CDI and Helidon applications may not work correctly.

Coherence MicroProfile

Coherence MP support was mainly built to integrate with Helidon. Due to issues in Helidon when using Native Image the Coherence MicroProfile modules are not currently tested or supported as native images.

Coherence gRPC With Non-Java Clients

Coherence gRPC was written to support non-Java clients such as Python, Go, Javascript, and so on. These clients use JSON for serialization and due to the unreliability of JSON, non-Java clients are not supported when using Native Image Coherence clusters. It would be possible to run a native image cluster alongside JVM based gRPC proxy cluster members which the non-Java clients could connect to.

Coherence Java gRPC clients using POF serialization work using native images for either the client, the cluster, or for both client and cluster.