This chapter provides step-by-step instructions for building and running a basic Coherence JCache example and demonstrates fundamental concepts of both JCache and the Coherence JCache provider. The sample application is a simple application that stores a domain object (the 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".
This chapter includes the following sections:
The examples in this chapter uses a simple Person
object. 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 34-1 A Simple Person Object
package com.examples; import java.io.Serializable; public class Person implements Serializable { private String m_sFirstName; private String m_sLastName; private int m_nAge; private static final long serialVersionUID = 99L; public Person(String sFirstName, String sLastName, int nAge) { m_sFirstName = sFirstName; m_sLastName = sLastName; m_nAge = nAge; } public String getFirstName() { return m_sFirstName; } public String getLastName() { return m_sLastName; } public int getAge() { return m_nAge; } public String toString() { return "Person( " +m_sFirstName + " " + m_sLastName + " : " + m_nAge + ")"; } }
Applications use the JCache API to access and interact with a cache. The API provides methods for creating and using a cache. The default cache type that Coherence uses if no cache type is defined is a local cache (local to the application process).
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.
Example 34-2 An Example JCache Application
package com.examples; import javax.cache.Cache; import javax.cache.CacheManager; import javax.cache.Caching; import javax.cache.configuration.MutableConfiguration; import javax.cache.spi.CachingProvider; public class JCacheExample { public static void main(String[] args) { CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, Object> config = new MutableConfiguration<String, Object>(); config.setStoreByValue(true).setTypes(String.class, Object.class); Cache<String, Object> cache = cacheManager.createCache("MyCache", config); Person p = new Person("John","Doe",24); String key = "k"; Person value = p; cache.put(key, value); System.out.println("\n Cache: " + cache.getName() + " contains: " + cache.get(key) + "\n"); cacheManager.close(); } }
To run the standalone application example:
From a command prompt, compile the Person.java
and JCacheExample.java
files. The following example assumes that the files are in a single directory that is referred to as APPLICATION_HOME
for the remainder of the tasks in this chapter:
cd APPLICATION_HOME javac -cp COHERENCE_HOME\lib\cache-api.jar com\examples\*
Run the JCacheExample
class and include the location of the coherence.jar
, coherence-jcache.jar
, and cache-api.ja
r libraries on the classpath using the Java -cp
option. For example:
java -cp .;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 and the Coherence cache factory being created. The application emits the entry that is in the cache and then the application exits.
Partitioned caches and pass-through caches use a Coherence cluster to distribute cached data. This task creates an operational override file to modify the out-of-box default cluster configuration. In particular, the default configuration is modified to create a private cluster which ensures that the JVM processes do not attempt to join an existing Coherence cluster that may be running on the network.
To configure an example cluster:
Create a file named tangosol-coherence-override.xml
.
Add the following override configuration and replace cluster_name
and port
with values that are unique for this cluster. For example, use your name for the cluster name and the last four digits of your phone number for the port.
<?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> <multicast-listener> <address>224.3.6.0</address> <port>port</port> <time-to-live>0</time-to-live> </multicast-listener> </cluster-config> </coherence>
Save the file to the APPLICATION_HOME
\config
directory.
A partitioned cache is a cache that distributes cache entries among any number of cache servers in a Coherence cluster. Entries that are stored in partitioned caches are backed up and persist on the cluster after the application process ends. For details about using partitioned caches with the JCache provider, see "Creating Partitioned Caches".
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.
From a command prompt, start a cache server instance using the DefaultCacheServer
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. Make sure that the operational override file and the coherence-jcache.jar
are loaded on the classpath before the coherence.jar
library. Lastly, use the tangosol.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 -Dtangosol.coherence.cacheconfig=coherence-jcache-cache-config.xml -cp APPLICATION_HOME\config;COHERENCE_HOME\lib\cache-api.jar; COHERENCE_HOME\lib\coherence-jcache.jar;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
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
The tangosol.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:
From a command prompt, run the application that was created in Example 34-2 and set the tangosol.coherence.jcache.configuration.classname
system property to partitioned
and the tangosol.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. Make sure that the operational override file and the coherence-jcache.jar
library are loaded on the classpath before the coherence.jar
library. For example:
java -Dtangosol.coherence.jcache.configuration.classname=partitioned -Dtangosol.coherence.distributed.localstorage=false -cp .;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 was loaded. Lastly, notice that the application process joins the cluster and that the jcache-partitioned-service
instance joins with the senior service on the cache server:
(thread=DistributedCache:jcache-partitioned-service, member=2): Service jcache-partitioned-service joined the cluster with senior service member 1
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:
From a command prompt, start a standalone cache factory instance using the CacheFactory
class. Use the Java -cp
option to include the APPLICATION_HOME
\config
directory. The classpath must also include the Person
object, cache-api.jar
, coherence-jcache.jar
, and coherence.jar
libraries. Make sure that the operational override file and the coherence-jcache.jar
are loaded on the classpath before the coherence.jar
library. Lastly, set the tangosol.coherence.cacheconfig
system property to coherence-jcache-cache-config.xml
and the tangosol.coherence.distributed.localstorage
system property to false
. For example:
java -Dtangosol.coherence.cacheconfig=coherence-jcache-cache-config.xml -Dtangosol.coherence.distributed.localstorage=false -cp APPLICATION_HOME\config;APPLICATION_HOME\person.jar; COHERENCE_HOME\lib\cache-api.jar;COHERENCE_HOME\lib\coherence-jcache.jar; COHERENCE_HOME\lib\coherence.jar com.tangosol.net.CacheFactory
The cache factory instance starts and becomes a member of the cluster and returns a command prompt for the command-line tool.
At the command-line tool command prompt, get the MyCache
cache using the cache
command:
cache jcache-partitioned-coherence-jcache-cache-config.xml$MyCache
Note:
For the purpose of this example, the cache name includes the application scope. Applications do not need to explicitly include the application scope when using a cache.At the command-line tool command prompt, retrieve the contents of the cache using the list
command.
list
The command returns and displays:
k = Person( John Doe : 24)
Shutdown all processes.
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). Pass-through caches allow you to use all of the native features of Coherence and provide greater control over cache configuration.
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.
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:
Create an XML file named example-config.xml
.
Copy the following distributed cache definition to the file:
<?xml version="1.0"?> <cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd"> <caching-scheme-mapping> <cache-mapping> <cache-name>MyCache</cache-name> <scheme-name>distributed</scheme-name> </cache-mapping> </caching-scheme-mapping> <caching-schemes> <distributed-scheme> <scheme-name>distributed</scheme-name> <service-name>DistributedCache</service-name> <backing-map-scheme> <local-scheme/> </backing-map-scheme> <autostart>true</autostart> </distributed-scheme> </caching-schemes> </cache-config>
Save the file to the APPLICATION_HOME
\config
directory.
From a command prompt, start a cache server instance using the DefaultCacheServer
class and use the Java -cp
option to include the APPLICATION_HOME
\config
directory and the coherence.jar
library. Make sure that the operational override file is loaded on the classpath before the coherence.jar
library. Lastly, use the tangosol.coherence.cacheconfig
system property to explicitly define the example-config.xml
cache configuration file. For example:
java -Dtangosol.coherence.cacheconfig=example-config.xml -cp APPLICATION_HOME\config;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
The tangosol.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 tangosol.coherence.jcache.configuration.classname
system property to passthrough
, the tangosol.coherence.cacheconfig
system property to example-config
, and the tangosol.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. Make sure that the operational override file is loaded on the classpath before the coherence.jar
library. For example:
java -Dtangosol.coherence.jcache.configuration.classname=passthrough -Dtangosol.coherence.cacheconfig=example-config.xml -Dtangosol.coherence.distributed.localstorage=false -cp .;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.
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:
From a command prompt, start a standalone cache factory instance using the CacheFactory
class. Use the Java -cp
option to include the APPLICATION_HOME
\config
directory. The classpath must also include the Person
object and the coherence.jar
library. Make sure that the operational override file is loaded on the classpath before the coherence.jar
library. Lastly, set the tangosol.coherence.cacheconfig
system property to example-config.xml
and the tangosol.coherence.distributed.localstorage
system property to false
. For example:
java -Dtangosol.coherence.cacheconfig=example-config.xml -Dtangosol.coherence.distributed.localstorage=false -cp APPLICATION_HOME\config;APPLICATION_HOME\person.jar; COHERENCE_HOME\lib\coherence.jar com.tangosol.net.CacheFactory
The cache factory instance starts and becomes a member of the cluster and returns a command prompt for the command-line tool.
At the command-line tool command prompt, get the MyCache
cache using the cache
command:
cache MyCache
At the command-line tool command prompt, retrieve the contents of the cache using the list
command.
list
The command returns and displays:
k = Person( John Doe : 24)