This section dives into the Coherence Spring Core module. Coherence Spring Core provides the basic support for the Spring Framework.

1. Getting Started

To add support for Oracle Coherence to an existing Spring Framework project, you should first add the required Spring Coherence dependencies to your build configuration:

Example 1. Coherence Spring Dependencies
Maven
<dependency>
    <groupId>com.oracle.coherence.spring</groupId>
    <artifactId>coherence-spring-core</artifactId>
    <version>4.0.0-SNAPSHOT</version>
</dependency>
Gradle
implementation("com.oracle.coherence.spring:coherence-spring-core:4.0.0-SNAPSHOT")

Next you also need to add the version of Coherence that your application will be using. Coherence Spring is compatible with both the open source Coherence CE and the commercial version of Oracle Coherence. Therefore, we don’t bring in Oracle Coherence as transitive dependency. For example, to use Coherence CE specify:

Example 2. Oracle Coherence CE Dependency
Maven
<dependency>
    <groupId>com.oracle.coherence.ce</groupId>
    <artifactId>coherence</artifactId>
    <version>23.03</version>
</dependency>
Gradle
implementation("com.oracle.coherence.ce:coherence:23.03")

In order to use the commercial version of Coherence:

Example 3. Commercial Oracle Coherence Dependency
Maven
<dependency>
    <groupId>com.oracle.coherence</groupId>
    <artifactId>coherence</artifactId>
    <version>14.1.1.2206</version>
</dependency>
Gradle
implementation("com.oracle.coherence.ce:coherence:14.1.1.2206")
Coherence CE versions are available from Maven Central. The commercial versions of Coherence needs to be uploaded into your own Maven repository.
Coherence Spring requires as a minimum version Coherence CE 22.06.

2. Bootstrapping Coherence

Coherence Spring uses the Coherence bootstrap API introduced in Coherence CE 20.12 to configure and create Coherence instances. This means that Coherence resources in a Spring application are typically part of a Coherence Session.

By default, Coherence will start a single Session configured to use the default Coherence configuration file. This behavior can easily be configured using traditional Coherence using system properties or using dedicated configuration.

3. Using the Default Session

The main building block for setting up Coherence for Spring is the @EnableCoherence annotation. This annotation will import the CoherenceSpringConfiguration class under the covers. Therefore, you can alternatively also declare @Import(CoherenceSpringConfiguration.class) instead.

In most use-cases, only a single Coherence Session is expected to be used. Therefore, without providing any further configuration the default session is configured using the embedded default configuration file. This results in the application joining Coherence as a cluster member (Session type SERVER). This is of course not the only way. Coherence Spring support the following 3 session types:

  • SERVER - Join as Coherence cluster member. This is the default session type.

  • CLIENT - Connect to Coherence as a Coherence*Extend or gRPC client

  • GRPC - Connect to Coherence as gRPC client (deprecated, use CLIENT instead)

As of Coherence Spring 4.0, the GRPC session type has been deprecated. Please use CLIENT instead. Since Coherence 22.06.2, relevant gRPC configuration can be configured directly in the coherence-cache-config.xml file as described in the Coherence reference guide chapter Configuring the Coherence gRPC Client.

In order to configure the type of your Session, you may declare a SessionConfigurationBean that allows to you to not only to set the session type but also to specify a custom Coherence configuration file or a custom session name.

SessionConfigurationBean
 @Bean
 SessionConfigurationBean sessionConfigurationBeanDefault() {
     final SessionConfigurationBean sessionConfigurationBean =
             new SessionConfigurationBean();
     sessionConfigurationBean.setType(SessionType.SERVER);
     sessionConfigurationBean.setConfig("test-coherence-config.xml");
     return sessionConfigurationBean;
 }
The option of declaring a GrpcSessionConfigurationBean for gRPC clients has been deprecated. Please use session type CLIENT instead and configure the gRPC relevant configuration properties in your coherence-cache-config.xml file.

4. Configure Multiple Sessions

If you need to configure multiple Coherence sessions, simply define multiple SessionConfigurationBeans. The auto-configuration will pick those up automatically to configure the required sessions.

The default session will only exist when zero sessions are specifically configured, or the default session is specifically configured with the default session name.

5. Session Configuration Bean Properties

Depending on the session type the available properties change a bit. The following properties all to ALL session types.

name

The name of the session. If not set, it will be set to the default session name which is an empty String.

scopeName

A scope name is typically used in an application where the Coherence cluster member has multiple sessions. The scope name is used to keep the sessions separate. The scope name will be applied to the session’s underlying ConfigurableCacheFactory and used to scope Coherence services. In this way multiple session configurations may use identical service names, which will be kept separate using the scope. On a Coherence cluster member, each session should have a unique scope name.

type

The session type of this configuration. There are three different types of sessions that can be configured:

  • server represents storage enabled cluster member session.

  • client represents a storage disabled cluster member or Coherence*Extend client session.

  • grpc (deprecated) is a gRPC client session (see the gRPC documentation).

The type of the session affects how the bootstrap API starts the session.

As of Coherence Spring 4.0, the GRPC session type has been deprecated. Please use CLIENT instead. Since Coherence 22.06.2, relevant gRPC configuration can be configured directly in the coherence-cache-config.xml file as described in the Coherence reference guide chapter Configuring the Coherence gRPC Client.

priority

The priority specifies the order to use, when starting the session. Sessions will be started with the lowest priority first. If this property is not specified, the property will default to 0.

The following property applies to the CLIENT (Coherence*Extend) and Server mode, only:

configUri

The Coherence cache configuration URI for the session. As already mentioned, the most common configuration to set will be the Coherence configuration file name. If not specified, the default value will be coherence-cache-config.xml.

The following property applies to the deprecated GRPC mode, only:

channelName (deprecated)

Sets the underlying gRPC channel. If not set, it will default to localhost and port 1408. This property is deprecated. See note under type.

serializer (deprecated)

Specifies the serializer to that shall be used, in order to serialize gRPC message payloads. If not specified, the serializer will be the default Coherence serializer, either POF if it has been enabled with the coherence.pof.enabled system property or Java serialization. This property is deprecated. See note under type.

tracingEnabled (deprecated)

Specifies if client gRPC tracing should be enabled. This is false by default. This property is deprecated. See note under type.

6. Dependency Injection

Coherence Spring provides comprehensive support for the injection Coherence objects into your Spring beans including: Session, NamedMap, NamedCache, ContinuousQueryCache, ConfigurableCacheFactory, Cluster.

For the most part, you can use the equivalent Coherence Spring annotation that match the annotations from Coherence’s CDI or Micronaut support.

6.1. Injecting NamedMap and NamedCache

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

In Spring one caveat exists regarding the injection of Map-based classes that directly inherit from java.util.Map including NamedCache and NamedMap when using the @Autowired annotation. Instead of injecting actual instances of Beans representing a java.util.Collection or java.util.Map, Spring will inject a collection of all the beans that represent the specified bean type instead. As a work-around, you can use the @Resource annotation, but it has its own limitations, for instance, not being usable for constructor injection.

Example of using the @Resource annotation
    @Resource(name = COHERENCE_CACHE_BEAN_NAME)
    private NamedCache numbers;                  (1)

    @Resource(name = COHERENCE_CACHE_BEAN_NAME)
    @Name("numbers")                             (2)
    private NamedCache namedCache;
1 If not specified, the name of the field will be used to determine the cache name
2 Alternatively, you can specify the name of the cache using the @Name annotation
For more information, please see Fine-tuning Annotation-based Autowiring with Qualifiers in the Spring Framework reference guide.

In order to provide a better user-experience around the dependency injection of maps and caches, Coherence Spring introduces its own set of annotations. The following annotations are available:

  • @CoherenceCache

  • @CoherenceMap

  • @CoherenceAsyncCache

  • @CoherenceAsyncMap

Using these annotations, you can inject any Coherence NamedMap and NamedCache in any situation including constructors.

Furthermore, the annotations also give you some added conveniences such as the ability to specify the name of the cache, or the name of the Coherence session as part of the annotation. E.g., the above example can be simplified to:

Example of using the @CoherenceCache annotation
    @CoherenceCache
    private NamedCache numbers;                  (1)

    @CoherenceCache("numbers")                   (2)
    private NamedCache namedCache;
1 If not specified, the name of the field will be used to determine the cache name
2 Alternatively, you can specify the name of the cache using the @Name annotation

All the annotations @CoherenceCache, @CoherenceMap, @CoherenceAsyncCache, and @CoherenceAsyncMap are themselves annotated with @Lazy. This is to avoid deadlocks where a cache bean requires another bean to be injected in its configuration, which will happen on a different thread to the main Spring thread. A consequence of this is that all cache beans will be Spring lazy dynamic proxies.

6.1.1. Type Conversion of NamedMap and NamedCache

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.

When defining your own ConversionService bean, please make sure that the CoherenceGenericConverter is added to it.

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.

Manually adding the CoherenceGenericConverter
    @Bean
    public ConversionService conversionService() {
        DefaultFormattingConversionService conversionService =
            new DefaultFormattingConversionService();
        conversionService.addConverter(new CoherenceGenericConverter());   (1)
        return conversionService;
    }
1 Adding a new instance of the CoherenceGenericConverter

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.

6.1.2. Specify the Map/Cache Name

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:

Example of constructor injection of a NamedMap
@Service
public class SomeService {

    public SomeService(@CoherenceMap("people") NamedMap<String, Person> map) {
        // TODO: initialize the service...
    }
}
If injecting a cache/map via the constructor, AND you do not specify a cache/map name, then Coherence Spring will try to derive the name of the cache/map from the parameter name. However, this only works if either the compiler flag -parameters (Java 8+) is enabled, or if the JVM generates debugging info. For more information see the article Method Parameter Reflection in Java.

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:

Example of using the @Name annotation
@CoherenceMap
@Name("people")
private NamedMap<String, Person> map;

6.1.3. Specify the Owning Session Name

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:

  • @CoherenceCache

  • @CoherenceMap

  • @CoherenceAsyncCache

  • @CoherenceAsyncMap

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.

Example of using the @SessionName annotation
@CoherenceMap
@SessionName("Catalog")
@Name("products")
private NamedMap<String, Product> map;

This can be further streamlined to:

Example of using the @CoherenceMap annotation with the session parameter
@CoherenceMap(name="products", session="Catalog")
private NamedMap<String, Product> map;

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

Example of using @CoherenceMap with session parameter in a constructor
@Controller
public class CatalogController {

    public CatalogController(@CoherenceMap(name="products", session="Catalog")
                             NamedMap<String, Product> products) {
        // TODO: initialize the bean...
    }
}

6.2. Injecting AsyncNamedMap & AsyncNamedCache

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 using one of the following annotations:

  • @CoherenceAsyncCache

  • @CoherenceAsyncMap

Injecting an AsyncNamedMap
@CoherenceAsyncMap("people")
private AsyncNamedMap<String, Person> map;

6.3. Injecting Views (CQC)

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.

Injecting an AsyncNamedMap
@CoherenceMap("people")
@View                                            (1)
private NamedMap<String, Person> map;
1 The injection point has been annotated with @View, so the injected NamedMap will actually be an implementation of a ContinuousQueryCache.

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 be a better approach than using a replicated cache.

6.3.1. Specify a View Filter

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

Injecting a @CoherenceMap with @WhereFilter
    @CoherenceMap("people")                                  (1)
    @View                                                    (2)
    @WhereFilter("lastName = 'Simpson'")                     (3)
    private NamedMap<String, Person> allSimpsons;            (4)
1 The name of the underlying map for the view is "people".
2 The @View annotation specifies that a view will be injected rather than a raw`NamedMap`.
3 The @WhereFilter annotation specifies the CohQL expression.
4 The NamedMap contains only people with the last name Simpson.

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

@WhereFilter with a more complex CohQL expression
    @CoherenceMap("people")
    @View
    @WhereFilter("lastName = 'Simpson' and age > 10")        (1)
    private NamedMap<String, Person> simpsons;
1 The @WhereFilter also filters on the age property.

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

The Coherence reference guide has an in-depth chapter on CohQL and more details on the WHERE clause under Filtering Entries in a Result Set

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.

6.3.2. Specify a View Transformer

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.

Injecting a @CoherenceMap with multiple @WhereFilter
    @CoherenceMap("people")                                  (1)
    @View                                                    (2)
    @PropertyExtractor("age")                                (3)
    private NamedMap<String, Integer> ages;                  (4)
1 The name of the underlying map for the view is "people".
2 The @View annotation specifies that a view will be injected rather than a raw NamedMap.
3 The @PropertyExtractor annotation specifies that a ValueExtractor should be used to transform the underlying cache values into different values in the view. In this case the @PropertyExtractor annotation will produce a value extractor to extract the age property.
4 Note that the map injected is now a NamedMap<String, Integer> with generic types of String and Integer because the values have been transformed from Person to Integer.

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

6.4. Injecting a Session

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 to annotate a field, method parameter, or other injection point with your preferred Spring-supported injection annotation such as @Autowired or @Inject:

Injecting a Coherence Session instance
@RestController
public class MyBean {
    @Inject                                      (1)
    private Session session;
1 Other injection annotations such as @Autowired can be used as well
Injecting a Coherence Session using constructor injection
@RestController
public class MyBean {
    @Autowired                                   (1)
    public MyBean(Session session) {
        // TODO...
    }
}
1 If your class has only a single constructor, you can even omit the @Autowired annotation

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

6.4.1. Specify a Session Name

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.

Injecting a specific (named) Coherence Session
@RestController
public class MyBean {
    @Autowired                                   (1)
    @Name("Catalog")
    private Session session;
}
1 Other injection annotations such as @Inject can be used as well

or into a constructor:

Injecting a specific (named) Coherence Session via constructor
@RestController
public class MyBean {
    @Autowired                                   (1)
    public MyBean(@Name("Catalog") Session session) {
        // TODO...
    }
}
1 If your class has only a single constructor, you can even omit the @Autowired annotation

6.5. Injecting NamedTopic

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

An alternative way to write message driven applications instead of directly injecting NamedTopic, Publisher or Subscriber beans is to use Messaging with Coherence Topics.

6.5.1. Injecting NamedTopic

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

Inject NamedTopic
@Inject
private NamedTopic<Person> people;

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.

6.5.1.1. Specify the Topic Name

Sometimes the name of the topic being injected needs to be different to the injection point name. This is always the case when injecting into method parameters as the parameter names are lost by the time the injection point is processed. In this case we can use the @Name annotation to specify the underlying cache name.

The example below will inject a NamedTopic that uses an underlying topic named orders.

Use @Name to specify topic name
@Inject
@Name("people")
private NamedTopic<Order> orders;

The same applies when injecting a constructor or method parameter:

Use @Name to specify topic name on a parameter
@Singleton
public class SomeBean {
    @Inject
    public SomeBean(@Name("orders") NamedTopic<Order> topic) {
    // ToDo:
    }
}
6.5.1.2. Specify the Session Name

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 a NamedTopic the specific session can be specified by annotating the injection point with @SessionName.

In the previous examples where no @SessionName was specified Coherence will use the default session to obtain the caches.

For example, assume the application has multiple sessions configured, one of which is named Customers. The following code snippet injects a NamedTopic using an underlying topic named orders in the Customers session.

Use @SessionName to specify session
@Inject
@SessionName("Customers")
@Name("orders")
private NamedTopic<Order> topic;

Again, the same annotation can be used on method parameter injection points.

Use @SessionName to specify session on a method parameter
@Controller
public class OrderProcessor {
    @Inject
    public OrderProcessor(@SessionName("Customers") @Name("orders")
                          NamedTopic<Order> orders) {
        // ToDo:
    }
}

6.5.2. Injecting a NamedTopic Publisher

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:

Inject a Publisher
@Inject
private Publisher<Order> orders;

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.

6.5.2.1. Specify the Topic Name

If the name of the injection point cannot be used as the NamedTopic name, which is always the case with injection points that are method or constructor parameters, then the @Name annotation can be used to specify the topic name.

For example, both of the code snippets below inject a Publisher that published to the orders topic:

Inject a Publisher that publishes on the orders topic
@Inject
@Name("orders")
private Publisher<Order> orders;
Inject a Publisher that publishes on the orders topic
@Controller
public class OrderController {
    @Inject
    public OrderController(@Name("orders") Publisher<Order> topic) {
        // ToDo:
    }
}
6.5.2.2. Specify the Owning Session

As with injection of NamedTopics, in applications using multiple Session instances, the name of the Session that owns the underlying NamedTopic can be specified when injecting a Publisher by adding the @SessionName annotation.

Inject a Publisher while specifying the owning session
@Inject
@Name("orders")
@SessionName("Customers")
private Publisher<Order> orders;

6.5.3. Injecting a NamedTopic Subscriber

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:

Inject Subscriber
@Inject
private Subscriber<Order> orders;

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.

6.5.3.1. Specify the Topic Name

If the name of the injection point cannot be used as the NamedTopic name, which is always the case with injection points that are method or constructor parameters, then the @Name annotation can be used to specify the topic name.

For example, both of the code snippets below inject a Subscriber that subscribe to the orders topic:

Inject subscriber into field
@Inject
@Name("orders")
private Subscriber<Order> orders;
Inject subscriber into method parameter
@Controller
public class OrderController {
    @Inject
    public OrderController(@Name("orders") Subscriber<Order> topic) {
        // ToDo:
    }
}
6.5.3.2. Specify the Owning Session

As with injection of NamedTopics, in applications using multiple Session instances, the name of the Session that owns the underlying NamedTopic can be specified when injecting a Subscriber by adding the @SessionName annotation.

@Inject
@Name("orders")
@SessionName("Customers")
private Subscriber<Order> orders;

7. Events

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:

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

Example of using a Coherence Event Listener
@CoherenceEventListener
void onEvent(CoherenceLifecycleEvent event) {
    // TODO: process event...
}

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 the method arguments.

Spring 4.2 introduced Annotation-driven event listeners as part of its event support.

Coherence Spring does NOT directly use Spring’s ApplicationEvent class and the corresponding ApplicationListener interface. However, Coherence Spring follows that pattern conceptually in order to provide a similar user experience.

By default, the handling of Coherence events is asynchronous. Use the @Synchronous annotation to make the event handler execution synchronous.
Example of making a Coherence Event Listener synchronous
@CoherenceEventListener
@Synchronous
void onEvent(CoherenceLifecycleEvent event) {
    // TODO: process event...
}

7.1. MapEvent Listeners

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 Spring makes this much simpler by just using Spring beans with suitably annotated observer methods that will receive the respective events.

7.1.1. MapEvent Observer Methods

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:

Example of listening to Inserted events
import com.oracle.coherence.spring.annotation.event.Inserted;
import com.oracle.coherence.spring.annotation.event.MapName;
import com.oracle.coherence.spring.event.CoherenceEventListener;
import com.tangosol.util.MapEvent;
import org.springframework.stereotype.Component;

@Component                                       (1)
public class PersonEventHandler {

    @CoherenceEventListener                      (2)
    public void onNewPerson(@MapName("people")   (3)
                            @Inserted            (4)
                            MapEvent<String, Person> event) {
        // TODO: process the event
    }
}
1 The PersonController is a simple Spring bean, in this case a Controller.
2 The onNewPerson method is annotated with @CoherenceEventListener making it a Coherence event listener.
3 The @MapName("people") annotation specifies the name of the map to receive events from, in this case people.
4 The @Inserted annotation specified that only Inserted events should be sent to this method.

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.

7.1.1.1. Specify the Map/Cache name

By default, a MapEvent observer method would receive events for all maps/caches. In practice though, this would not be a very common use case, and typically you would want an observer method to listen to events that are for specific caches. The Coherence Spring API contains two annotations for specifying the map name:

Both annotations take a single String value that represents the name of the map or cache that events should be received from.

Listening to events for all caches
    @CoherenceEventListener
    public void onEvent(MapEvent<String, String> event) {
        // TODO: process the event
    }

The above method receives events for all caches.

Listening to events for the map named "foo"
    @CoherenceEventListener
    public void onFooEvent(@MapName("foo")       (1)
                           MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the map named foo.
Listening to events for the cache named "bar"
    @CoherenceEventListener
    public void onBarEvent(@CacheName("bar")     (1)
                           MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the cache named bar.
7.1.1.2. Specify the Cache Service name

In the previous section we showed to restrict received events to a specific map or cache name. Events can also be restricted to only events from a specific cache service. In Coherence all caches are owned by a cache service, which has a unique name. By default, a MapEvent observer method would receive events for a matching cache name on all services. If an applications Coherence configuration has multiple services, the events can be restricted to just specific services using the @ServiceName annotation.

Listening to events for the "foo" map on all services
    @CoherenceEventListener
    public void onEventFromAllServices(@MapName("foo")  (1)
                                MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the map named foo on all cache services.
Listening to events for the "foo" map on the "Storage" service only
    @CoherenceEventListener
    public void onEventOnStorageService(@MapName("foo")
                        @ServiceName("Storage")  (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the map named foo owned by the cache service named Storage.
Listening to events for ALL caches on the "Storage" service
    @CoherenceEventListener
    public void onEventFromAllCachesOnStorageService(@ServiceName("Storage")  (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for all caches owned by the cache service named Storage as there is no @MapName or @CacheName annotation.
7.1.1.3. Specify the Owning Session Name

In applications that use multiple Sessions, there may be a situation where more than one session has a map with the same name. In those cases an observer method may need to restrict the events it receives to a specific session. The events can be restricted to maps and/or caches in specific sessions using the @SessionName annotation.

Listening to events for the "orders" map in ALL sessions
    @CoherenceEventListener
    public void onOrdersEventAllSessions(@MapName("orders")  (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the map named orders in all sessions.
Listening to events for the "orders" map in the "Customer" session only
    @CoherenceEventListener
    public void onOrdersEventInCustomerSession(@MapName("orders")
                        @SessionName("Customer")             (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the map named orders owned by the Session named Customer.
Listening to events for ALL caches in the "Customer" session
    @CoherenceEventListener
    public void onEventInAllCachesInCustomerSession(@SessionName("Customer") (1)
                                MapEvent<String, String> event) {
        // TODO: process the event
    }
1 The above method receives events for the all caches owned by the Session named Customer as there is no @MapName or @CacheName annotation.

Therefore, in application with multiple sessions, events with the same name can be routed by session.

Route events with the cache name by the name of the session
    @CoherenceEventListener
    public void onCustomerOrders(@SessionName("Customer")    (1)
                                 @MapName("orders")
                                 MapEvent<String, Order> event) {
        // TODO: process the event
    }

    @CoherenceEventListener
    public void onCatalogOrders(@SessionName("Catalog")      (2)
                                @MapName("orders")
                                MapEvent<String, Order> event) {
        // TODO: process the event
    }
1 The onCustomerOrders method will receive events for the orders map owned by the Session named Customer.
2 The onCatalogOrders method will receive events for the orders map owned by the Session named Catalog.

7.1.2. Receive Specific Event Types

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

  • Insert

  • Update

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

Listen to "Insert" event for the "test" map only
    @CoherenceEventListener
    public void onInsertEvent(@MapName("test")
                        @Inserted                            (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 Only Insert events for the map test will be received.
Listen to "Insert" and "Delete" events for the "test" map only
    @CoherenceEventListener
    public void onInsertAndDeleteEvent(@MapName("test")
                        @Inserted @Deleted                   (1)
                        MapEvent<String, String> event) {
        // TODO: process the event
    }
1 Only Insert and Delete events for the map test will be received.
Listen to ALL map events for the "test" map
    @CoherenceEventListener
    public void onMapEvent(@MapName("test") MapEvent<String, String> event) {
        // TODO: process the event
    }

All events for the map test will be received.

7.1.3. Filtering Events

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.

Example of a Where Filter
    @WhereFilter("age >= 18")                    (1)
    @CoherenceEventListener
    @MapName("people")
    public void onAdult(MapEvent<String, Person> people) {
        // TODO: process event...
    }
1 The @WhereFilter annotation is applied to the method.

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.

7.1.4. Transforming Events

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:

Example of a Property Extractor
    @CoherenceEventListener
    @PropertyExtractor("customerId")                         (1)
    public void onOrder(@MapName("orders")                   (2)
                        MapEvent<String, String> event) {    (3)
        // TODO: process event...
    }
1 The method is annotated with @PropertyExtractor to indicate that a ValueExtractor that just extracts the customerId property should be used to transform the event.
2 The map name to receive events from is set to orders
3 Note that the generic types of the MapEvent parameter are now MapEvent<String, String> instead of MapEvent<String, Order> because the event values will have been transformed from an Order into just the String customerId.

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:

Example of using multiple Property Extractors
    @CoherenceEventListener
    @PropertyExtractor("customerId")                              (1)
    @PropertyExtractor("orderId")
    public void onOrderWithMultiplePropertyExtractors(
                        @Inserted                                 (2)
                        @MapName("orders")
                        MapEvent<String, List<Object>> event) {   (3)
        List list = event.getNewValue();
        String customerId = (String) list.get(0);                 (4)
        Long orderId = (Long) list.get(1);
        // ...
    }
1 The method is annotated with two @PropertyExtractor annotations, one to extract customerId and one to extract orderId.
2 The method parameter is annotated with @Inserted so that the method only receives Insert events.
3 The MapEvent parameter not has a key of type String and a value of type List<Object>, because the values from the multiple extractors will be returned in a List. We cannot use a generic value narrower than Object for the list because it will contain a String and a Long.
4 The extracted values can be obtained from the list, they will be in the same order that the annotations were applied to the method.

7.2. Coherence Event Interceptors

Coherence produces many events in response to various server-side 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 Spring API makes subscribing to these events simple, by using the same approach used for Spring Application 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.

7.2.1. Event Types

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.

7.2.2. Coherence Lifecycle Events

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:

@CoherenceEventListener
public void onEvent(LifecycleEvent event) {
    // TODO: process the event
}
7.2.2.1. Receive Specific LifecycleEvent Types

There are four different types of LifecycleEvent. By adding the corresponding annotation to the method parameter the method will only receive the specified events.

  • Activating - a ConfigurableCacheFactory instance is about to be activated, use the @Activating annotation

  • Activated - a ConfigurableCacheFactory instance has been activated, use the @Activated annotation

  • Disposing - a ConfigurableCacheFactory instance is about to be disposed, use the @Disposing annotation

For example, the method below will only receive Activated and Disposing events.

@CoherenceEventListener
public void onEvent(@Activated @Disposing LifecycleEvent event) {
    // TODO: process the event
}
7.2.2.2. Receive CoherenceLifecycleEvents for a Specific Coherence Instance

Each Coherence instance in an application has a unique name. The observer method can be annotated to only receive events associated with a specific Coherence instance by using the @Name annotation.

For example, the method below will only receive events for the Coherence instance named customers:

@CoherenceEventListener
public void onEvent(@Name("customers") CoherenceLifecycleEvent event) {
    // TODO: process the event
}

The method in this example will receive events for the default Coherence instance:

@CoherenceEventListener
public void onEvent(@Name(Coherence.DEFAULT_NAME) CoherenceLifecycleEvent event) {
    // TODO: process the event
}

7.2.3. Session Lifecycle Events

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:

@CoherenceEventListener
public void onEvent(SessionLifecycleEvent event) {
    // TODO: process the event
}
7.2.3.1. Receive Specific SessionLifecycleEvent Types

There are four different types of SessionLifecycleEvent. By adding the corresponding annotation to the method parameter the method will only receive the specified events.

  • Starting - a Coherence instance is about to start, use the @Starting annotation

  • Started - a Coherence instance has started, use the @Started annotation

  • Stopping - a Coherence instance is about to stop, use the @Stopping annotation

  • Stopped - a Coherence instance has stopped, use the @Stopped annotation

For example, the method below will only receive Started and Stopped events.

@CoherenceEventListener
public void onEvent(@Started @Stopped SessionLifecycleEvent event) {
    // TODO: process the event
}
7.2.3.2. Receive SessionLifecycleEvents for a Specific Session Instance

Each Session instance in an application has a name. The observer method can be annotated to only receive events associated with a specific Session instance by using the @Name annotation.

For example, the method below will only receive events for the Session instance named customers:

@CoherenceEventListener
public void onEvent(@Name("customers") SessionLifecycleEvent event) {
    // TODO: process the event
}

The method in this example will receive events for the default Coherence instance:

@CoherenceEventListener
public void onEvent(@Name(Coherence.DEFAULT_NAME) SessionLifecycleEvent event) {
    // TODO: process the event
}

7.2.4. ConfigurableCacheFactory Lifecycle Events

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:

@CoherenceEventListener
public void onEvent(CoherenceLifecycleEvent event) {
    // TODO: process the event
}
7.2.4.1. Receive Specific CoherenceLifecycleEvent Types

There are four different types of CoherenceLifecycleEvent. By adding the corresponding annotation to the method parameter the method will only receive the specified events.

  • Starting - a Coherence instance is about to start, use the @Starting annotation

  • Started - a Coherence instance has started, use the @Started annotation

  • Stopping - a Coherence instance is about to stop, use the @Stopping annotation

  • Stopped - a Coherence instance has stopped, use the @Stopped annotation

For example, the method below will only receive Started and Stopped events.

@CoherenceEventListener
public void onEvent(@Started @Stopped CoherenceLifecycleEvent event) {
    // TODO: process the event
}
7.2.4.2. Receive CoherenceLifecycleEvents for a Specific Coherence Instance

Each Coherence instance in an application has a unique name. The observer method can be annotated to only receive events associated with a specific Coherence instance by using the @Name annotation.

For example, the method below will only receive events for the Coherence instance named customers:

@CoherenceEventListener
public void onEvent(@Name("customers") CoherenceLifecycleEvent event) {
    // TODO: process the event
}

The method in this example will receive events for the default Coherence instance:

@CoherenceEventListener
public void onEvent(@Name(Coherence.DEFAULT_NAME) CoherenceLifecycleEvent event) {
    // TODO: process the event
}

7.2.5. Cache Lifecycle Events

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.

@CoherenceEventListener
public void onEvent(CacheLifecycleEvent event) {
    // TODO: process the event
}
7.2.5.1. Receive Specific CacheLifecycleEvent Types

There are three types of `CacheLifecycleEvent:

  • Created - a cache instance has been created, use the @Created annotation

  • Truncated - a cache instance has been truncated (all data was removed), use the @Truncated annotation

  • Destroyed - a cache has been destroyed (destroy is a cluster wide operation, so the cache is destroyed on all members of the cluster and clients) use the @Destroyed annotation

For example, the method below will only receive Created and Destroyed events for all caches.

@CoherenceEventListener
public void onEvent(@Created @Destroyed CacheLifecycleEvent event) {
    // TODO: process the event
}
7.2.5.2. Receive CacheLifecycleEvents for a Specific NamedMap or NamedCache

To only receive events for a specific NamedMap annotate the method parameter with the @MapName annotation. To only receive events for a specific NamedCache annotate the method parameter with the @CacheName annotation.

The @MapName and @CacheName annotations are actually interchangeable so use whichever reads better for your application code, i.e. if your code is dealing with NamedMap used @MapName. At the storage level, where the events are generated a NamedMap and NamedCache are the same.

The method below will only receive events for the map named orders:

@CoherenceEventListener
public void onEvent(@MapName("orders") CacheLifecycleEvent event) {
    // TODO: process the event
}
7.2.5.3. Receive CacheLifecycleEvents from a Specific Cache Service

Caches are owned by a Cache Service, it is possible to restrict events received by a method to only those related to caches owned by a specific service by annotating the method parameter with the @ServiceName annotation.

The method below will only receive events for the caches owned by the service named StorageService:

@CoherenceEventListener
public void onEvent(@ServiceName("StorageService") CacheLifecycleEvent event) {
    // TODO: process the event
}
7.2.5.4. Receive CacheLifecycleEvents from a Specific Session

A typical use case is to obtain NamedCache and NamedMap instances from a Session. It is possible to restrict events received by a method to only those related to caches owned by a specific Session by annotating the method parameter with the @SessionName annotation.

The method below will only receive events for the caches owned by the Session named BackEnd:

@CoherenceEventListener
public void onEvent(@SessionName("BackEnd") CacheLifecycleEvent event) {
    // TODO: process the event
}

7.2.6. Entry Events

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.

@CoherenceEventListener
public void onEvent(EntryEvent event) {
    // TODO: process the event
}
7.2.6.1. Receive Specific EntryEvent Types

There are a number of different EntryEvent types.

  • Inserting - an entry is being inserted into a cache, use the @Inserting annotation

  • Inserted - an entry has been inserted into a cache, use the @Inserted annotation

  • Updating - an entry is being updated in a cache, use the @Updating annotation

  • Updated - an entry has been updated in a cache, use the @Updated annotation

  • Removing - an entry is being deleted from a cache, use the @Removing annotation

  • Removed - an entry has been deleted from a cache, use the @Removed annotation

To restrict the EntryEvent types received by a method apply one or more of the annotations above to the method parameter. For example, the method below will receive Inserted and Removed events.

@CoherenceEventListener
public void onEvent(@Inserted @Removed EntryEvent event) {
    // TODO: process the event
}

The event types fall into two categories, pre-events (those named *ing) and post-events, those named *ed). Pre-events are emitted synchronously before the entry is mutated. Post-events are emitted asynchronously after the entry has been mutated.

As pre-events are synchronous the listener method should not take a long time to execute as it is blocking the cache mutation and could obviously be a performance impact. It is also important that developers understand Coherence reentrancy as the pre-events are executing on the Cache Service thread so cannot call into caches owned by the same service.

7.2.6.2. Receive EntryProcessorEvents for a Specific NamedMap or NamedCache

To only receive events for a specific NamedMap annotate the method parameter with the @MapName annotation. To only receive events for a specific NamedCache annotate the method parameter with the @CacheName annotation.

The @MapName and @CacheName annotations are actually interchangeable so use whichever reads better for your application code, i.e. if your code is dealing with NamedMap used @MapName. At the storage level, where the events are generated a NamedMap and NamedCache are the same.

The method below will only receive events for the map named orders:

@CoherenceEventListener
public void onEvent(@MapName("orders") EntryProcessorEvent event) {
    // TODO: process the event
}
7.2.6.3. Receive EntryProcessorEvents from a Specific Cache Service

Caches are owned by a Cache Service, it is possible to restrict events received by a method to only those related to caches owned by a specific service by annotating the method parameter with the @ServiceName annotation.

The method below will only receive events for the caches owned by the service named StorageService:

@CoherenceEventListener
public void onEvent(@ServiceName("StorageService") EntryProcessorEvents event) {
    // TODO: process the event
}
7.2.6.4. Receive EntryProcessorEvents from a Specific Session

A typical use case is to obtain NamedCache and NamedMap instances from a Session. It is possible to restrict events received by a method to only those related to caches owned by a specific Session by annotating the method parameter with the @SessionName annotation.

The method below will only receive events for the caches owned by the Session named BackEnd:

@CoherenceEventListener
public void onEvent(@SessionName("BackEnd") EntryProcessorEvents event) {
    // TODO: process the event
}

7.2.7. EntryProcessor Events

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.

@CoherenceEventListener
public void onEvent(EntryProcessorEvent event) {
    // TODO: process the event
}
7.2.7.1. Receive Specific EntryProcessorEvent Types

There are a number of different EntryProcessorEvent types.

  • Executing - an EntryProcessor is being invoked on a cache, use the @Executing annotation

  • Executed - an EntryProcessor has been invoked on a cache, use the @Executed annotation

To restrict the EntryProcessorEvent types received by a method apply one or more of the annotations above to the method parameter. For example, the method below will receive Executed events.

@CoherenceEventListener
public void onEvent(@Executed EntryProcessorEvent event) {
    // TODO: process the event
}

The event types fall into two categories, pre-event ('Executing') and post-event (Executed). Pre-events are emitted synchronously before the EntryProcessor is invoked. Post-events are emitted asynchronously after the EntryProcessor has been invoked.

As pre-events are synchronous the listener method should not take a long time to execute as it is blocking the EntryProcessor invocation and could obviously be a performance impact. It is also important that developers understand Coherence reentrancy as the pre-events are executing on the Cache Service thread so cannot call into caches owned by the same service.

7.2.7.2. Receive EntryProcessorEvents for a Specific NamedMap or NamedCache

To only receive events for a specific NamedMap annotate the method parameter with the @MapName annotation. To only receive events for a specific NamedCache annotate the method parameter with the @CacheName annotation.

The @MapName and @CacheName annotations are actually interchangeable so use whichever reads better for your application code, i.e. if your code is dealing with NamedMap used @MapName. At the storage level, where the events are generated a NamedMap and NamedCache are the same.

The method below will only receive events for the map named orders:

@CoherenceEventListener
public void onEvent(@MapName("orders") EntryProcessorEvent event) {
    // TODO: process the event
}
7.2.7.3. Receive EntryProcessorEvents from a Specific Cache Service

Caches are owned by a Cache Service, it is possible to restrict events received by a method to only those related to caches owned by a specific service by annotating the method parameter with the @ServiceName annotation.

The method below will only receive events for the caches owned by the service named StorageService:

@CoherenceEventListener
public void onEvent(@ServiceName("StorageService") EntryProcessorEvents event) {
    // TODO: process the event
}
7.2.7.4. Receive EntryProcessorEvents from a Specific Session

A typical use case is to obtain NamedCache and NamedMap instances from a Session. It is possible to restrict events received by a method to only those related to caches owned by a specific Session by annotating the method parameter with the @SessionName annotation.

The method below will only receive events for the caches owned by the Session named BackEnd:

@CoherenceEventListener
public void onEvent(@SessionName("BackEnd") EntryProcessorEvents event) {
    // TODO: process the event
}

7.2.8. Partition Level Transaction Events

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.

@CoherenceEventListener
public void onEvent(TransactionEvent event) {
    // TODO: process the event
}
7.2.8.1. Receive Specific TransactionEvent Types

There are a number of different TransactionEvent types.

  • Committing - A COMMITTING event is raised prior to any updates to the underlying backing map. This event will contain all modified entries which may span multiple backing maps. Use the @Committing annotation

  • Committed - A COMMITTED event is raised after any mutations have been committed to the underlying backing maps. This event will contain all modified entries which may span multiple backing maps. Use the @Committed annotation

To restrict the TransactionEvent types received by a method apply one or more of the annotations above to the method parameter. For example, the method below will receive Committed events.

@CoherenceEventListener
public void onEvent(@Committed TransactionEvent event) {
    // TODO: process the event
}
7.2.8.2. Receive TransactionEvent from a Specific Cache Service

Caches are owned by a Cache Service, it is possible to restrict events received by a method to only those related to caches owned by a specific service by annotating the method parameter with the @ServiceName annotation.

The method below will only receive events for the caches owned by the service named StorageService:

@CoherenceEventListener
public void onEvent(@ServiceName("StorageService") TransactionEvent event) {
    // TODO: process the event
}

7.2.9. Partition Transfer Events

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.

TransferEvents are dispatched to interceptors while holding a lock on the partition being transferred, blocking any operations for the partition. Event observer methods should therefore execute as quickly as possible of hand-off execution to another thread.

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.

@CoherenceEventListener
public void onEvent(TransferEvent event) {
    // TODO: process the event
}
7.2.9.1. Receive Specific TransferEvent Types

There are a number of different TransferEvent types.

  • Arrived - This TransferEvent is dispatched when a set of BinaryEntry instances have been transferred to the local member or restored from backup.The reason for the event (primary transfer from another member or restore from backup) can be derived as follows:

TransferEvent event;
boolean restored = event.getRemoteMember() == event.getLocalMember();

Use the @Arrived annotation to restrict the received events to arrived type.

  • Assigned - This TransferEvent is dispatched when a partition has been assigned to the local member. This event will only be emitted by the ownership senior during the initial partition assignment. Use the @Assigned annotation to restrict received events.

  • Departing - This TransferEvent is dispatched when a set of BinaryEntry are being transferred from the local member. This event is followed by either a Departed or Rollback event to indicate the success or failure of the transfer. Use the @Departing annotation to restrict received events.

  • Departed - This TransferEvent is dispatched when a partition has been successfully transferred from the local member. To derive the BinaryEntry instances associated with the transfer, consumers should subscribe to the Departing event that would precede this event. Use the @Departed annotation to restrict received events.

  • Lost - This TransferEvent is dispatched when a partition has been orphaned (data loss may have occurred), and the ownership is assumed by the local member. This event is only be emitted by the ownership senior. Use the @Lost annotation to restrict received events.

  • Recovered - This TransferEvent is dispatched when a set of BinaryEntry instances have been recovered from a persistent storage by the local member. Use the @Recovered annotation to restrict received events.

  • Rollback - This TransferEvent is dispatched when partition transfer has failed and was therefore rolled back. To derive the BinaryEntry instances associated with the failed transfer, consumers should subscribe to the Departing event that would precede this event. Use the @Rollback annotation to restrict received events.

To restrict the TransferEvent types received by a method apply one or more of the annotations above to the method parameter. For example, the method below will receive Lost events.

@CoherenceEventListener
public void onEvent(@Lost TransferEvent event) {
    // TODO: process the event
}

Multiple type annotations may be used to receive multiple types of TransferEvent.

7.2.9.2. Receive TransferEvent from a Specific Cache Service

Caches are owned by a Cache Service, it is possible to restrict events received by a method to only those related to caches owned by a specific service by annotating the method parameter with the @ServiceName annotation.

The method below will only receive events for the caches owned by the service named StorageService:

@CoherenceEventListener
public void onEvent(@ServiceName("StorageService") TransferEvent event) {
    // TODO: process the event
}

7.2.10. Unsolicited Commit Events

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.

@CoherenceEventListener
public void onEvent(UnsolicitedCommitEvent event) {
    // TODO: process the event
}

8. Filter Binding Annotations

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:

  • The filter binding annotation

  • An implementation of a FilterFactory that is annotated with the filter binding annotation. This is a factory that produces the required Filter.

  • Injection points annotated with the filter binding annotation.

We will put all three parts together in an example. Let’s use a Coherence NamedMap named plants that contains plants represented by instances of the Plant class as map values. Among the various properties on the Plant class there is a property called plantType and a property called height. In this example, we want to inject a view that only shows large palm trees (any palm tree larger than 20 meters). We would need a Filter that has a condition like the following: plantType == PlantType.PALM && height >= 20.

8.1. Create the filter binding annotation

First create a simple annotation, it could be called something like PlantNameExtractor

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import com.oracle.coherence.spring.annotation.FilterBinding;

@FilterBinding                                   (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface LargePalmTrees {               (2)
}
1 The annotation class is annotated with @FilterBinding
2 The annotation name is PlantNameExtractor

In this case the annotation does not need any other attributes.

8.2. Create the FilterFactory

Now create the FilterFactory implementation that will produce instances of the required Filter.

import com.oracle.coherence.spring.annotation.FilterFactory;
import com.tangosol.util.Extractors;
import com.tangosol.util.Filter;
import com.tangosol.util.Filters;
import org.springframework.stereotype.Component;

@LargePalmTrees                                              (1)
@Component                                                   (2)
public class LargePalmTreesFilterFactory<Plant>
        implements FilterFactory<LargePalmTrees, Plant> {
    @Override
    public Filter<Plant> create(LargePalmTrees annotation) { (3)
        Filter<Plant> palm = Filters.equal("plantType", PlantType.PALM);
        Filter<Plant> height = Filters.greaterEqual(
                Extractors.extract("height"), 20);
        return Filters.all(palm, height);
    }
}
1 The class is annotated with the PlantNameExtractor filter binding annotation
2 The class must be a Spring bean, let’s annotate it with @Component so that component scanning will pick this class up as a Spring bean
3 The create method uses the Coherence filters API to create the required filter.

The parameter to the create method is the annotation used on the injection point. In this case the annotation has no values, but if it did we could access those values to customize how the filter is created.

For example, we can make the filter more general purpose by calling the annotation @PalmTrees and by adding a value parameter representing the height like this:

@FilterBinding
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface PalmTrees {
    String value();
}
@FilterBinding
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface PalmTrees {
    int value() default 0;
}

We then need to modify our filter factory to use the height value:

import com.oracle.coherence.spring.annotation.FilterFactory;
import com.tangosol.util.Extractors;
import com.tangosol.util.Filter;
import com.tangosol.util.Filters;
import org.springframework.stereotype.Component;

@PalmTrees                                                                (1)
@Component                                                                (2)
public class PalmTreesFilterFactory<Plant>
        implements FilterFactory<PalmTrees, Plant> {
    @Override
    public Filter<Plant> create(PalmTrees annotation) {                   (3)
        Filter<Plant> palm = Filters.equal("plantType", PlantType.PALM);
        Filter<Plant> height = Filters.greaterEqual(
                Extractors.extract("height"), annotation.value());  (4)
        return Filters.all(palm, height);
    }
}
1 The class is annotated with the more flexible PalmTrees filter binding annotation accepting a height parameter
2 The class must be a Spring bean, let’s annotate it with @Component so that component scanning will pick this class up as a Spring bean
3 The create method uses the Coherence filters API to create the required filter
4 Instead of hard-coding the height, we use the value from the @PalmTrees annotation

8.3. Annotate the Injection Point

Now the application code where the view is to be injected can use the custom filter binding annotation.

    @View                                                    (1)
    @PalmTrees(1)                                            (2)
    @CoherenceCache("plants")                                (3)
    private NamedMap<Long, Plant> palmTrees;
1 The @View annotation indicates that this is a view rather than a plain NamedMap
2 The @PalmTrees annotation links to the custom filter factory which is used to create the filter for the view. The annotation value of 1 indicates that we are interested in all palm trees of at least 1 meter in height.
3 Due to Spring limitations regarding the injection of Maps, we use the @CoherenceMap annotation to inject the NamedMap, which also has takes an optional value to specify the name of the cache.

9. Extractor Binding Annotations

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:

  • The extractor binding annotation

  • An implementation of a ExtractorFactory that is annotated with the extractor binding annotation. This is a factory that produces the required ValueExtractor.

  • Injection points annotated with the extractor binding annotation.

As an example, let’s continue with our previous example, where we have a Coherence NamedMap named plants that contains Plant instances as values. In this example we are interested in inject a map of plant names instead of the actual plant instances. Each plant has a name property that we will use for that purpose. We will need a ValueExtractor that extracts the name property and the resulting map of plant names can be injected into our Spring beans.

9.1. Create the extractor binding annotation

First create a simple annotation called PlantName

@ExtractorBinding                                (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface PersonAge {                    (2)
}

import com.oracle.coherence.spring.annotation.ExtractorBinding;
import com.oracle.coherence.spring.annotation.FilterBinding;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@ExtractorBinding                                (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface PlantNameExtractor {           (2)
}
1 The annotation class is annotated with @ExtractorBinding
2 The annotation name is PlantNameExtractor

In this case the annotation does not need any other attributes.

9.2. Create the ExtractorFactory

Now create the ExtractorFactory implementation that will produce instances of the required ValueExtractor.

import com.oracle.coherence.spring.annotation.ExtractorFactory;
import com.tangosol.util.Extractors;
import com.tangosol.util.ValueExtractor;
import org.springframework.stereotype.Component;

@PlantNameExtractor                                          (1)
@Component                                                   (2)
public class PlantNameExtractorFactory<Plant>
        implements ExtractorFactory<PlantNameExtractor, Plant, String> {
    @Override
    public ValueExtractor<Plant, String> create(PlantNameExtractor annotation) {  (3)
        return Extractors.extract("name");
    }
}
1 The class is annotated with the PlantNameExtractor extractor binding annotation
2 The class must be a Spring bean, let’s annotate it with @Component so that component scanning will pick this class up as a Spring bean
3 The create method uses the Coherence Extractors API to create the required extractor, in this case a trivial property extractor.

The parameter to the create method is the annotation used on the injection point. In this case the annotation has no values, but if it did we could access those values to customize how the ValueExtractor is created.

9.3. Annotate the Injection Point

Now the application code where the view is to be injected can use the custom extractor binding annotation.

@View                                            (1)
@PersonAge                                       (2)
@Name("people")                                  (3)
private NamedMap<String, Integer> ages;          (4)
    @View                                        (1)
    @PlantNameExtractor                          (2)
    @CoherenceMap("plants")                      (3)
    private NamedMap<Long, String> plants;       (4)
1 The @View annotation indicates that this is a view rather than a plain NamedMap
2 The @PlantNameExtractor annotation links to the custom extractor factory used to create the ValueExtractor for the view
3 Due to Spring limitations regarding the injection of Maps, we use the @CoherenceMap annotation to inject the NamedMap, which also has takes an optional value to specify the underlying cache/map name to use for the view.
4 Note that the NamedMap generics are now Long and String instead of Long and Plant as the Plant values from the underlying cache are transformed into String values by extracting just the name property.

10. Messaging with Coherence Topics

Spring Coherence integration provides support for message driven applications by virtue of 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 Spring applications is already covered in Injecting NamedTopics. With Spring messaging this becomes much simpler.

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

10.1. Define Publishers - @CoherencePublisher

To create a topic Publisher that sends messages, you can simply define an interface that is annotated with @CoherencePublisher. Also, your configuration class has to be annotated with the @CoherencePublisherScan annotation. This is needed to specify the base package from which we recursively scan for @CoherencePublisher annotated interfaces.

Config.java
@Configuration
@CoherencePublisherScan("com.example.app.services")
public class Config {
}

For example the following is a trivial @CoherencePublisher interface:

ProductClient.java
import com.oracle.coherence.spring.annotation.CoherencePublisher;
import com.oracle.coherence.spring.annotation.Topic;

@CoherencePublisher                              (1)
public interface ProductClient {

    @Topic("my-products")                        (2)
    void sendProduct(String message);            (3)

    void sendProduct(@Topic String topic, String message); (4)
}
1 The @CoherencePublisher annotation is used to designate this interface as a message publisher.
2 The @Topic annotation indicates which topics the message should be published to
3 The method defines a single parameter, which is the message value. In this case the values being published are String instances but they could be any type that can be serialized by Coherence.
4 It is also possible for the topic to be dynamic by making it a method argument annotated with @Topic.

At run time Spring 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:

Using ProductClient
ProductClient client = applicationContext.getBean(ProductClient.class);
client.sendProduct("Blue Trainers");

10.2. Reactive and Non-Blocking Method Definitions

The @CoherencePublisher annotation supports the definition of reactive return types (such as Reactor Flux) as well as Futures.

The following sections cover possible method signatures and behaviour:

10.2.1. Mono Value and Return Type

Mono<Publisher.Status> sendBook(Mono<Book> book);

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.

10.2.2. Reactor Flux Value and Return Type

Flux<Publisher.Status> sendBooks(Flux<Book> book);

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.

10.2.3. Future Return Type

Future<Publisher.Status> sendBooks(Mono<Book> book);

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

10.3. Define Subscribers - @CoherenceTopicListener

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:

ProductListener.java
import com.oracle.coherence.spring.annotation.CoherenceTopicListener;
import com.oracle.coherence.spring.annotation.Topic;

@CoherenceTopicListener                          (1)
public class ProductListener {

    @Topic("my-products")                        (2)
    public void receive(String product) {        (3)
        System.out.println("Got Product - " + product);
    }
}
1 The @CoherenceTopicListener annotation to indicate that this bean is a Coherence topic listener.
2 The @Topic annotation is again used to indicate which topic to subscribe to.
3 The receive method defines single arguments that will receive the message value, in this case the message is of type String.

10.4. Method Parameter Bindings

When using a Coherence topic Subscriber directly in application code, the receive method returns an Element, which contains the message value and metadata. The annotated subscriber method can take various parameter types that will bind to the element itself or to the message.

For example

@CoherenceTopicListener
@Topic("my-products")
public void receive(Element<Product> product) {
    // ... process message ...
}

The method above will be passed the Element received from the topic. By receiving the element, the method has access to the message value and all the metadata stored with the message.

10.5. Committing Messages

An important part of Coherence topic subscribers is committing messages to notify the server that they have been processed and guaranteeing at least once delivery. When using Micronaut Coherence messaging every message will be committed after the handler method has successfully processed the message. This behaviour can be controlled by adding a commit strategy to the @CoherenceTopicListener annotation.

10.5.1. Default Commit Behaviour

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

@CoherenceTopicListener
@Topic("my-products")
public void receive(Element<Product> product) {
    // ... process message ...
}

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

10.5.2. Setting Commit Strategy

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

  • CommitStrategy.SYNC - This strategy is the default, and will synchronously commit every message upon successful completion of the handler method, by calling Element.commit().

@CoherenceTopicListener(commitStrategy = CommitStrategy.SYNC)
@Topic("my-products")
public void receive(Product product) {
    // ... process message ...
}
  • CommitStrategy.ASYNC - This strategy will asynchronously commit every message upon successful completion of the handler method, by calling Element.commitAsync().

@CoherenceTopicListener(commitStrategy = CommitStrategy.ASYNC)
@Topic("my-products")
public void receive(Product product) {
    // ... process message ...
}
  • CommitStrategy.MANUAL - This strategy will not automatically commit messages, all handling of commits must be done as part of the handler method or by some external process.

@CoherenceTopicListener(commitStrategy = CommitStrategy.MANUAL)
@Topic("my-products")
public void receive(Element<Product> product) {
    // ... process message ...

    // manually commit the element
    element.commit();
}

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.

10.5.3. Forwarding Messages with @SendTo

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.

ProductListener.java
import com.oracle.coherence.spring.*;
import org.springframework.messaging.handler.annotation.SendTo;

@CoherenceTopicListener
public class ProductListener {

    @Topic("awesome-products")                   (1)
    @SendTo("product-quantities")                (2)
    public int receive(Product product) {
        System.out.println("Got Product - " + product.getName() + " by " + product.getBrand());
        return product.getQuantity();            (3)
    }
}
1 The topic subscribed to is awesome-products
2 The topic to send the result to is product-quantities
3 The return value is used to indicate the value to forward

You can also do the same using Reactive programming:

ProductListener.java
import com.oracle.coherence.spring.*;
import org.springframework.messaging.handler.annotation.SendTo;
import reactor.core.publisher.Mono;

@CoherenceTopicListener
public class ProductListener {

    @Topic("awesome-products")                   (1)
    @SendTo("product-quantities")                (2)
    public Mono<Integer> receiveProduct(Mono<Product> productSingle) {
        return productSingle.map(product -> {
            System.out.println("Got Product - " + product.getName() + " by " + product.getBrand());
            return product.getQuantity();        (3)
        });
    }
}
1 The topic subscribed to is awesome-products
2 The topic to send the result to is product-quantities
3 The return is mapped from the single to the value of the quantity

11. Cache Store

Coherence Spring provides dedicated support for database-backed caches using JPA. Spring Data’s JPA Repositories make basic CRUD database access very simple. An application developer can just provide an interface that extends JpaRepository with the required generic parameters and Spring will do the rest.

Coherence caches that are backed by a database have two options for how the database integration is provided:

  • CacheLoader - an application developer writes an implementation of a CacheLoader to read data from a database for a given key (or keys), convert it to entities that are then loaded into a cache for the given keys.

  • CacheStore - whilst a CacheLoader only loads from a database into a cache, a CacheStore (which extends CacheLoader) also stores cached entities back to the database, or for entries deleted from the cache, erases the corresponding values from the database. The parallels between a CacheLoader or CacheStore and a JpaRepository should be pretty obvious.

The Coherence Spring core module provides two interfaces:

To create a JPA repository cache loader or cache store, all a developer needs to do is extend the relevant interface JpaRepositoryCacheLoader or JpaRepositoryCacheStore with the correct generic parameters. We will illustrate the use of Cache Stores using the following example.

11.1. JPA Repository CacheStore Demo

In this demo we are show-casing how to use Spring Data JPA repository beans as Coherence CacheStores in applications using the Coherence Spring project.

The demo is split into multiple Maven modules in order to show-case 2 use-cases:

  • Embedded Coherence

  • Connect to a remote Coherence instance cache using Coherence*Extend

The Maven Project is structured into the following modules:

  • coherence-cachestore-demo-app Main entry point for the demo using an embedded Coherence instance

  • coherence-cachestore-demo-server Remote Coherence server we will connect to using Coherence*Extend

  • coherence-cachestore-demo-core Contains common code shared between the local app and the remote Coherence server version

11.1.1. Data Model

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:

@Entity
@Table(name = "PEOPLE")
public class Person implements Serializable {

    /**
     * The unique identifier for this person.
     */
    @Id
    private Long id;

    /**
     * The age of this person.
     */
    private int age;

    /**
     * The person's first name.
     */
    private String firstname;

    /**
     * The person's last name.
     */
    private String lastname;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getFirstname() {
        return firstname;
    }

    public void setFirstname(String firstname) {
        this.firstname = firstname;
    }

    public String getLastname() {
        return lastname;
    }

    public void setLastname(String lastname) {
        this.lastname = lastname;
    }

}

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

11.1.2. Writing a JPA Repository CacheStore

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

import com.oracle.coherence.spring.cachestore.JpaRepositoryCacheStore;
import org.springframework.stereotype.Repository;

@Repository
public interface PersonRepository extends JpaRepositoryCacheStore<Person, Long> {

}

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.

11.1.3. Embedded Coherence

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.

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

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.

coherence-cache-config.xml
    <caching-schemes>
        <distributed-scheme>
            <scheme-name>db-scheme</scheme-name>
            <service-name>StorageService</service-name>
            <backing-map-scheme>
                <read-write-backing-map-scheme>
                    <internal-cache-scheme>
                        <local-scheme/>
                    </internal-cache-scheme>
                    <cachestore-scheme>
                        <spring:bean>{repository-bean}</spring:bean>
                    </cachestore-scheme>
                </read-write-backing-map-scheme>
            </backing-map-scheme>
            <autostart>true</autostart>
        </distributed-scheme>

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.

coherence-cache-config.xml
        <cache-mapping>
            <cache-name>people</cache-name>
            <scheme-name>db-scheme</scheme-name>
            <init-params>
                <init-param>
                    <param-name>repository-bean</param-name>
                    <param-value>personRepository</param-value>
                </init-param>
            </init-params>
        </cache-mapping>

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.

The bean name used here is personRepository. This is the default name generated by Spring for the PersonRepository class, which is the simple class name with the first letter lowercase. If we did not want to rely on Spring generating a bean name we could specify a name in the @Repository annotation on the PersonRepository class.

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:

<cache-mapping>
    <cache-name>locations</cache-name>
    <scheme-name>db-scheme</scheme-name>
    <init-params>
        <init-param>
            <param-name>repository-bean</param-name>
            <param-value>locationRepository</param-value>
        </init-param>
    </init-params>
</cache-mapping>

11.1.4. Running the Embedded Sample

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:

PersonController.java
@RestController
@RequestMapping(path = "/api/people")
@Transactional()
public class PersonController {

    /**
     * The {@link NamedMap} to store {@link Person} entities.
     */
    @CoherenceMap
    private NamedMap<Long, Person> people;

    @Autowired
    private PersonRepository personRepository;

    /**
     * Create a {@link Person} in the cache.
     * @param id         the unique identifier for the person
     * @param firstName  the person's first name
     * @param lastName   the person's last name
     * @param age        the person's age
     * @return the identifier used to create the person
     */
    @PostMapping
    public Long createPerson(@RequestParam("id") long id, @RequestParam("firstName") String firstName,
            @RequestParam("lastName") String lastName, @RequestParam("age") int age) {
        Person person = new Person();
        person.setFirstname(firstName);
        person.setLastname(lastName);
        person.setAge(age);
        person.setId(id);
        people.put(id, person);
        return id;
    }

    /**
     * Returns the {@link Person} with the specified identifier.
     *
     * @param personId  the unique identifier for the person
     * @return  the {@link Person} with the specified identifier
     */
    @GetMapping("/{personId}")
    public Person getPerson(@PathVariable("personId") Long personId) {
        Person person = people.get(personId);
        if (person == null) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Person " + personId + " does not exist");
        }
        return person;
    }

    @GetMapping("/db/{personId}")
    public Person getPersonFromDb(@PathVariable("personId") Long personId) {
        Person person = this.personRepository.findById(personId).orElseThrow(() -> {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Person " + personId + " does not exist");
        });
        return person;
    }
}

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:

./mvnw clean package -pl samples/cachestore-demo

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

java -jar samples/cachestore-demo/coherence-spring-cachestore-demo-app/target/coherence-spring-cachestore-demo-4.0.0-SNAPSHOT.jar

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

curl -i -X GET http://localhost:8080/api/people/100

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:

curl -i -X POST http://localhost:8080/api/people \
    -d 'firstName=Joe' -d 'lastName=Smith' \
    -d 'age=21' -d 'id=100'

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.

curl -i -X GET http://localhost:8080/api/people/100
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 19 Aug 2021 16:13:47 GMT

{"id":100,"age":21,"firstname":"Joe","lastname":"Smith"}%

11.1.5. Using Coherence*Extend

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:

./mvnw clean install -pl :coherence-spring-cachestore-demo-server -am -DskipTests
./mvnw clean install -pl :coherence-spring-cachestore-demo-app -am -DskipTests

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:

java -jar samples/cachestore-demo/coherence-spring-cachestore-demo-server/target/coherence-spring-cachestore-demo-server-4.0.0-SNAPSHOT.jar

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:

java -jar samples/cachestore-demo/coherence-spring-cachestore-demo-app/target/coherence-spring-cachestore-demo-app-4.0.0-SNAPSHOT.jar \
--Dspring.profiles.active=remote

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.

11.1.6. Inspecting the Database

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.