59 Building Your First Coherence JCache Application
Person object) into a cache. The example demonstrates using a local cache, a partitioned cache, and a pass-through cache.
If you are new to Coherence, you may consider also running the native Coherence NamedCache example. See Building Your First Coherence Application.
Application and Provider Lifecycle
Use Java 21 or later and the matching 26.1.0.0.0 Coherence/JCache artifacts. Configure the intended provider, cache URI, and class loader once, then reuse the CacheManager. Standard JCache entry processors and listeners have their own interfaces; when their definitions cross a Coherence boundary, provide the required application data/executable metadata as well.
This chapter includes the following sections:
- Task 1: Create a Simple Object
Create a simplePersonobject to be cached using the Coherence JCache provider. - Task 2: Store the Object in a Local Cache
Applications use the JCache API to access and interact with a cache. - Task 3: Configure an Example Cluster
Partitioned caches and pass-through caches use a Coherence cluster to distribute cached data. - Task 4: Store the Object in a Partitioned Cache
A partitioned cache is a cache that distributes cache entries among any number of cache servers in a Coherence cluster. - Task 5: Store the Object in a Pass-Through Cache
A pass-through cache is a cache that delegates to a pre-existing Coherence cache (a cache that is defined in a Coherence cache configuration file).
Parent topic: Using the Coherence JCache Implementation
Task 1: Create a Simple Object
Person object to be cached using the Coherence JCache provider.The Person object contains a constructor and three fields for a first name, last name, and age. The Person object implements the Serializable interface. Serialization is required when the object is stored in a partitioned cache.
Example 59-1 A Simple Person Object
package com.examples;
import com.tangosol.util.function.Remote;
import java.io.Serializable;
@Remote.Allowed
public record Person(String firstName, String lastName, int age) implements Serializable {
public String getFirstName() { return firstName; }
public String getLastName() { return lastName; }
public int getAge() { return age; }
}Parent topic: Building Your First Coherence JCache Application
Task 2: Store the Object in a Local Cache
This section includes the following topics:
Parent topic: Building Your First Coherence JCache Application
Create the Sample JCache Application
The following application stores a single Person object to a local cache. The application demonstrates getting a cache provider, creating a cache manager, configuring and creating a cache, and using the cache.
Build and metadata prerequisites
Use the matching 26.1 coherence-jcache provider and standard javax.cache API. Compile Person and JCacheExample in the same com.examples package. The Person record uses Java 21 or later and preserves JavaBean-style accessors for the examples that follow.
Run the security-config-maven-plugin generate goal during process-classes so Person’s @Remote.Allowed annotation produces META-INF/coherence/security-config.xml. Package that resource with the model and put the artifact on every required classpath. The default local-cache walkthrough uses Java serialization; POF examples additionally need POF type registration. See Generating Application Security Configuration.
Example 59-2 An Example JCache Application
package com.examples;
import javax.cache.Cache;
import javax.cache.Caching;
import javax.cache.configuration.MutableConfiguration;
public class JCacheExample {
public static void main(String[] args) {
var provider = Caching.getCachingProvider();
try (var manager = provider.getCacheManager()) {
var config = new MutableConfiguration<String, Person>()
.setStoreByValue(true)
.setTypes(String.class, Person.class);
Cache<String, Person> cache = manager.createCache("MyCache", config);
cache.put("k", new Person("John", "Doe", 24));
System.out.println("Cache: " + cache.getName() + " contains: " + cache.get("k"));
}
}
}Parent topic: Task 2: Store the Object in a Local Cache
Run the Sample JCache Application
To run the standalone application example:
Project setup
Use the complete pom.xml in Building Examples with Application Security Metadata and put both source files under src/main/java/com/examples. The Maven build compiles the Java 21 sources, generates the allowed Person metadata and packages target/person.jar. For a partitioned or pass-through variant, put that artifact on the storage member classpath as well as the application classpath. The run command assumes the matching provider/API libraries from the installed distribution; translate the quoted classpath as described in the programming introduction on Windows.
Parent topic: Task 2: Store the Object in a Local Cache
Task 3: Configure an Example Cluster
To configure an example cluster:
-
Create a file named
tangosol-coherence-override.xml. -
Add the following override configuration and replace
cluster_namewith a value that is unique for this cluster. For example, use your name for the cluster name.<?xml version='1.0'?> <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config coherence-operational-config.xsd"> <cluster-config> <member-identity> <cluster-name>cluster_name</cluster-name> </member-identity> </cluster-config> </coherence> -
Save the file to the
APPLICATION_HOME\configdirectory.
Parent topic: Building Your First Coherence JCache Application
Task 4: Store the Object in a Partitioned Cache
In this task, two separate Java processes form the cluster: a cache server process and the JCacheExample application process. For simplicity, the two processes are collocated on a single computer. The cache server, by default, is configured to store cache data. Lastly, a Coherence CacheFactory is used to verify that the JCacheExample application successfully created and loaded the cache on the cluster.
This section includes the following topics:
Parent topic: Building Your First Coherence JCache Application
Start the Example Cache Server
From a command prompt, start a cache server instance using the Coherence class and use the Java -cp option to include the APPLICATION_HOME\config directory. The classpath must also include the cache-api.jar, coherence-jcache.jar, and coherence.jar libraries. Ensure that the operational override file and the coherence-jcache.jar are loaded on the classpath before the coherence.jar library. Lastly, use the coherence.cacheconfig system property to explicitly use the JCache coherence-jcache-cache-config.xml cache configuration file that is located in the coherence-jcache.jar. For example:
java -Dcoherence.cacheconfig=coherence-jcache-cache-config.xml -cp "$APPLICATION_HOME/target/person.jar:$APPLICATION_HOME/config:$COHERENCE_HOME/lib/cache-api.jar:$COHERENCE_HOME/lib/coherence-jcache.jar:$COHERENCE_HOME/lib/coherence.jar" com.tangosol.net.Coherence
From the cache server output, notice that a distributed cache service that is called jcache-partitioned-service is created and is the senior member of the cluster:
(thread=DistributedCache:jcache-partitioned-service, member=1): Service jcache-partitioned-service joined the cluster with senior service member 1
Parent topic: Task 4: Store the Object in a Partitioned Cache
Run The Application
The coherence.jcache.configuration.classname system property configures the Coherence JCache provider to use a partitioned cache instead of a local cache. The application code does not need to be modified in any way, which allows portability between JCache providers. In addition, Coherence manages the application scope and cache configuration.
To store the Person object in a partitioned cache:
Parent topic: Task 4: Store the Object in a Partitioned Cache
Verify the Cache
The cache server in this example is configured, by default, to store the cache's data. The data is available to all members of the cluster and persists even after members leave the cluster. For example, the application exits after it loads and displays a key in the cache. However, the cache and key are still available for all cluster members.
This step uses the cache factory command-line tool to connect to the cache and list all items in the cache.
To verify the cache:
Parent topic: Task 4: Store the Object in a Partitioned Cache
Task 5: Store the Object in a Pass-Through Cache
In this task, two separate Java processes form the cluster: a cache server process and the JCacheExample application process. For simplicity, the two processes are collocated on a single computer. The cache server, by default, is configured to store cache data. Lastly, a Coherence CacheFactory is used to verify that the JCacheExample application successfully created and loaded the cache on the cluster.
This section includes the following topics:
Parent topic: Building Your First Coherence JCache Application
Define the Example Cache
For this example, a cache configuration is created that defines a distributed cache that is explicitly mapped to the MyCache name.
To define the example cache:
Parent topic: Task 5: Store the Object in a Pass-Through Cache
Start the Example Cache Server
From a command prompt, start a cache server instance using the Coherence class and use the Java -cp option to include the APPLICATION_HOME\config directory and the coherence.jar library. Ensure that the operational override file is loaded on the classpath before the coherence.jar library. Lastly, use the coherence.cacheconfig system property to explicitly define the example-config.xml cache configuration file. For example:
java -Dcoherence.cacheconfig=example-config.xml -cp "$APPLICATION_HOME/target/person.jar:$APPLICATION_HOME/config:$COHERENCE_HOME/lib/coherence.jar" com.tangosol.net.Coherence
Parent topic: Task 5: Store the Object in a Pass-Through Cache
Run the Application
The coherence.jcache.configuration.classname system property configures the Coherence JCache provider to use a pass-through cache. The application code does not need to be modified in any way.
From a command prompt, run the JCacheExample class and set the coherence.jcache.configuration.classname system property to passthrough, the coherence.cacheconfig system property to example-config, and the coherence.distributed.localstorage system property to false. Use the Java -cp option to include the APPLICATION_HOME\config directory. The classpath must also include the cache-api.jar, coherence-jcache.jar, and coherence.jar libraries. Ensure that the operational override file is loaded on the classpath before the coherence.jar library. For example:
java -Dcoherence.jcache.configuration.classname=passthrough -Dcoherence.cacheconfig=example-config.xml -Dcoherence.distributed.localstorage=false -cp "$APPLICATION_HOME/target/person.jar:$APPLICATION_HOME/config:$COHERENCE_HOME/lib/cache-api.jar:$COHERENCE_HOME/lib/coherence-jcache.jar:$COHERENCE_HOME/lib/coherence.jar" com.examples.JCacheExample
Coherence log messages are emitted that indicate the Coherence configuration resources that are being used. Notice that the tangosol-coherence-override.xml file and example-config.xml file were loaded. The application process connects to the cluster that contains the cache server process and both processes are running the DistributedCache service. As before, the application emits the entry that is in the cache and then the application exits.
Parent topic: Task 5: Store the Object in a Pass-Through Cache
Verify the Cache
The cache server in this example is configured, by default, to store the cache's data. The data is available to all members of the cluster and persists even after members leave the cluster. For example, the application exits after it loads and displays a key in the cache. However, the cache and key are still available for all cluster members.
This step uses the cache factory command-line tool to connect to the MyCache cache and list all items in the cache.
To verify the cache:
Parent topic: Task 5: Store the Object in a Pass-Through Cache