Coherence Spring Core

As mentioned previously, Spring a has a special relationship with Map implementations. In order to work around this limitation, we provide the meta-annotations @CoherenceCache, @CoherenceMap etc. We apply a little trick using the @Value annotation and referencing the injection candidate via a SpEL expression. This in turn, however, triggers type conversion in Spring’s DefaultListableBeanFactory, and we must provide a no-op converter for Map-based Coherence objects using the CoherenceGenericConverter.

Without it, you may see Spring’s MapToMapConverter being used, which in turn will call Map#entrySet(), a potentially very expensive operation for large datasets in a Coherence cluster.

If the BeanFactory already contains a ConfigurableConversionService, we will add the CoherenceGenericConverter automatically using the CoherenceConversionServicePostProcessor. This should be typically the case with Spring Boot, which provides the ApplicationConversionService. If you provide your own ConversionService bean, we will back-off and a message to add the CoherenceGenericConverter manually will be logged.

In case no ConversionService is defined in your application context, PropertyEditors are being used, and that chain does not seem to trigger the same expensive operation, nonetheless using the ConversionService route is advised.

As already mentioned above, you specify the name of the map/cache using the value-property of the annotation. Of course, the same applies when injecting a constructor or method parameter:

If you prefer, you can also specify the name of the map/cache using the @Name annotation. The example below will inject a NamedMap that uses an underlying cache named people:

Whilst most applications probably use a single Coherence Session, there are uses-cases where an application may have multiple sessions. In this case, when injecting for example a NamedMap, the specific session can be specified by annotating the injection point with either @SessionName or more concise with the session parameter available for the following annotations:

In the previous examples where no separate Session name was specified, Coherence will use the default session to obtain the caches/maps. Assuming that the application has multiple sessions configured, one of which is named Catalog, the following example injects a NamedMap from an underlying cache named products in the Catalog session.

This can be further streamlined to:

The same annotation can be used on method parameter injection points as well:

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

For example, if there was a cache named "people", containing Person instances, and the application required a view of that cache to just contain People where the "lastName" attribute is equal to "Simpson", then the @WhereFilter filter binding annotation could be used to specify the Filter. The @WhereFilter annotation produces a Filter created from a Coherence CohQL where-clause, in this case lastName == 'Simpson'.

The above CohQL expression is still rather simple. Let’s further restrict the results:

The view injected above will be all People with a lastName attribute equal to Simpson and an age attribute greater than 10.

Other built-in or custom filter binding annotations can be combined as well and multiple filter-binding annotations can be added to the same injection point to build up more complex views. The Filter instances produced from each filter binding annotation will all be collected together in an AllFilter, which will logically combine them together.

The values in a view map do not have to be the same as the values in the underlying cache. Instead, a ValueExtractor can be used to transform the actual cache value into a different value in the view. ValueExtractors are specified for views using a special extractor binding annotation. These are annotations that are themselves annotated with the meta-annotation @ExtractorBinding. The Coherence Spring framework comes with some built in implementations, for example @PropertyExtractor, and it is simple to implement other as required by applications (see the Extractor Binding Annotation section for more details).

For example, if there was a cache named "people", containing Person instances, and the application required a view where the value was just the age attribute of each Person rather than the whole cache value. A @PropertyExtractor annotation could be used to specify that the values should be transformed using a property extractor.

Multiple extractor bindings can be applied to the injection point, in which case the view value will be a List of the extracted attributes.

For most applications that only use a single Session the simple examples above will be all that is required. Some applications though may use multiple named Session instances, in which case the Session name need to be specified. This can be done by adding the @Name annotation to the injection point.

or into a constructor:

The simplest way to inject a NamedTopic is to just annotate the injection point with @javax.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 Spring also supports annotating methods directly as publishers and subscribers. See the 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 MapEvent observer method is a method on a Spring bean that is annotated with @CoherenceEventListener. The annotated method must have a void return type and must take a single method parameter of type MapEvent, typically this has the generic types of the underlying map/cache key and value.

For example, assuming that there is a map/cache named people, with keys of type String and values of type Plant, and the application has logic that should be executed each time a new Plant is inserted into the map:

The above example is still rather simple. There are a number of other annotations that provide much finer-grained control over what events are received from where.

There are three types of event that a MapEvent observer method can receive:

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.

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.

Coherence Spring comes with some built in implementations, for example:

It is simple to implement custom filters as required by applications. Please refer to the Filter Binding Annotation section for more details.

For example, let’s 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. However, as the condition is very simple, the built-in @WhereFilter filter binding annotation will be used in this example 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 convert 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 Coherence Spring, 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. As events contain both a new and old values, 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 an 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 a two @PropertyExtractor annotations:

The different types of event that can be observed are listed below:

Most of the events above only apply to storage enabled cluster members. For example, an EntryEvent will only be emitted for mutations of an entry on the storage enabled cluster member that owns that entry. Lifecycle events on the other hand, may be emitted on all members, such as CacheLifecycle event that may be emitted on any member when a cache is created, truncated, or destroyed.

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

To subscribe to LifecycleEvent simply create a Spring bean with a listener method that is 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:

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

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

SessionLifecycleEvents 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:

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

To subscribe to CoherenceLifecycleEvent simply create a Spring 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:

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

To subscribe to CacheLifecycleEvent simply create a Spring 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 EntryProcessorEvent simply create a Spring 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 Spring 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 Spring 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 Spring 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 Spring 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.

The implementation will return a Mono that when subscribed to will subscribe to the passed Mono and send a message emitting the resulting Publisher.Status.

The implementation will return a Reactor Flux that when subscribed to will subscribe to the passed Flux and for each emitted item will send a message emitting the resulting Publisher.Status.

The implementation will return a Future with publisher’s status.

If no commitStrategy field has been provided to the @CoherenceTopicListener annotation the default behaviour is to synchronously call Element.commit() for every message received.

No commitStrategy field has been supplied to the @CoherenceTopicListener annotation.

The @CoherenceTopicListener commitStrategy field is an enumeration of type CommitStrategy with three values, SYNC, ASYNC and MANUAL.

In the example above a MANUAL commit strategy has used. The element will be committed by the application code at the end of the handler method. To be able to manually commit a message the method must take the Element as a parameter so that application code can access the commit methods.

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:

At its core (and in the coherence-cachestore-demo-core module), the application has a simple class called Person that is annotated with basic JPA annotations:

The identifier of a Person is defined as Long, so in our Coherence-based application we would put these Person instances into a Coherence NamedMap<Long, Person>.

To write a JPA repository CacheStore that can be used by our people cache we need to create a simple Spring Data repository interface:

That is all the code required to write a CacheStore that can be plugged into Coherence. Spring Data will take care of actually generating the implementation of the interface, and supplying that implementation as a bean.

In the embedded Coherence CacheStore demo we use a co-located Coherence instance that will start as part of the application itself.

To use a CacheStore in Coherence, it needs to be configured in the Coherence cache configuration file, which in the embedded use-case is coherence-cache-config.xml. In order to use the repository bean as a CacheStore, we will make use of the Coherence Spring feature that allows injection of Spring beans into the cache configuration file.

To use Spring bean injection in the configuration file we need to declare a custom namespace in the root XML element that references the Coherence Spring NamespaceHandler.

The xmlns:spring="class://com.oracle.coherence.spring.namespace.NamespaceHandler" line declares the custom namespace, so elements with a prefix spring will be handled by the com.oracle.coherence.spring.namespace.NamespaceHandler class. The custom namespace handler allows us to use elements of the form <spring:bean>bean-name</spring:bean> anywhere in the configuration that Coherence normally allows an <instance> element or a <class-scheme> element.

Thus, we can add a scheme to the <cache-schemes> section of the configuration that uses the repository bean.

In the snippet above you can see the <spring:bean>{repository-bean}</spring:bean> element used as the cache store. In this case we have not used the name of the repository bean directly, we have used a parameter named repository-bean (XML values in curly-brackets in the <spring:bean> element are treated as parameter macros). This allows us to map multiple caches to the same scheme each with a different cache store - this is quite a common approach in Coherence for a number of elements that may be configured in a scheme per-cache. We can now also add the cache mapping for our people cache that will use the scheme above.

In the mapping above, the cache name people maps to the scheme db-scheme that we created above. As we mentioned above, we need to pass the actual bean name in the repository-bean parameter, which we do by using the <init-params> element in the mapping. We set the <param-value> element to the bean name, in this case personRepository.

If we had another cache with a different cache store, for example if we had an entity called Location with a repository cache store class called LocationRepository, the bean name would default to locationRepository, and we could add the following mapping:

This sample is just a simple Spring Boot application that exposes two endpoints to create/update people and get people by id. The controller class for the two endpoints is very simple:

We use the Coherence Spring integration to inject a NamedMap into the controller. This will be for the cache named people, which we configured to use the cache store in the configuration above.

In the createPerson method we use the request parameters to create a Person and put it into the cache. The CacheStore will write this to the database.

In the getPerson method we retrieve the Person from the cache using the id from the request path, loading from the database if there is no entry in the cache for the id.

We can build the example using Maven from the root directory of Coherence Spring:

This will build a Spring Boot jar that we can run the normal Spring Boot ways, for example:

After the application has started we can try to get a Person using curl

This should return a 404 response because there is no person in the database or cache with the id 100.

We can create a Person using a curl POST request:

This will create the Person named Joe Smith with the id 100. This should return with a 200 response to say the Person was successfully created and will be stored in the database.

If we re-run the GET request we should get Joe Smith.

This is the slightly more complex version of the CacheStore demo. Instead of using an embedded version Coherence, we will have a remote Coherence instance and the actual application will connect to Coherence via Coherence*Extend.

We can build the example using Maven from the root directory of Coherence Spring:

We now have to start the Coherence Server as well as the Coherence Client App. We run both apps using Spring Boot. Let’s start with the Coherence Server:

Next we start the client app. It is actually the same app as used in the embedded Coherence use-case. However, we will specify an additional Spring Boot profile, instructing the app to connect to the Coherence server in client mode via Coherence*Extend:

By activating the remote Spring Boot profile, we will configure Coherence for client mode and we reference a different Cache Configuration XML file called remote-cache-config.xml.

In the remote Coherence CacheStore demo, HSQL will be instantiated via the server module. This allow the app as well as the server to access the HSQL database instance. That way we can also inspect the data in the data more easily as we can inspect the database data via SQL tools such as the open-source DBeaver.