Oracle Coherence is a scalable, fault-tolerant, cloud-ready, distributed platform for building grid-based applications and reliably storing data. The product is used at scale, for both compute and raw storage, in a vast array of industries such as critical financial trading systems, high performance telecommunication products and e-commerce applications.

Micronaut features dedicated support to bootstrap Coherence and for both injection of Coherence resources into beans and injection of beans into Coherence resources. Micronaut Injection simplifies application code as Coherence maps, caches and topics are just injected instead of being obtained via Coherence APIs.

Using annotated event listener methods simplifies building reactive code that responds to Coherence cache events.

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-coherence/releases

Important Changes in Release 5.0.0

The following outlines backwards-incompatible changes made in this release:

gRPC

Coherence Configuration Client

To add support for Oracle Coherence to an existing project, you should first add the Micronaut Coherence configuration to your build configuration. For example:

Next, you also need to add the version of Coherence that your application will be using. For example, to use Coherence CE:

There is no minimal configuration required to bootstrap Coherence. If no specific configuration is provided Coherence will run with default values. Some Coherence functionality can be configured using System properties. Add these properties to the application configuration file, for example:

The above configuration sets the cluster name to test-cluster, and the role name to storage. Any Coherence system property (prefixed with coherence.) specified in the Micronaut configuration will then be picked up by Coherence at runtime.

The default behavior of the Coherence Micronaut framework is to use the Coherence bootstrap API introduced in Coherence CE 20.12 to configure and create Coherence instances. This means that Coherence resources in a Micronaut application are typically owned by a Coherence Session.

By default, Coherence will start a single Session configured to use the default Coherence configuration file. This behaviour can easily be configured, either traditionally using Coherence system properties or using explicit Micronaut configuration.

The simplest configuration, applicable to the majority of applications that only require a single Session, is to just configure and use the default Session. If the application is a Coherence cluster member, or a Coherence*Extend client, then all that needs to be specified is the Coherence configuration file name (although even this is optional as Coherence will use a default file name if none is configured). Alternatively, if the application is a Coherence gRPC client, the default Session can be configured as a gRPC Session (see the Coherence gRPC).

As already mentioned in the Quick Start section, the name of the Coherence configuration file for the default session can be set in the Micronaut config, for example in the application configuration file:

In the above configuration, the coherence section contains a sessions section which is the configuration of one or more sessions. The format is a map using the session name as the map key. In the above example there is a single session with the name default.

In the example below, there are two sessions configured, one named catalog and one named customer:

In this example, there will be two sessions, one named catalog and the default session.

There are a number of fields that may be used to configure a Session, all of them are optional.

Micronaut Data is a database access toolkit that uses Ahead of Time (AoT) compilation to pre-compute queries for repository interfaces that are then executed by a thin, lightweight runtime layer.

Micronaut Data is inspired by GORM and Spring Data, however improves on those solutions in the following ways:

This integration allows using Coherence as a data source for a Micronaut repositories

In addition to the above, this library provides abstract synchronous and asynchronous repositories that expose the power of Coherence when not using generated queries.

This documentation assumes with principals of Micronaut Data as described here.

As Coherence is ultimately a key/value store, there are some limitations using the generated query facility offered by Micronaut.

The following auto generated query types/features are not supported

Micronaut, and dependency injection in general, make it easy for application classes to declare the dependencies they need and let the runtime provide them when necessary. This makes the applications easier to develop, test and reason about, and the code extremely clean.

Micronaut Coherence allows you to do the same for Coherence objects, such as Session, NamedMap, NamedCache, ContinuousQueryCache, ConfigurableCacheFactory, Cluster, etc…​

Coherence NamedMap and NamedCache instances can be injected as beans in Micronaut applications. The mechanics of injecting NamedMap or NamedCache beans is identical, so any use of NamedMap in the examples below can be replaced with NamedCache. Other more specialized forms of NamedMap and NamedCache can also be injected, for example the asynchronous forms of both classes, and views.

The simplest way to inject a NamedMap is to just annotate the injection point with @jakarta.inject.Inject.

In this example the injection point field name is used to determine the cache name to inject, so a NamedMap bean with an underlying cache name of people will be injected.

It is possible to inject the asynchronous classes AsyncNamedMap and AsyncNamedCache as beans in exactly the same way as described above. Just change the type of the injection point to be AsyncNamedMap or AsyncNamedCache.

View (or ContinuousQueryCache) beans can be injected by specifying the @View annotation at the injection point. A view is a sub-set of the data in an underlying cache, controlled by a Filter.

In the above example, no Filter has been specified, so the default behaviour is to use an AlwaysFilter. This means that the view will contain all the entries from the underlying cache (typically a distributed cache). As a ContinuousQueryCache will hold keys and values locally in deserialized form this can often a better approach than using a replicated cache.

Coherence NamedTopic instances can be injected as beans in Micronaut applications.

An alternative way to write message driven applications and TransferEvent`microservices instead of directly injecting `NamedTopic, Publisher or Subscriber beans is to use Micronaut Coherence Messaging.

The simplest way to inject a NamedTopic is to just annotate the injection point with @jakarta.inject.Inject.

In this example the injection point field name is used to determine the topic name to inject, so a NamedTopic bean with an underlying topic name of people will be injected.

As an alternative to using a NamedTopic directly in code, Coherence Micronaut also supports annotating methods directly as publishers and subscribers using the same approach as Micronaut Messaging. See the Micronaut Messaging with Coherence Topics section of the documentation.

If application code only needs to publish messages to a Coherence NamedTopic then instead of injecting a NamedTopic bean, a Publisher bean can be injected.

The simplest way to inject a Publisher is just to annotate the injection point of type Publisher with @Inject, for example:

The example above will inject a Publisher bean, the name of the underlying NamedTopic will be taken from the name of the injection point, in this case orders.

If application code only needs to subscribe to messages from a Coherence NamedTopic then instead of injecting a NamedTopic bean, a Subscriber bean can be injected.

The simplest way to inject a Subscriber is just to annotate the injection point of type Subscriber with @Inject, for example:

The example above will inject a Subscriber bean, the name of the underlying NamedTopic will be taken from the name of the injection point, in this case orders.

A Subscriber can filter the messages that it receives from the NamedTopic by using a Filter. Filtering of messages takes place on the server, so for use cases where the application is only interested in a sub-set of messages, this can be more efficient than bringing all messages back to the client for processing.

Filters are specified for a Subscriber using a special filter binding annotation. These are annotations that are themselves annotated with the meta-annotation @FilterBinding. The Micronaut Coherence framework comes with some built in implementations, for example @AlwaysFilter, and @WhereFilter, and it is simple to implement other as required by applications (see the Filter Binding Annotation section for more details).

For example, both of the code snippets below inject a Subscriber that subscribe to the orders topic, but only receives Order messages where the productId attribute is AB1234. the @WhereFilter filter binding annotation is used to specify the Filter, as @WhereFilter takes a Coherence CohQL where clause and converts it to a Filter.

A Subscriber can be configured to receive just a part of a NamedTopic message using a ValueExtractor. The message transformation happens on the server so in use-cases where a Subscriber only requires a part of a message, it can be much more efficient to extract the required parts on the server instead of bringing the full payload back to the client.

ValueExtractors are specified for a Subscriber using a special extractor binding annotation. These are annotations that are themselves annotated with the meta-annotation @ExtractorBinding. The Micronaut Coherence framework comes with some built in implementations, for example @PropertyExtractor, and @PofExtractor, and it is simple to implement other as required by applications (see the Extractor Binding Annotation section for more details).

For example, assuming that there is a topic named orders containing Order instances as the payload. If a Subscriber is required to subscribe to the orders topic, but only needs to receive the productId values, then a @PropertyExtractor annotation could be used. A @PropertyExtractor specifies the name of a property to extract.

Both code snippets below will inject a Subscriber that just receives the productId property of Orders objects from the orders topic.

Sometimes it might not be possible to inject a Coherence resource, such as NamedMap or NamedCache directly because the name of the resource to be injected is not known until runtime. In this case it makes sense to inject a Session instance which can then be used to obtain other resources.

The simplest way to inject a Session is just to annotate a field, method parameter, or other injection point.

or into a constructor:

Both examples above will inject the default Session instance into the injection point.

Event driven patterns are a common way to build scalable applications and microservices. Coherence produces a number of events that can be used by applications to respond to data changes and other actions in Coherence.

There are two types of events in Coherence. There are MapEvents, that in a traditional Coherence application are subscribed to using MapListener and there are a number of different types of Event, that are in a traditional Coherence application are subscribed to using an EventInterceptor.

Micronaut makes subscribing to both of these event types much simpler, using observer methods annotated with @CoherenceEventListener.

For example,

The method above receives all events of type CoherenceLifecycleEvent emitted during the lifetime of the application.

The actual events received can be controlled further by annotating the method or parameter.

Listening for changes to data in Coherence is a common use case in applications. Typically, this involves creating an implementation of a MapListener and adding that listener to a NamedMap or NamedCache. Using Coherence Micronaut makes this much simpler by just requiring Micronaut beans with suitably annotated observer methods that will receive events.

There are three types of event that a MapEvent observer method can receive, Insert, Update and Delete. By default, an observer method will receive all events for the map (or maps) it applies to. This can be controlled using the following annotations:

Zero or more of the above annotations can be used to annotate the MapEvent parameter of the observer method.

For example,

All events for the map test will be received.

The MapEvents received by an observer method can be further restricted by applying a filter. Filters are applied by annotating the method with a filter binding annotation, which is a link to a factory that creates a specific instance of a Filter. Event filters applied in this way are executed on the server, which can make receiving events more efficient for clients as the event will not be sent from the server at all.

The Micronaut Coherence framework comes with some built in implementations, for example @AlwaysFilter, and @WhereFilter, and it is simple to implement other as required by applications (see the Filter Binding Annotation section for more details).

For example, assume there is a map named people with keys of type String and values of type People, and an observer method needs to receive events for all values where the age property is 18 or over. A custom filter binding annotation could be written to create the required Filter, but as the condition is very simple, in this example the built in @WhereFilter filter binding annotation will be used with a where clause of age >= 18.

The onAdult method above will receive all events emitted from the people map, but only for entries where the value of the age property of the entry value is >= 18.

In some use-cases the MapEvent observer method does not require the whole map or cache value to process, it might only require one, or a few, properties of the value, or it might require some calculated value. This can be achieved by using an event transformer to transform the values that will be received by the observer method. The transformation takes place on the server before the event is emitted to the method. This can improve efficiency on a client in cases where the cache value is large but the client only requires a small part of that value because only the required values are sent over the wire to the client.

In the Coherence Micronaut framework, event values are transformed using a ValueExtractor. A ValueExtractor is a simple interface that takes in one value and transforms it into another value. The ValueExtractor is applied to the event value; events contain both a new and old values and the extractor is applied to both as applicable. For Insert events there is only a new value, for Update events there will be both a new and old value and for Delete events there will only be an old value. The extractor is not applied to the event key.

The ValueExtractor to use for a MapEvent observer method is indicated by annotating the method with an extractor binding annotation. An extractor binding is an annotation that is itself annotated with the meta-annotation @ExtractorBinding. The extractor binding annotation is a link to a corresponding ExtractorFactory that will build an instance of a ValueExtractor.

For example, assuming that there is a NamedMap with the name orders that has keys of type String and values of type Order; the Order class has a customerId property of type String. A MapEvent observer method is only interested in the customerId for an order so the built-in extractor binding annotation @PropertyExtractor can be used to just extract the customerId from the event:

It is possible to apply multiple filter binding annotations to a method. In this case the extractors are combined into a Coherence ChainedExtractor, which will return the extracted values as a java.util.List.

Expanding on the example above, if the Order class also has an orderId property of type Long, and an observer method, only interested in Insert events needs both the customerId and orderId, then the method can be annotated with an two @PropertyExtractor annotations:

Coherence produces many events in response to various serverside and client side actions. For example, Lifecycle events for Coherence itself, maps and cache, Entry events when data in maps and caches changes, Partition events for partition lifecycle and distribution, EntryProcessor events when invoked on a map or cache, etc. In a stand-alone Coherence application these events are subscribed to using a EventInterceptor implementation registered to listen to specific event types.

The Coherence Micronaut API makes subscribing to these events much simpler, by using the same approach used for Micronaut events, namely annotated event observer methods. A Coherence event observer method is a method annotated with @CoherenceEventListener that has a void return type and a single parameter of the type of event to be received. The exact events received can be further controlled by applying other annotations to the method or event parameter. The annotations applied will vary depending on the type of the event.

CoherenceLifecycleEvents are emitted to indicate the lifecycle of a Coherence instance.

To subscribe to CoherenceLifecycleEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type CoherenceLifecycleEvent.

CoherenceLifecycleEvent are emitted by Coherence instances and will only be received in the same JVM, which could be a cluster member or a client.

For example, the onEvent method below will receive lifecycle events for all Coherence instances in the current application:

SessionLifecycleEvents are emitted to indicate the lifecycle event of a Session instance.

To subscribe to SessionLifecycleEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type SessionLifecycleEvent.

SessionLifecycleEvent are emitted by Session instances and will only be received in the same JVM, which could be a cluster member or a client.

For example, the onEvent method below will receive lifecycle events for all Session instances in the current application:

LifecycleEvent are emitted to indicate the lifecycle of a ConfigurableCacheFactory instance.

To subscribe to LifecycleEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type LifecycleEvent.

LifecycleEvent are emitted by ConfigurableCacheFactory instances and will only be received in the same JVM, which could be a cluster member or a client.

For example, the onEvent method below will receive lifecycle events for all ConfigurableCacheFactory instances in the current application:

CacheLifecycleEvent are emitted to indicate the lifecycle of a cache instance.

To subscribe to CacheLifecycleEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type CacheLifecycleEvent.

For example, the onEvent method below will receive lifecycle events for all caches.

An EntryEvent is emitted when a EntryProcessor is invoked on a cache. These events are only emitted on the storage enabled member that is the primary owner of the entry that the EntryProcessor is invoked on.

To subscribe to EntryEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type EntryEvent.

For example, the onEvent method below will receive entry events for all caches.

An EntryProcessorEvent is emitted when a mutation occurs on an entry in a cache. These events are only emitted on the storage enabled member that is the primary owner of the entry.

To subscribe to EntryProcessorEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type EntryProcessorEvent.

For example, the onEvent method below will receive entry events for all caches.

A TransactionEvent is emitted in relation to all mutations in a single partition in response to executing a single request. These are commonly referred to as partition level transactions. For example, an EntryProcessor that mutates more than one entry (which could be in multiple caches) as part of a single invocation will cause a partition level transaction to occur encompassing all of those cache entries.

Transaction events are emitted by storage enabled cache services, they will only e received on the same member that the partition level transaction occurred.

To subscribe to TransactionEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type TransactionEvent.

For example, the onEvent method below will receive all transaction events emitted by storage enabled cache services in the same JVM.

A TransferEvent captures information concerning the transfer of a partition for a storage enabled member. Transfer events are raised against the set of BinaryEntry instances that are being transferred.

To subscribe to TransferEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type TransferEvent.

For example, the onEvent method below will receive all transaction events emitted by storage enabled cache services in the same JVM.

An UnsolicitedCommitEvent captures changes pertaining to all observed mutations performed against caches that were not directly caused (solicited) by the partitioned service. These events may be due to changes made internally by the backing map, such as eviction, or referrers of the backing map causing changes.

Unsolicited commit events are emitted by storage enabled cache services, they will only e received on the same member.

To subscribe to UnsolicitedCommitEvent simply create a Micronaut bean with a listener method annotated with @CoherenceEventListener. The method should have a single parameter of type UnsolicitedCommitEvent.

For example, the onEvent method below will receive all Unsolicited commit events emitted by storage enabled cache services in the same JVM.

Micronaut Coherence integration provides support for message driven applications by integrating Micronaut Messaging and Coherence topics.

A Coherence NamedTopic is analogous to a queue or pub/sub topic, depending on the configuration and application code. Messages published to the topic are stored in Coherence caches, so topics are scalable and performant.

A typical stand-alone Coherence application would create a NamedTopic along with Publisher or Subscriber instances to publish to or subscribe to topics. Injection of topics into Micronaut applications is already covered in Injecting NamedTopics. With Micronaut messaging this becomes much simpler.

With Micronaut Coherence Messaging publishers and subscribers beans are created by writing suitably annotated interfaces.

To create a topic Publisher that sends messages you can simply define an interface that is annotated with @CoherencePublisher.

For example the following is a trivial @CoherencePublisher interface:

At compile time Micronaut will produce an implementation of the above interface. You can retrieve an instance of ProductClient either by looking up the bean from the ApplicationContext or by injecting the bean with @Inject:

Note that since the sendProduct method returns void this means the method will send the message and block until the message has been sent. You can return a Future to support non-blocking message delivery.

To listen to Coherence topic messages you can use the @CoherenceTopicListener annotation to define a message listener.

The following example will listen for messages published by the ProductClient in the previous section:

On any @@CoherenceTopicListener method that returns a value, you can use the @SendTo annotation to forward the return value to the topic or topics specified by the @SendTo annotation.

The key of the original ConsumerRecord will be used as the key when forwarding the message.

You can also do the same using Reactive programming:

Filter binding annotations are normal annotations that are themselves annotated with the @FilterBinding meta-annotation. A filter binding annotation represents a Coherence Filter and is used to specify a Filter in certain injection points, for example a View (CQC), NamedTopic Subscriber beans, event listeners, etc.

There are three parts to using a filter binding:

For example; assume there is a Coherence NamedMap with the name people that contains Person instances for the value. Among the various properties on the Person class is a property called gender and property called age. Now assume we want to inject a view that only shows adult males, we would need a Filter that has a condition like `gender == "male" && age > 18".

ValueExtractor binding annotations are normal annotations that are themselves annotated with the @ExtractorBinding meta-annotation. An extractor binding annotation represents a Coherence ValueExtractor and is used to specify a ValueExtractor in certain injection points, for example a View (CQC), NamedTopic Subscriber beans, MapEvent listeners, etc.

There are three parts to using an extractor binding:

For example; assume there is a Coherence NamedMap with the name people that contains Person instances for the value. Among the various properties on the Person class is a property called age. Now assume we want to inject a view that uses the age property for the value, we would need a ValueExtractor that extracts the age property.

Using Micronaut to inject Coherence objects into your application classes, and Micronaut beans into Coherence-managed objects will allow you to support many use cases where dependency injection may be useful, but it doesn’t cover an important use case that is somewhat specific to Coherence.

Coherence is a distributed system, and it uses serialization in order to send both the data and the processing requests from one cluster member (or remote client) to another, as well as to store data, both in memory and on disk.

Processing requests, such as entry processors and aggregators, have to be deserialized on a target cluster member(s) in order to be executed. In some cases, they could benefit from dependency injection in order to avoid service lookups.

Similarly, while the data is stored in a serialized, binary format, it may need to be deserialized into user supplied classes for server-side processing, such as when executing entry processors and aggregators. In this case, data classes can often also benefit from dependency injection (in order to support Domain-Driven Design (DDD), for example).

While these transient objects are not managed by the Micronaut container, Coherence Micronaut does support their injection during deserialization, but for performance reasons requires that you explicitly opt in by implementing com.oracle.coherence.inject.Injectable interface.

You can inject Micronaut beans into the standard Coherence cache configuration file by using the Coherence Micronaut custom namespace handler.

Custom namespace handlers are a standard feature of Coherence that allow the cache configuration file to be customized considerably.

The Coherence Micronaut custom namespace handler provides a single additional XML element named <bean> that is used to declare a named Micronaut bean for injection into the configuration.

To use the Coherence Micronaut custom namespace handler it must be declared in the XML configuration file alongside the other XSD values:

The <bean> element can be used anywhere in the configuration that an instance element would be used, for example when declaring interceptors, cache stores, listeners, etc.

For examples, with the following entry event interceptor:

This bean can be referenced in the cache configuration file, for example as an interceptor in a cache mapping:

To use Coherence as a Micronaut HTTP session store add the micronaut-coherence-session dependency:

Also, add a Coherence dependency - either Coherence CE or commercial version:

Enable Coherence sessions via configuration in the application configuration file:

Coherence cache will be obtained using default Coherence session.

In case that cache is configured to use POF serialization, additional POF configuration for the class io.micronaut.coherence.httpsession.CoherenceSessionStore$CoherenceHttpSession has to be added to the POF config. User can pick appropriate value for type-id.

To use Coherence as the caching implementation, add it as a dependency to your application:

Also, add Coherence dependency - either Coherence CE or commercial version:

When using the @Cacheable and other Cache Annotations, Micronaut will use default Coherence session to obtain cache instance for caching. It’s up to the user to configure Coherence specific cache.

You can also add Coherence module to your project using mn CLI feature:

To disable Coherence:

To use Coherence to store configuration values, add following dependencies:

Also, add Coherence dependency - either Coherence CE or commercial version:

To enable support simply add the following configuration to your bootstrap configuration file:

This will create a configuration client using the session named client to connect to a Coherence proxy server over extend and allow the application to lookup property sources for the application from Coherence.