Whenever an application upgrades its Coherence version (even for a minor patch update), it is recommended to recompile the application code against the new Coherence version.

Ideally, recompiling the application should also include a full continuous integration build and test run. Coherence APIs are guaranteed to be downward-compatible for patch releases, but they may not be binary compatible. This means that an application should not require code changes for a minor Coherence patch upgrade, but it may require recompilation to work correctly.

Application developers should always consult the release notes when upgrading Coherence, they should especially check for deprecations so that application code can be changed to use alternatives. Deprecated code is not removed in a patch but may be removed in a major Coherence upgrade.

Every class that will be sent over the network between different JVMs in the application must be serializable, using either the default Coherence serialization (Java) or POF serialization. This applies to both cluster members and Coherence client processes.

When upgrading to a new version of an application where classes have changed, there are a number of rules to consider depending on how the classes are used, which are detailed in the following sections. For example, Cache Keys and Values.

Although Java serialization is the default serializer used in Coherence, application that require seamless upgrades should be using Coherence POF instead. Java serialization is not downward-compatible without significant effort and is not properly evolvable. POF, on the other hand, can be written to be down- and upward-compatible, and is fully evolvable as well as platform independent.

You cannot change the serializer used by a cache service in a rolling upgrade. For example, an application cannot change from Java serialization to POF serialization.

• Adding or Removing Classes
  Take care when adding or removing classes during upgrades.
• Enum Classes
  If you use enum types in applications, then the same rules that apply to normal classes also apply to enum classes. plus some additional considerations.

You must take into consideration how changes to cache keys and values may affect serialization.

If an application uses custom entry processors, then these need to be compatible across versions. This includes serialization evolvability, ideally using POF serialization.

An entry processor must return the same result type as the previous version (or a compatible sub class of that type). An entry processor may be executed during an upgrade, so the caller on the old version of the application would expect to receive the same result type.

If the new version of an entry processor introduces new fields, the code in the process method must allow for those fields to be null (or some other default set during deserialization). If an old version of the application executed the entry processor, then it will not have been able to set those new fields, so if the processor executes on a storage member with the new version of the class, the fields will be missing when deserialized.

A new version of an entry processor should still populate fields of the old version if those fields are mandatory for the old version to execute without failure.

Introducing a new entry processor class can only be done if it can be guaranteed that the processor will not be executed until all the storage enabled cluster members have been upgraded. If a new version of the application tries to invoke an entry processor and that invoke call targets a storage member running the old version of the code, then the caller will receive an exception with a root cause of ClassNotFoundException.

Removing an existing entry processor class from an application should only be done when it can be guaranteed no parts of the application will try to invoke that entry processor.

If an application uses custom filter implementations, they must be compatible across versions. This includes serialization evolvability, ideally using POF serialization.

Filters can be used to register for events using MapListener so they must have a suitable implementation of equals and hashCode. If these methods change so that a new implementation does not equal an old implementation, then the application may not receive the correct events or may receive no events.

If a new filter implementation introduces new fields, the filter methods must be able to execute when that field is not set. If an old version of the application executes a method using the old version of the filter, when it is deserialized for execution on a cluster member running the new version, those fields will not be set. The new version should allow for this or should set suitable default values in its constructor or when deserialized.

Introducing new filter classes can only be done if it can be guaranteed that the new filter class will not be used until all of the storage enabled cluster members have been upgraded. If a new version of the application tries to execute a cache query, add a MapListener, or any other operation involving the new filter class, that operation will fail if it executes on a cluster member that is not yet upgraded.

Custom filter implementations can only be removed once it can be guaranteed that no existing versions of the application will execute methods requiring those filters during the upgrade.

If an application uses custom aggregators, then these should be compatible across versions. This includes serialization evolvability, ideally using POF serialization.

The new version of the aggregator should also return the same result type as previous versions. If an application code executing the old version of the application invokes the aggregator and the aggregator runs on a storage member running the new version, the calling code will expect to receive the same result type (or a compatible sub-class of that result type).

The aggregators partial result type must also remain compatible across versions. As the aggregator runs the reduce phase where the results from different members are collected and reduced to a single result, the member running the reduction could receive partial results from storage members running different versions of the aggregator.

If the new version of an aggregator class introduces new fields, the aggregator must still work if those fields are not set during deserialization, or it should set suitable default values in the constructor or when deserialized. If during upgrade the aggregator is invoked from an old version of the application and executes on a storage member running the new version, the new fields will not be present when deserializing.

Introducing a new aggregator class can only be done if it can be guaranteed that the aggregator will not be executed until all the storage enabled cluster members have been upgraded. If a new version of the application tries to invoke an aggregator and that invoke call targets a storage member running the old version of the code, then the caller will receive an exception with a root cause of ClassNotFoundException.

Custom aggregator implementations can only be removed once it can be guaranteed that no existing versions of the application will execute methods requiring those aggregators during the upgrade.

If an application uses custom extractors, these should be serialization compatible. Adding or removing fields must be done in an evolvable way, ideally using POF evolvability.

Extractors that are used to extract a type to be returned to a calling application should return the same type as the previous version.

Value extractors are used to define indexes in Coherence. A specific index is identified from a Map keyed by the value extractor. If the implementation of a value extractor changes, such that it is not correctly equal to the previous version, then this could cause indexes not to be used or maybe even the wrong index could be used.

Introducing a new value extractor class can only be done if it can be guaranteed that the value extractor will not be executed until all the storage enabled cluster members have been upgraded. If a new version of the application tries to invoke a value extractor and that invoke call targets a storage member running the old version of the code, then the caller will receive an exception with a root cause of ClassNotFoundException.

Custom value extractor implementations can only be removed once it can be guaranteed that no existing versions of the application will execute methods requiring those value extractors during the upgrade.

Lambdas use in Coherence APIs must be treated like any other class in a Coherence application. Typically, a lambda used as a Coherence API method parameter means the lambda will be serialized and sent to the server to be executed.

Coherence uses lambdas in two ways, dynamic lambdas and static lambdas. For dynamic lambdas, both the lambda state and the code are serialized and sent to the server to be executed. For static lambdas, only the state is serialized and the lambda code must exist on the server already.

To fully support rolling upgrades, you should use dynamic lambdas. See Processing Entries Using Lambda Expressions.

Coherence topics, like caches, store serialized data on the server. The classes used for values published to topics should be serialization compatible and evolvable.

During a rolling upgrade, a topic will continue to work without loss of published elements. If the upgrade involves upgrading application JVMs containing topic subscribers, then this will cause uncommitted elements to be resent to new subscribers as the old application members are shutdown. Coherence guarantees at least one delivery, so application code that processes messages should alway be written to be idempotent to allow for messages to be received more than once. See Using Portable Object Format.

Applications that use cache loaders or cache stores to access an external data source must still be able to load data from and write data to the external data source.

Writing evolvable database schemas is far beyond the scope of this documentation, but if a database schema is updated as part of an application upgrade, there may still be cluster members running the old version of the code trying to read from or write to the new database schema.

Cache stores are application code and hence can interact with anything, not just a database, so any changes to the external data sources used by cache stores must be downward and upward compatible.

Client application code (both Extend and gRPC) must be written to have downward and upward compatible functionality. Although Coherence itself guarantees clients can connect to Coherence clusters on different versions (including different major versions), application code must be written to support this.

Client application code must also be written to survive disconnection, which will happen during a rolling upgrade. Coherence will reconnect a client automatically on the next request during a rolling upgrade, but any request that was in-flight when the client was disconnected may throw an exception on the client. In-flight requests may actually complete on the server, so applications that re-try failed requests must make sure these requests are idempotent, that is, they can safely be replayed more than once. For example, a put request from a client that is in progress on the storage member when the proxy is killed may throw an exception on the client, but the put will succeed on the storage member. If the client retries the put, the put will happen twice. This may be fine, but side-effects of the put will occur twice, for example, applications that perform other processing based on events would receive two events for that entry.

There are a number of things that can be changed in a cache configuration file as part of an upgrade. There are also things that cannot be changed without a full cluster shutdown.

A few examples to consider:

• Adding Caches - A new version of an application may require a new cache to be created. If the cache configuration file in the old version does not have a mapping for the new cache, the upgrade could fail.

• Removing Caches - If a cache mapping is removed, then this can cause an exception when a cluster member using the new version of the configuration receives a cache create request from a member running the old version of the application.

• Change Cache Types - It is not always possible to change the type of a cache in a rolling upgrade. For example, you cannot change from a legacy replicated cache to a distributed cache. Some cache types can be changed, for example, it would be possible to change to use a near cache on a new version of the application, as this is local to the new JVM.

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

<caching-scheme-mapping>
    <cache-mapping>
      <cache-name>foo</cache-name>
      <scheme-name>storage</scheme-name>
    </cache-mapping>

    <cache-mapping>
      <cache-name>bar</cache-name>
      <scheme-name>storage</scheme-name>
    </cache-mapping>
</caching-scheme-mapping>

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

<caching-scheme-mapping>
    <cache-mapping>
      <cache-name>*</cache-name>
      <scheme-name>storage-scheme</scheme-name>
    </cache-mapping>
</caching-scheme-mapping>

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

 <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>foo-*</cache-name>
      <scheme-name>foo-storage</scheme-name>
    </cache-mapping>

    <cache-mapping>
      <cache-name>bar-*</cache-name>
      <scheme-name>foo-storage</scheme-name>
    </cache-mapping>
</caching-scheme-mapping>

There are a number of Coherence configuration items that can be changed in the Operational Configuration file (or override file) some of which can be changed in a rolling update and some cannot.

Security in Coherence has a number of features:

• SSL/TLS changes for cluster members

• SSL/TLS changes for Extend and gRPC clients

• Identity assertion

• Storage access authorization

See Introduction to Oracle Coherence Security in Securing Oracle Coherence.

Applications that use Coherence persistence should ensure that the classes used for cache keys and values are serialization compatible and evolvable.

If a cluster member tries to read persistence files stored by a different version of the application, this may fail if the data is not compatible. The actual issues may not be immediately visible as the serialized binary data will be read from files and loaded into the cache in its serialized binary form, but the application will later fail when it tries to deserialize that data.

For more information, see:

• Using Portable Object Format

• Persisting Caches in Administering Oracle Coherence

<persistence-environments>
   <persistence-environment id="oldEnviornment">
      <persistence-mode>on-demand</persistence-mode>
      <active-directory>/oldEnv</active-directory>
      <snapshot-directory>/oldEnv</snapshot-directory>
      <trash-directory>/oldEnv</trash-directory>
   </persistence-environment>
</persistence-environments>

<persistence-environments>
   <persistence-environment id="newEnviornment">
      <persistence-mode>on-demand</persistence-mode>
      <active-directory>/newEnv</active-directory>
      <snapshot-directory>/newEnv</snapshot-directory>
      <trash-directory>/newEnv</trash-directory>
   </persistence-environment>
</persistence-environments>

Federation copies data between different Coherence clusters. The classes used in federated cache keys and values must be evolvable across the versions so that data can successfully be sent between different clusters.

For general information on using federation in Coherence, see Federating Caches Across Clusters in Administering Oracle Coherence.

In addition to the general considerations for upgrade such as JDK upgrade, Lambda, serialization compatibility, and so on, you must also consider aspects specific to federation.

The executor service that is part of the Coherence Concurrent module executes tasks remotely in the Coherence cluster. These tasks are serialized and sent to other cluster members for execution, so they must be evolvable like any other class sent over the network in Coherence.

For more information, see Using Executors.