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

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:

<dependency>
    <groupId>io.helidon.microprofile.config</groupId>
    <artifactId>helidon-microprofile-config</artifactId>
    <version>2.5.0</version>
</dependency>

<!-- optional: add it if you want YAML config file support -->
<dependency>
    <groupId>io.helidon.config</groupId>
    <artifactId>helidon-config-yaml</artifactId>
    <version>2.5.0</version>
</dependency>

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: "MyCluster"
        - 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

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 give you incredible amount of 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.