9 Using Coherence MicroProfile Configuration

Coherence MicroProfile (MP) Configuration provides support for Eclipse MicroProfile Configuration within Coherence cluster members. See Eclipse MicroProfile Configuration. Coherence MP Configuration enables you to configure various Coherence parameters from the values specified in any of the supported configuration sources, and to use Coherence cache as another, mutable configuration source.

This chapter includes the following topics:

• Enabling the Use of Coherence MicroProfile Configuration
  To use Coherence MP Configuration, you should first declare it as a dependency in the pom.xml file.
• Configuring Coherence Using MP Configuration
  Coherence provides a number of configuration properties that you can use to define certain attributes or to customize cluster member behavior at runtime.
• Using Coherence Cache as a Configuration Source
  Coherence MP Configuration also provides an implementation of the Eclipse MP Configuration ConfigSource interface, which enables you to store configuration parameters in a Coherence cache.
• Examples Using Helidon MicroProfile with Coherence
  There are a number of open source example applications that demonstrate using Coherence MicroProfile integration with Helidon.
• Coordinating Framework Configuration Health and Metrics
  Align framework-owned lifecycle, startup configuration, application metadata and protected observation endpoints.

Enabling the Use of Coherence MicroProfile Configuration

To use Coherence MP Configuration, you should first declare it as a dependency in the pom.xml file.

You can declare Coherence MP Configuration as follows:

<dependency>
    <groupId>${coherence.groupId}</groupId>
    <artifactId>coherence-mp-config</artifactId>
    <version>${coherence.version}</version>
</dependency>

You will also need an implementation of the Eclipse MP Configuration specification as a dependency. For example, if you are using Helidon, add the following to the pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.helidon</groupId>
      <artifactId>helidon-bom</artifactId>
      <version>4.3.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>io.helidon.microprofile.config</groupId>
    <artifactId>helidon-microprofile-config</artifactId>
  </dependency>
  <dependency>
    <groupId>io.helidon.config</groupId>
    <artifactId>helidon-config-yaml</artifactId>
  </dependency>
</dependencies>

Application requirements

This POM fragment uses the Helidon 4.3.0 baseline of the 26.1 release and requires Java 21. Merge dependencyManagement/dependencies with the existing application POM; do not add duplicate top-level sections. Import the matching Coherence BOM and include coherence-mp-config. The YAML module is optional when YAML is not used. A different MicroProfile implementation must supply compatible Config/CDI APIs and implementations.

Configuring Coherence Using MP Configuration

Coherence provides a number of configuration properties that you can use to define certain attributes or to customize cluster member behavior at runtime.

For example, you can define attributes such as cluster and role name, as well as define whether a cluster member should or should not store data, through the use of system properties:

-Dcoherence.cluster=MyCluster -Dcoherence.role=Proxy -Dcoherence.distributed.localstorage=false

You can also define most of these attributes within the operational or cache configuration file. For example, you could define first two attributes, cluster name and role, within the operational configuration override file:

  <cluster-config>
    <member-identity>
      <cluster-name>MyCluster</cluster-name>
      <role-name>Proxy</role-name>
    </member-identity>
  </cluster-config>

While these two options are more than enough in most cases, there are some issues with them being the only way to configure Coherence:

• When you are using one of the Eclipse MicroProfile implementations, such as Helidon (see Helidon) as the foundation of your application, Oracle recommends that you define some of Coherence configuration parameters along with the other configuration parameters, and not in a separate file or through system properties.
• In some environments, such as Kubernetes, Java system properties are cumbersome to use, and environment variables are a preferred way of passing configuration properties to containers.

Unfortunately, neither of the two use cases above is supported out-of-the-box. Coherence MP Configuration is designed to fill this gap.

As long as you have coherence-mp-config and an implementation of Eclipse MP Configuration specification to your class path, Coherence will use any of the standard or custom configuration sources to resolve various configuration options it understands.

Standard configuration sources in MP Configuration include the META-INF/microprofile-config.properties file, if present in the class path; environment variables; and system properties (in that order, with the properties in the latter overriding the ones from the former). These configuration sources directly address the second use case mentioned above, and allow you to specify Coherence configuration options through environment variables within the Kubernetes YAML files. For example:

containers:
  - name: my-app
    image: my-company/my-app:1.0.0
    env:
      - name: COHERENCE_CLUSTER
        value: "application-specific-cluster"
      - name: COHERENCE_ROLE
        value: "Proxy"
      - name: COHERENCE_DISTRIBUTED_LOCALSTORAGE
        value: "false"

The above is just an example. If you are running the Coherence cluster in Kubernetes, you should really be using Coherence Operator instead, as it will make both the configuration and the operation of the Coherence cluster much easier.

You can also specify the Coherence configuration properties along with the other configuration properties of your application, which will enable you to keep everything in one place, and not scattered across many files. For example, if you are writing a Helidon application, you can simply add the coherence section to the application.yaml file:

coherence:
  cluster: MyCluster
  role: Proxy
  distributed:
    localstorage: false

Application requirements

The Kubernetes fragment belongs under the pod spec containers field; replace the image with your approved immutable application image. Set initialization-time Coherence properties before the first service/Session starts. A live change to a configuration source does not imply that already-created cluster, security or service settings are reconfigured. Keep secrets in the deployment secret provider and out of ordinary shared config caches/logs.

Using Coherence Cache as a Configuration Source

Coherence MP Configuration also provides an implementation of the Eclipse MP Configuration ConfigSource interface, which enables you to store configuration parameters in a Coherence cache.

This feature has several benefits:

• Unlike pretty much all of the default configuration sources, which are static, configuration options stored in a Coherence cache can be modified without forcing you to rebuild your application JARs or Docker images.
• You can change the value in one place, and it will automatically be visible and up to date on all the members.

While the features above provide significant flexibility, it may not always be desirable. Therefore, this feature is disabled by default.

If you want to enable it, you should do so explicitly by registering CoherenceConfigSource as a global interceptor in the cache configuration file:

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">

  <interceptors>
    <interceptor>
      <instance>
        <class-name>com.oracle.coherence.mp.config.CoherenceConfigSource</class-name>
      </instance>
    </interceptor>
  </interceptors>

  <!-- your cache mappings and schemes... -->

</cache-config>

After you enable the feature, CoherenceConfigSource is activated as soon as the cache factory is initialized, and injected into the list of available config sources for your application to use through the standard MP Configuration APIs.

By default, it will be configured with a priority (ordinal) of 500, making it of a higher priority than all the standard configuration sources, thus allowing you to override the values provided through configuration files, environment variables, and system properties. However, you have full control over that behavior and can specify a different ordinal through the coherence.mp.config.source.ordinal configuration property.

Examples Using Helidon MicroProfile with Coherence

There are a number of open source example applications that demonstrate using Coherence MicroProfile integration with Helidon.

For more information about example applications, see the following items:

• Helidon Sock Shop

  This project is an implementation of a stateful, microservices based application that uses Oracle Coherence Community Edition as a scalable embedded data store, and Helidon MP as an application framework

  If you are interested in using this, see the Coherence Helidon Sock Shop sample.

• Todo List Example

  This repository contains a set of simple task management examples written in various languages to showcase Coherence Community Edition.

  In particular, the Java directory showcases how to integrate Coherence with Helidon MicroProfile.

  If you are interested in using this, see the Todo List example.

Application requirements

Follow Coordinating Framework Configuration Health and Metrics for release baselines, lifecycle ownership and endpoint access. Choose readiness, liveness and safety according to the resource being observed rather than treating them as interchangeable.

Coordinating Framework Configuration Health and Metrics

Align framework-owned lifecycle, startup configuration, application metadata and protected observation endpoints.

Use the Coherence 26.1 modules and a compatible MicroProfile runtime together. The release baseline uses Config 3.1, Health 4.0.1 and Metrics 5.1.2; the optional implementation dependencies must come from the framework BOM rather than independent version guesses.

• Let the framework own the Coherence instance/Session when its integration manages startup. Inject/reuse the configured Session and typed map handles; do not start a second client or close a shared instance inside a request.
• Package generated application metadata, model classes and POF resources with the artifact visible to the framework/Coherence class loader.
• Coordinate startup/readiness with required services and persistence recovery. A framework HTTP server being live is not proof that storage services are safe or ready.
• Configure endpoint-specific identity, TLS and network access for health/metrics. Prefer local/internal scraping paths and the approved management gateway for remote access.
• Choose the intended metrics adapter and registry. Avoid exporting the same MBean twice through competing adapters; bound labels and preserve counter/gauge semantics.
• Test startup/shutdown, rejected requests and context propagation across asynchronous work using the exact runtime and module versions.

For underlying service health/metric semantics use Using the Health Check API and Using Oracle Coherence Metrics.