Coherence Spring Reference Documentation

The Coherence Spring reference guide is available as:

If you run into issues with Spring Coherence, we are here to help.

In order to see what changes were made from earlier versions of Coherence Spring, see the Change History as well as the GitHub Releases page.

If you are getting started with Coherence Spring, start with the Quickstart. It is a great way to see a working solution quickly. Particularly if you are relatively new to Spring, continue with the Coherence Spring Boot chapter next.

The reference documentation makes a distinction between Spring Framework and Spring Boot. At its very core, Spring Framework provides Dependency Injection (DI) or Inversion Of Control (IOC) to Java applications. Furthermore, Spring Framework gives developers comprehensive infrastructure support for developing Java applications.

Spring Boot on the other hand, is an opinionated extension to the Spring Framework by:

The vast majority of new Spring projects will utilize Spring Boot. Nonetheless, please also study the Spring Framework targeted chapters as Spring Frameworks is the foundation for everything related to Spring Boot.

In order to get started, please checkout the code from the coherence-community/coherence-spring[Coherence Spring Repository] GitHub repository.

You now have checked out all the code for Coherence Spring. The relevant demo code for this Quickstart demo is under samples/coherence-spring-demo/.

There you will find 3 Maven sub-modules:

The first two Maven modules are essentially variations of the same app. The third module contains shared code.

In this chapter we will focus on the Spring Boot version. Since we checked out the project, let’s build it using Maven:

Now we are ready to run the application:

Once the application is started, the embedded database is empty. Let’s create an event with 2 people added to them using curl:

This call will create and persist an Event to the database. However, there is more going on. The created Event is also added to the Coherence Cache. The magic is happening in the Service layer, specifically in DefaultEventService#createAndStoreEvent(), which is annotated with @CachePut(cacheNames="events", key="#result.id").

The cacheNames attribute of the @CachePut annotation indicates the name of the underlying cache to use. As caches are basically just a Map, we also need a key. In this case we use the expression #result.id to retrieve the primary key of the Event as it was persisted. Thus, the saved Event is added to the cache named events and ultimately also returned and printed to the console:

We see that an Event with the id 1 was successfully created. Let’s verify that the cache put worked by inspecting the cache using the open-source tool VisualVM.

Under the MBeans tab you will find the Cache MBeans, including and entry for the events cache, providing numerous statistical information regarding the cache.

You should see an entry for TotalPuts of 1.

Next, lets retrieve the Event using id 1:

The Event is returned. Did you notice? No SQL queries were executed as the value was directly retrieved from the Cache. Let’s check the statistics again, this time via the Coherence VisualVM Plugin:

We will see now how values are being returned from the cache by seeing increasing cacheHits, e.g., "cacheHits" : 1. Let’s evict our Event with id 1 from the cache named events:

If you now retrieve the event again using:

you will see an SQL query executed in the console, re-populating the cache. Feel free to play along with the Rest API. We can, for example, add people:

Or assign people to events:

What is involved to make this all work? Using Spring Boot, the setup is incredibly simple. We take advantage of Spring Boot’s AutoConfiguration capabilities, and the sensible defaults provided by Coherence Spring.

In order to activate AutoConfiguration for Coherence Spring you need to add the coherence-spring-boot-starter dependency as well as the desired dependency for Coherence.

In this quickstart example we are using Spring’s Caching abstraction and therefore, we use the spring-boot-starter-cache dependency as well:

For caching you also must activate caching using the @EnableCaching annotation.

Please see the relevant chapter on Caching in the Spring Boot reference guide.

With @EnableCaching in place, Coherence’s autoconfiguration will also provide a CoherenceCacheManager bean to the application context.

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:

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:

In order to use the commercial version of 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.

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:

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.

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.

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:

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

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.

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.

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.

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.

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:

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.

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:

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.

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.

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:

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.

Spring provides its own cache abstraction, allowing you to add caching to Java methods. Coherence Spring provides an implementation of this abstraction for Oracle Coherence.

As a start, please familiarize yourself with Spring’s Cache Abstraction by reading the following resources:

Spring’s cache abstraction for Coherence will be automatically enabled as soon as you specify @EnableCaching in your applications configuration classes. In that case a CoherenceCacheManager bean implementation is registered as CacheManager. Of course, you can define your own CacheManager as well, but in that case auto-configuration will back-off.

When the CacheManager gets instantiated it is configured with default settings that then get applied for all underlying caches being created and used. Those settings are defined using the CoherenceCacheConfiguration object. If not specified as a second (optional) constructor argument to the CoherenceCacheManager, a default instance is created.

Thus, you can customize certain cache properties when instantiating the CoherenceCacheManager by providing your own CoherenceCacheConfiguration instance as a second constructor argument. For example, you can set the time-to-live (ttl) property to specify that caches shall expire after a certain period.

Please consult the Quickstart chapter to see an example using Spring’s cache abstraction support with Spring Boot. Coherence Spring also provides an example of using Spring Framework (without Spring Boot). The source code for the samples is part of the Coherence Spring projects:

If you’re using Spring Boot, please continue reading the Spring Boot specific chapter on caching.

Oracle Coherence supports the explicit concurrency control of cache entries using locks. The configuration class CoherenceCacheConfiguration provides 3 options to specify the relevant settings:

useLocks

This option lets you specify whether you want to use locks or not. This options defaults to true, meaning that locking is enabled by default.

lockTimeout

When locking cache entries, you can set a cache timeout. The specified value in milliseconds, instructs Coherence how long it shall try to acquire a lock for the cache entry. If a timeout occurs, Coherence Spring will throw an exception. A value of -1 will cause Coherence to block indefinitely. Specifying 0 will cause Oracle Coherence not to wait at all. By default, the value is set to 0.

lockEntireCache

While generally not recommended, the option exists to also lock they entire cache (not just the specific cache entry). This option defaults to false.

For further information, please read the corresponding chapter Using Explicit Locking for Data Concurrency in the Oracle Coherence reference guide.

In this chapter you will learn how to configure Coherence as an HTTP session store using Spring Session.

First you need to add the coherence-spring-session dependency:

In order to enable Spring Session support for Coherence, make sure Coherence is enabled and then enable Spring Session using the @EnableCoherenceHttpSession annotation.

Are you running Coherence as a dedicated server instance? Then you need to make sure that your Coherence server may need one or more additional dependencies on its classpath for serialization. Depending on your requirements, you may need Coherence Spring Session, Spring Security Core, Spring Security Web. Please also ensure that dependency version between Coherence server and application clients matches exactly.

In case that you configured the cache using POF serialization, additional POF configuration for the class MapSession is necessary:

This Coherence Spring source code repository provides a dedicated example application, illustrating the usage of Spring Session and Spring Security using Spring Boot.

The example application show-cases 2 use-cases:

Even though this demo is targeting Spring Session, we use Spring Security as well, since the authentication details are stored in the session as well. In regard to authentication, users have 2 choices:

The username is coherence, and the password rocks.

Once successfully authenticated, the application will return a 2xx HTTP status with an empty body and a session cookie. An Authentication failure, on the other hand, produces a non-2xx HTTP status with an empty body. The application has an endpoint that responds to a GET request to the URL /hello that returns the string Hello Coherence. All endpoints require an authenticated user using the session cookie or the username and password.

When dealing with the expiration of cache entries, you generally have 2 options in Coherence:

When you define a session timeout via the application, for example @EnableCoherenceHttpSession(sessionTimeoutInSeconds = 1000), the session expiration will be set for each put-operation in CoherenceIndexedSessionRepository.

If you rather prefer defining the session expiration timeouts in your coherence-cache-config.xml file, you should set the session timeout in the application to 0, for instance @EnableCoherenceHttpSession(sessionTimeoutInSeconds = 0). That way, put operations will never to set an expiration value for the cache entry. You can then set the expiry-delay cache configuration element for your cache in the coherence-cache-config.xml file.

In regard to the question, whether one strategy or the other strategy is preferable: It is mostly a matter of preference. You do have, however, a bit more control when configuring expiration logic via the coherence-cache-config.xml file, as you have the ability to define custom eviction policies.

For more information, please consult the respective chapter on Controlling the Growth of a Local Cache in the Coherence reference guide.

The Spring Data Coherence module provides integration with Coherence data grids. Key functional areas of Spring Data Coherence are a POJO centric model for interacting with a Coherence data grid and easily writing a Repository style data access layer.

Before proceeding, please be familiar with the Spring Data Commons documentation, as this section will assume some familiarity with Spring Data.

Simple repositories such as the following will, of course, work as expected:

However, it is recommended to extend the CoherenceRepository interface, to fully utilize the features Coherence for Spring Data has to offer such as:

Please also see the chapter Using the Repository API of the Coherence reference documentation for more details on these features.

Example extending the blocking CoherenceRepository interface:

or for the non-blocking flavor:

As Coherence is, at its core, a key-value store, mapping Entities for use with a Coherence Repository is relatively simple as only the id needs to be annotated. It is possible to use either org.springframework.data.annotation.Id or javax.persistence.Id to denote the entity’s id.

For example:

In order to enable Coherence-based Repositories, you must use the @EnableCoherenceRepositories annotation. A simple configuration example would be:

Similarly to other Spring Data implementations, the @EnableCoherenceRepositories annotation offers several configuration options to configure how Spring will search for repositories. Please see the API docs for details.

Spring Data Coherence module supports projections as defined in Spring Data Projections documentation. This allows us, among other things, to transfer a subset of the entities properties when closed projections are used.

Imagine a repository and aggregate root type such as the following example:

In order to start using Coherence with Spring Boot you have to add the coherence-spring-boot-starter dependency as well as the desired version of Coherence.

By adding the coherence-spring-boot-starter dependency, AutoConfiguration will be activated via the CoherenceAutoConfiguration class. This will also bind the CoherenceProperties class for further configuration. The YAML configuration for Spring Boot’s Coherence support may look like the following:

The following configuration properties are available.

Session-related configuration properties are defined based on the session type in:

If the provided Spring Boot configuration properties are not sufficient for your needs, you can also specify any of the native Coherence properties. For a list of available native properties, please consult the reference guide chapter on System Property Overrides.

Since Spring Boot 2.4.x, you can define your own custom config locations. This allows you to import these config locations as property sources. As such, Coherence Spring allows you to use a Coherence cluster as a source of configuration data for your Spring Boot based applications.

You can trigger the import of remote configuration properties with the Spring Boot property spring.config.import using the value coherence:. You will also need the corresponding Coherence config-client configured to specify any remote connection settings for your Coherence cluster as well as settings specifying how properties will be applied, e.g., the name of the application used to fetch remote properties.

Many properties have sensible default values. Please see class CoherenceConfigClientProperties for details.

If you have not already done so, please read the chapter Configuring Coherence Cache for Spring first.

In this chapter, we see how we can use caching with Coherence in Spring Boot. As long as coherence-spring-boot-starter is added to your project, and caching is enabled via @EnableCaching, Coherence Autoconfiguration will automatically provide a CoherenceCacheManager (implementing Spring’s CacheManager) to the ApplicationContext. However, the CacheManager is only added if no CacheManager was configured explicitly beforehand.

Once that is in place, you can take advantage of Spring’s Cache abstraction backed by Coherence and use Spring’s annotations such as @Cacheable, @CacheEvict, @CachePut etc.

Spring’s cache abstraction is not your only option with regard to caching. Another option is to use Hibernate’s Second-Level cache support.

When using only Hibernate’s second-level cache without the requirement of using Coherence for non-Hibernate application needs, you may want to disable Coherence’s auto-configuration support for Spring Boot as it is not needed:

In order to configure Hibernate Second-Level Caching for Coherence using Spring Boot, you simply have to set the Hibernate property hibernate.cache.region.factory_class to com.oracle.coherence.hibernate.cache.CoherenceRegionFactory.

Your Spring Boot application.yaml file may look like the following:

For more detailed information please see the Caching chapter of the Hibernate reference documentation.

Coherence Spring also provides support for Spring Session. This includes auto-configuration support as well as a set of Coherence-specific configuration properties. Before you continue, please consider reading the chapter on Coherence Spring Session first.

In order to activate Spring Session support for Spring Boot, you must have the following dependencies added to your project:

Basically, adding the coherence-spring-session dependency will activate the CoherenceSpringSessionAutoConfiguration class. Auto-configuration will back-off in certain situations:

The following Coherence-specific configuration properties are available:

Support for injecting Coherence Publishers is enabled automatically by adding the coherence-spring-boot-starter dependency. By default, base package to scan for @CoherencePublisher annotated interfaces is derived from the main class annotated with @SpringBootApplication. Base package can be overridden by annotating configuration class with @CoherencePublisherScan as described at Messaging with Coherence Topics.

By adding the coherence-spring-boot-starter and com.oracle.coherence.ce:coherence-micrometer dependencies auto-configuration will register CoherenceMicrometerMetrics and publish Coherence Metrics under the coherence. name.

To disable the auto-configured Coherence metrics even when coherence-micrometer module is on the classpath, set the following property:

Coherence Spring’s support for Spring Data also contain auto-configuration support for Spring Boot. The auto-configuration is activated as soon as the Coherence Spring Data dependency is added to your Spring Boot project.

There is no need to add the @EnableCoherenceRepositories annotation, as the Coherence Spring Data auto-configuration support, will automatically detect any Coherence repositories. In fact, adding @EnableCoherenceRepositories to your Spring Boot project, will cause auto-configuration to back-off.

Auto-configuration can also be de-activated by setting environment property coherence.spring.data.repositories.enabled to false.

Spring Cloud Config provides support for externalized configuration in distributed systems. It integrates seamlessly with Spring Boot applications and allows you to externalize / centralize critical application properties. Spring Cloud Config provides numerous storage backends for your configuration data and as part of Coherence Spring we also provide a backend for Oracle Coherence.

In this chapter we will cover two aspects of Coherence-specific support for Spring Cloud Config:

Let’s get started with an example to show the general functioning of Spring Cloud Config.

This demo is essentially the same as is used in the Quickstart chapter. However, we externalize some Coherence configuration using Spring Cloud Config. The source code for the demo is part of the Coherence Spring source code repository. Therefore, to get started, please clone its repository:

You now have checked out all the code for Coherence Spring! The relevant demo code for the Spring Cloud Config demo is under coherence-spring-samples/coherence-spring-cloud-config-demo/. The demo consists of 2 Maven modules:

The Config Server is essentially using 2 dependencies:

The demo client on the other hand will use the following dependencies:

The previously discussed demo application illustrated the main concepts of using Spring Cloud Config Server as a configuration backend for Oracle Coherence. For a general understanding of Spring Cloud Config Server, please consult the respective reference documentation.

Coherence Spring is essentially unaware of Spring Cloud Config Server. Coherence Spring merely takes advantage of Spring Boot’s configuration facilities. The main integration point for configuration between Spring and Oracle Coherence is the SpringSystemPropertyResolver class, which makes the properties of Spring’s Environment available to Oracle Coherence.

When using Spring Boot (and not just plain Spring Framework), we also provide the CoherenceProperties class. It provides means to expose Coherence Spring configuration options in a type-safe manner, to provide code completion via your IDE etc.

Behind the scenes using CoherenceProperties.getCoherencePropertiesAsMap() will translate the explicit Spring Boot properties into the property format used by Oracle Coherence. It is important to note that you can always provide ANY Oracle Coherence property as well.

For instance the following properties are equivalent: