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:
<dependency>
<groupId>com.oracle.coherence.spring</groupId>
<artifactId>coherence-spring-core</artifactId>
<version>3.0.0-M2</version>
</dependency>
implementation("com.oracle.coherence.spring:coherence-spring-core:3.0.0-M2")
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:
<dependency>
<groupId>com.oracle.coherence.ce</groupId>
<artifactId>coherence</artifactId>
<version>21.06</version>
</dependency>
implementation("com.oracle.coherence.ce:coherence:21.06")
In order to use the commercial version of Coherence:
<dependency>
<groupId>com.oracle.coherence</groupId>
<artifactId>coherence</artifactId>
<version>14.1.1-0-1</version>
</dependency>
implementation("com.oracle.coherence.ce:coherence:14.1.1-0-1")
Coherence CE versions are available from Maven Central. The commercial versions of Coherence needs to be uploaded into your own Maven repository. |
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 client
-
GRPC - Connect to Coherence as gRPC client
If the application is a Coherence cluster member, or a Coherence*Extend client, then all that needs to be specified is
the Coherence configuration file name. For instance, you may for example provide an implementation of
the AbstractSessionConfigurationBean
, to specify the type of your session and to use a custom Coherence configuration
file.
@Bean
SessionConfigurationBean sessionConfigurationBeanDefault() {
final SessionConfigurationBean sessionConfigurationBean =
new SessionConfigurationBean();
sessionConfigurationBean.setType(SessionType.SERVER);
sessionConfigurationBean.setConfig("test-coherence-config.xml");
return sessionConfigurationBean;
}
If you connect as gRPC client, however, the properties change slightly and you need to specify a
GrpcSessionConfigurationBean
:
@Bean
GrpcSessionConfigurationBean grpcSessionConfigurationBean() {
final GrpcSessionConfigurationBean sessionConfigurationBean = new GrpcSessionConfigurationBean();
sessionConfigurationBean.setName("sessionName");
sessionConfigurationBean.setChannelName("grpcChanelBeanName");
return sessionConfigurationBean;
}
The Channel Name property would refer to a grpcChannel bean.
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 is a gRPC client session (see the gRPC documentation).
The type of the session affects how the bootstrap API starts the session.
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 GRPC
mode, only:
channelName
Sets the underlying gRPC channel. If not set, it will default to localhost
and port 1408
.
serializer
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.
tracingEnabled
Specifies if client gRPC tracing should be enabled. This is false
by default.
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.
@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:
@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 |
6.1.1. 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:
@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:
@CoherenceMap
@Name("people")
private NamedMap<String, Person> map;
6.1.2. 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.
@CoherenceMap
@SessionName("Catalog")
@Name("products")
private NamedMap<String, Product> map;
This can be further streamlined to:
@CoherenceMap(name="products", session="Catalog")
private NamedMap<String, Product> map;
The same annotation can be used on method parameter injection points as well:
@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
@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.
@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'
.
@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:
@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.
@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
:
@RestController
public class MyBean {
@Inject (1)
private Session session;
1 | Other injection annotations such as @Autowired can be used as well |
@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.
@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:
@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
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
.
@Inject
@Name("people")
private NamedTopic<Order> orders;
The same applies when injecting a constructor or method 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.
@Inject
@SessionName("Customers")
@Name("orders")
private NamedTopic<Order> topic;
Again, the same annotation can be used on method parameter injection points.
@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
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:
orders
topic@Inject
@Name("orders")
private Publisher<Order> orders;
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
@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
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
@Name("orders")
private Subscriber<Order> orders;
@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:
-
MapEvents which are subscribed to using a MapListener
-
Events, which are subscribed to using an EventInterceptor
Spring makes subscribing to both of these event-types much simpler using observer methods annotated with @CoherenceEventListener.
@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.
|
@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:
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.
@CoherenceEventListener
public void onEvent(MapEvent<String, String> event) {
// TODO: process the event
}
The above method receives events for all caches.
@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 . |
@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.
@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. |
@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 . |
@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.
@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. |
@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 . |
@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.
@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.
@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. |
@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. |
@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
.
@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:
@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:
@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:
-
CoherenceLifecycleEvent - lifecycle events for Coherence instances
-
SessionLifecycleEvent - lifecycle events for Session instances
-
LifecycleEvent - lifecycle events for ConfigurableCacheFactory instances
-
CacheLifecycleEvent - lifecycle events for NamedMap and NamedCache instances
-
EntryEvent - events emitted by the mutation of entries in a NamedMap or NamedCache
-
EntryProcessorEvent - events emitted by the invocation of an EntryProcessor on entries in a NamedMap or NamedCache
-
TransactionEvent - events pertaining to all mutations performed within the context of a single request in a partition of a NamedMap or NamedCache, also referred to as "partition level transactions".
-
TransferEvent - captures information concerning the transfer of a partition for a storage enabled member.
-
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.
-
If using commercial versions of Coherence with Coherence Spring, there are also events associated to the federation of data between different clusters.
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 ( As pre-events are synchronous the listener method should not take a long time to execute as it is blocking the |
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 ofBinaryEntry
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 ofBinaryEntry
are being transferred from the local member. This event is followed by either aDeparted
orRollback
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 theBinaryEntry
instances associated with the transfer, consumers should subscribe to theDeparting
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 ofBinaryEntry
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 theBinaryEntry
instances associated with the failed transfer, consumers should subscribe to theDeparting
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.
@Configuration
@CoherencePublisherScan("com.example.app.services")
public class Config {
}
For example the following is a trivial @CoherencePublisher
interface:
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
:
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.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:
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.
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:
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 |