This chapter includes the following sections:
META-INF/services/javax.cache.spi.CachingProvider
service definition assures that applications using the javax.cache.Caching
bootstrap class use the Coherence JCache provider by default.MutableConfiguration
class during cache creation.coherence-pof-config.xml
file.CacheMXBean
and CacheStatisticsMXBean
JMX MBeans.Parent topic: Using the Coherence JCache Implementation
META-INF/services/javax.cache.spi.CachingProvider
service definition assures that applications using the javax.cache.Caching
bootstrap class use the Coherence JCache provider by default.coherence-jcache.jar
library. The instructions and examples in this chapter assume that the Coherence JCache provider is the default JCache provider. However, applications are able to register and use multiple cache providers. In such cases, applications have several options to select the Coherence JCache provider.
Note:
If multiple JCache providers are registered, then the use of the getCachingProvider()
or getCachingProvider(ClassLoader)
methods result in a cache exception.
The first option is to override the default cache provider using the javax.cache.spi.cachingprovider
system property and specifying the fully qualified name of the Coherence JCache provider implementation class. For example:
System.setProperty("javax.cache.spi.cachingprovider", "com.tangosol.coherence.jcache.CoherenceBasedCachingProvider");
The system property can also be specified on the command line at runtime. For example,
-Djavax.cache.spi.cachingprovider=com.tangosol.coherence.jcache. CoherenceBasedCachingProvider
The second option is to use the Caching.getCachingProvider(String)
or Caching.getCachingProvider(String, ClassLoader)
methods to explicitly request the Coherence JCache provider implementation. For example:
CachingProvider cachingProvider = Caching.getCachingProvider( "com.tangosol.coherence.jcache.CoherenceBasedCachingProvider"); CacheManager cacheManager = cachingProvider.getCacheManager(); ...
Use the getCachingProviders
methods to iterate the list of registered providers if multiple caching providers are registered.
Lastly, applications can directly instantiate the Coherence JCache provider. However, this option is not portable across providers. The following example instantiates the Coherence JCache provider:
CachingProvider cachingProvider = new CoherenceBasedCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager();
Parent topic: Performing Basic Coherence JCache Tasks
This section includes the following topics:
Parent topic: Performing Basic Coherence JCache Tasks
Applications can cache data using a local cache. Local caches are the default cache type when using the Coherence JCache provider and are similar to a Coherence local cache scheme. Local caches do not provide data backup and the data does not persist after the application process exits. The following example creates a local cache using the JCache API.
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, String> config = new MutableConfiguration<String, String>(); config.setStoreByValue(true).setTypes(String.class, String.class); Cache<String, String> cache = cacheManager.createCache("MyCache", config);
A local cache results in the creation of a Coherence NamedCache
instance that use jcache-local-*
cache names that are mapped to a local cache scheme that is named jcache-local-scheme
, which is managed by the jcache-local-service
service.
Parent topic: Creating Coherence JCache Caches
Applications can cache data to a Coherence partitioned cache. The application process automatically joins a Coherence cluster and Coherence manages the distribution and backup of the data across the cluster. Partitioned caches do not require any application code changes; therefore, existing JCache applications can easily be migrated to use Coherence partitioned caches.
Note:
Partitioned caches do not support store-by-reference semantics.
To create a partitioned cache, use the tangosol.coherence.jcache.configuration.classname
property and set it to partitioned
. For example:
-Dcoherence.jcache.configuration.classname=partitioned
The system property also supports a value of local
, which is the default value if no value is specified and results in a local cache being created.
A partitioned cache results in the creation of a Coherence NamedCache
instance that use jcache-partitioned-*
cache names that are mapped to a partitioned cache scheme that is named jcache-partitioned-scheme
, which is managed by the jcache-partitioned-service
service.
Operational Configuration
JCache applications must use a tangosol-coherence-override.xml
operational override file or Coherence system properties, or both, to configure Coherence operational settings. The operational settings, among other things, allow applications to join an existing cluster. See Specifying an Operational Configuration File. For example, an application can specify the following system properties at runtime to join a cluster that is named Cluster1
and has a multicast address of 231.1.1.1
and port 7574
.
-Dcoherence.cluster=Cluster1 -Dcoherence.clusteraddress=231.1.1.1 -Dcoherence.clusterport=7574
Cache Configuration
Partitioned caches for JCache automatically use a default Coherence cache configuration file that is included in the coherence-jcache.jar
library. The configuration file is called coherence-jcache-cache-config.xml
. Any cache servers in the cluster must also use the coherence-jcache-cache-config.xml
file. For example, a cache server can explicitly set the cache configuration file using the coherence.cacheconfig
system property:
-Dcoherence.cacheconfig=coherence-jcache-cache-config.xml
You can also use an existing Coherence cache configuration file. See Using Native Coherence Functionality from JCache.
Parent topic: Creating Coherence JCache Caches
Applications can use a pass-through cache to delegate all cache operations to pre-existing Coherence caches. A pass-through cache results in the use of a native Coherence NamedCache
instance from a JCache interface. A pass-through cache allows an application to take full advantage of all Coherence native features and configuration.
To create a pass-through cache, an application can use the Coherence PassThroughCacheConfiguration
JCache configuration object and specify the name of an existing cache mapping that is defined in a Coherence cache configuration file. For example:
... CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); PassThroughCacheConfiguration<String, Object> config = new PassThroughCacheConfiguration<String, Object>(); config.setTypes(String.class, Object.class); Cache<String, Object> cache = cacheManager.createCache("MyCache", config);
As an alternative, existing JCache applications can continue to use a MutableConfiguration
object and create a pass-through cache by specifying the coherence.jcache.configuration.classname
property and setting the value to passthrough
. For example:
-Dcoherence.jcache.configuration.classname=passthrough
The system property allows JCache applications to use Coherence native features without having to change any application code. However, most MutableConfiguration
object properties are ignored. A warning message is emitted if the system property is used to create a pass-through cache.
WARNING: Lossy conversion of configuration javax.cache.configuration.MutableConfiguration to a PassThroughConfiguration. Most properties from class javax.cache.configuration.MutableConfiguration are ignored. Configure PassThroughCache using native Coherence configuration methodologies.
Operational Configuration
Pass-through caches for JCache use a tangosol-coherence-override.xml
operational override file or Coherence system properties, or both, to configure Coherence operational settings. The operational settings, among other things, allow applications to join an existing cluster. See Specifying an Operational Configuration File.
Cache Configuration
Pass-through caches for JCache use an existing Coherence cache configuration file. Applications can specify the location of the file at runtime using the coherence.cacheconfig
property. For example:
-Dcoherence.cacheconfig=my-cache-config.xml
The above technique changes the default URI a cache manager uses to get a specified cache configuration file. An alternative way to specify a cache configuration that uses the JCache API and does not rely on setting a system property is to specify the URI when creating a cache manager. For example:
Caching.getCacheManager(new URI(my-cache-config.xml), null, null);
Any cache created from the above returned cache manager uses the specified cache configuration file to the getCacheManager
call. See Specifying a Cache Configuration File.
Parent topic: Creating Coherence JCache Caches
Applications can cache data to a remote Coherence partitioned cache. The application process connects to a Coherence proxy service on the cluster and Coherence manages the distribution and backup of the data across the cluster. Remote caches rely on Coherence*Extend. See Overview of Coherence*Extend in Developing Remote Clients for Oracle Coherence. Remote caches do not require any application code changes; therefore, existing JCache applications can easily be migrated to use Coherence remote caches.
To create a remote cache, use the tangosol.coherence.jcache.configuration.classname
property and set it to remote
. For example:
-Dcoherence.jcache.configuration.classname=remote
A remote cache results in the creation of a Coherence NamedCache
instance that use jcache-extend-*
cache names that are mapped to a remote cache scheme that is named jcache-extend-tcp
. The cache is configured to connect to the cluster using a proxy service that is named TCPProxyService
.
Operational Configuration
JCache applications must use a tangosol-coherence-override.xml
operational override file or Coherence system properties, or both, to configure Coherence operational settings if required. See Specifying an Operational Configuration File.
Cache Configuration
Remote caches for JCache automatically use a default Coherence cache configuration file that is included in the coherence-jcache.jar
library. The configuration file is called coherence-jcache-extendclient-cache-config.xml
. In addition, at least one cache servers in the cluster must use the coherence-jcache-server-proxy-cache-config.xml
file, which defines the proxy service. For example, a cache server can explicitly set the cache configuration file using the coherence.cacheconfig
system property:
-Dcoherence.cacheconfig=coherence-jcache-server-proxy-cache-config.xml
You can also choose to use an existing Coherence cache configuration file. See Using Native Coherence Functionality from JCache.
Parent topic: Creating Coherence JCache Caches
The Coherence JCache provider allows applications to use native Coherence functionality. Applications that use native Coherence functionality are not portable among JCache providers. Applications typically use native functionality to reuse existing Coherence implementations and configuration.
This section includes the following topics:
Parent topic: Creating Coherence JCache Caches
JCache applications can directly access the underlying Coherence NamedCache
instance for a cache. A cache cannot be accessed directly using the NamedCache
and JCache API interchangeably. In addition, using the NamedCache
instance to access cache keys and values bypasses additional behavior provided by the Coherence JCache provider implementation.
The following example directly accesses the underlying NamedCache
instance for a JCache cache and uses the instance to put and get an entry:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, String> config = new MutableConfiguration<String, String>(); config.setStoreByValue(true).setTypes(String.class, String.class); Cache<String, String> cache = cacheManager.createCache("MyCache", config); String key = "k"; String value = "Hello World"; NamedCache nc = cache.unwrap(NamedCache.class); nc.put(key, value); System.out.println("The value is " + nc.get(key) + "\n"); nc.destroy(); cacheManager.close();
Parent topic: Using Native Coherence Functionality from JCache
Any native Coherence concept that does not have an equivalent JCache concept (such as eviction) can be configured using a Coherence cache configuration file, operational override file, or Coherence system properties.
Note:
Applications that are designed to be portable across JCache provider implementations should only rely on the configuration that is provided through the JCache CompleteConfiguration
API.
When using an existing Coherence cache configuration file for JCache partitioned and local caches, then the file must include a jcache
namespace handler definition. For example:
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config" xmlns:jcache="class://com.tangosol.coherence.jcache.JCacheNamespace" xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd"> ...
The JCache namespace handler generates any missing elements that are required for the JCache-specific cache configuration file and allows an applications to extend the standard cache configuration file. The JCache namespace handler does not generate an element if it is already defined in the cache configuration file.
Parent topic: Using Native Coherence Functionality from JCache
MutableConfiguration
class during cache creation. This is a standard JCache class and should be used to maintain portability among JCache providers. For example:MutableConfiguration<String, String> config = new MutableConfiguration<String, String>(); config.setStoreByValue(true).setTypes(String.class, String.class); Cache<String, String> cache = cacheManager.createCache("MyCache", config);
Applications that use local and partitioned caches can optionally use the Coherence JCache provider-specific implementations of the JCache CompleteConfiguration
API. The implementations are LocalCacheConfiguration
and PartitionedCacheConfiguration
, respectively. However, the use of these classes is not portable among JCache providers. For example:
PartitionedCacheConfiguration<String, String> config = new PartitionedCacheConfiguration<String, String>(); config.setStoreByValue(true).setTypes(String.class, String.class);
Application that use pass-through caches, require the Coherence JCache provider PassThroughCacheConfiguration
configuration class. Pass-through caches are configured using native Coherence configuration and therefore do not support using JCache-specific configuration options.
PassThroughCacheConfiguration<String, String> config = new PassThroughCacheConfiguration<String, String>();
This section includes the following topics:
Parent topic: Performing Basic Coherence JCache Tasks
JCache provides the option to specify whether a cache uses store-by-reference or store-by-value semantics. The setStoreByValue
method configures store-by semantics for both keys and values. A value of true
indicates store-by-value semantics and a value of false
indicates store-by-reference semantics. The Coherence JCache provider uses store-by-value semantics by default for all cache types and only supports store-by-reference for local caches. Partitioned caches do not support store-by-reference. In addition, the provider relies on either Java Serialization or POF to implement store-by-value semantics for all Coherence JCache cache types. Applications that use local caches and configure store-by-reference do not require that keys and values be serializable or POF-enabled.
The following example configures a local cache to use store-by-reference semantics.
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>(); config.setStoreByValue(false); Cache<String, Integer> cache = cacheManager.createCache("MyCache", config);
Note:
If store-by-reference is enabled, the cache can be mutated by any threads holding a reference to the cache. Keys that are mutated may not be retrievable. In addition, values that are mutated may be observed by all threads in the JVM if Java permissions are not properly set. Beyond the local heap, entries need to be transformed into a representation and any mutations that occur after the transformation may not be reflected in the cache.
Parent topic: Configuring Coherence JCache Caches
JCache allows you to set the expected key and value types of an entry. Any entry that is placed in the cache must then adhere to the declared types; otherwise, a runtime exception occurs. The setTypes
method is used to configure the entry types, which cannot be set to null
. The following example sets the key type to String
and the value type to Integer
:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>(); config.setTypes(String.class, Integer.class); Cache<String, Integer> cache = cacheManager.createCache("MyCache", config);
Note:
The Coherence JCache implementation does not perform runtime checks to ensure that objects passed into mutative cache operations match with what was configured through the javax.cache.configuration.Configuration
API. Applications should use generics to operate on the cache and take advantage of static compile time checking.
The default key and value type, if no type is configured, is Object.class
. Using the default type or explicitly configuring the Object.class
type disables runtime type checking and allows and application to use any key or value type. However, it is then the responsibility of the application to ensure type safety. The following example disables type checking by explicitly setting the key and value types to Object.class
and omitting the type parameters when getting the cache:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<Object, Object> config = new MutableConfiguration<Object, Object>(); config.setStoreByValue(true).setTypes(Object.class, Object.class); Cache<Object, Object> cache = cacheManager.getCache("MyCache");
Although it is not required, the above examples also use compile-time type checking. When omitted, the compiler will not check for type safety. The following example disables both compile-time and runtime type checking.
MutableConfiguration config = new MutableConfiguration(); cacheManager.createCache("MyCache", config);
Parent topic: Configuring Coherence JCache Caches
JCache allows you to configure the amount of time an entry is available in a cache. Entries that expire are no longer valid and are not available to an application.
Note:
The Coherence JCache provider may evict entries that are not due to expire if the maximum cache capacity is reached. Cache entries are evicted using a default eviction policy that is based on a combination of how often and recently entries are accessed. Entries that are accessed least frequently and are not accessed for the longest period are evicted first.
Expiry is configured using the setExpiryPolicyFactory
method to select an expiry policy and to set a time value. The following example configures entries in the cache to expire 5 minutes after they are created:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>(); config.setExpiryPolicyFactory(CreatedExpiryPolicy.factoryOf( Duration.FIVE_MINUTES)); Cache<String, Integer> cache = cacheManager.createCache("MyCache", config);
If the policy is set to null
or if expiry is not configured, then the eternal policy is used by default and entries are never expired. Each policy can specify the duration of time that must pass before a cache entry is considered expired. For convenience, pre-defined durations are provided: ZERO
, ONE_MINUTE
, FIVE_MINUTES
, TEN_MINUTES
, TWENETY_MINUTES
, THIRTY_MINUTES
, ONE_HOUR
, and ONE_DAY
. Any non-negative duration value can be configured.
The following expiry policies are supported:
Created – Cache entries are expired based on when they are created. An update does not reset the expiry time. This policy is implemented in the JCache CreatedExpiryPolicy
class.
Accessed – Cache entries are expired based on the last time they accessed. Accessed does not include a cache update. This policy is implemented in the JCache AccessedExpiryPolicy
class.
Modified – Cache entries are expired based on the last time it was updated. Updating includes created and changing (updating) an entry. This policy is implemented in the JCache ModifiedExpiryPolicy
class.
Touched – Cache Entry based on when it was last touched. A touch includes creation, update or access. This policy is implemented in the JCache TouchedExpiryPolicy
class.
Eternal (default) – Cache entries are never expired. This policy is implemented in the JCache EternalExpiryPolicy
class.
Expiry policies and durations must be serialized to support distributed caching scenarios. The Coherence JCache provider uses Portable Object Format (POF) for serialization and includes POF serializers for expiry types. These types must be configured to be used by the Coherence JCache provider if partitioned caches are used together with pass-through caches. See Configuring a JCache POF Configuration file.
Parent topic: Configuring Coherence JCache Caches
Read-through and write-through caching allow applications to load data into a cache from a data source and to write data from a cache into a data source. Databases are the most common data source integration, but any data source can be integrated with JCache caches. Read-through and write-through caching are not enabled by default and require application-specific implementations of the JCache CacheLoader
and CacheWriter
interfaces, respectively.
To enable read-through or write-through caching, set the setReadThrough
and setWriteThrough
methods, respectively, to true
. For example:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>(); config.setReadThrough(true).setWriteThrough(true); Cache<String, Integer> cache = cacheManager.createCache("MyCache", config);
To register a CacheLoader
and CacheWriter
implementation, use the setCacheLoaderFactory
and setCacheWriterFactory
methods, respectively, and enter the fully qualified name of the implementation class. For example:
cacheWriter = new MyCacheWriter(); cacheLoader = new MyCacheLoader(); MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>(); config.setReadThrough(true).setWriteThrough(true) .setCacheWriterFactory(FactoryBuilder.factoryOf(cacheWriter)); .setCacheLoaderFactory(FactoryBuilder.factoryOf(cacheLoader)); Cache<String, Integer> cache = cacheManager.createCache("MyCache", config);
The implementations are automatically used when performing certain cache operations. See Using Read-Through and Write-Through Caching.
Parent topic: Configuring Coherence JCache Caches
JCache provides two dynamic mbeans: the CacheMXBean
and CacheStatisticsMXBean
mbeans. The CacheMXBean
mbean shows the configuration settings of a cache. The CacheStatisticsMXBean
mbean shows performance statistics for a cache. See Viewing JCache Management Information.
Management is disabled by default. To enable management information, set the setManagementEnabled
and setStatisticsEnabled
methods to true
when configuring a cache. For example:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration config = new MutableConfiguration(); config.setManagementEnabled(true).setStatisticsEnabled(true); Cache cache = cacheManager.createCache("MyCache", config);
Management can also be enabled at runtime using the cache manager:
CachingProvider cachingProvider = Caching.getCachingProvider(); CacheManager cacheManager = cachingProvider.getCacheManager(); MutableConfiguration config = new MutableConfiguration(); Cache cache = cacheManager.createCache("MyCache", config); cacheManager.enableManagement("MyCache", true); cacheManager.enableStatistics("MyCache", true);
Parent topic: Configuring Coherence JCache Caches
javax.cache.Cache
interface. Refer to the Cache
API documentation for the semantics and details of all the available JCache operations.A cache must first be created and configured before cache operations can be performed. The following example demonstrates performing simple put
and get
operations:
Note:
Key and values cannot be null
.
CachingProvider provider = Caching.getCachingProvider(); CacheManager cacheManager = provider.getCacheManager(); MutableConfiguration config = new MutableConfiguration(); Cache cache = cacheManager.createCache("MyCache", config); cache.put("k1", "Hello World"); System.out.println("The value is " + cache.get("k1")+ "\n");
The above example does not perform compile or runtime entry type checking. See Setting Cache Entry Types.
Understanding Coherence JCache Operations
Cache operations are implemented differently for each cache type: LocalCache
, PartitionedCache
, and PassThroughCache
. For example, partitioned cache operations are implemented using Coherence entry processors that can take advantage of Coherence data serialization. Each of the cache types provides implementations of cache operations that take advantage of the cache topology being used.
Parent topic: Performing Basic Coherence JCache Tasks
CacheLoader
and CacheWriter
interfaces, respectively. Read-through and writer-through caching are not enabled by default. See Enabling Read-Through and Write-Through Caching.
Note:
Applications that choose to use a Coherence pass-through cache, can use read-through and write-through caching natively in Coherence and are not required to include JCache specific loader and writer implementations.
This section includes the following topics:
Parent topic: Performing Basic Coherence JCache Tasks
Read-through caching requires an application to implement the CacheLoader
interface. The implementation details are specific to the external resource that is being used. For details about implementing CacheLoader
methods, refer to the JCache API documentation.
The CacheLoader
interface provides the load
and loadAll
methods. An implementation uses these methods to include the necessary logic to connect and retrieve a value, or set of values, from an external resource. A cache loader implementation is automatically invoked whenever an entry for a given key is not found as a result of performing a get
, getAll
, getAndRemove
, or getAndReplace
operation. When using entry processors, the invoke
and invokeAll
operations automatically use the cache loader if the entry processor uses the getValue
method. See Processing JCache Entries.
Parent topic: Using Read-Through and Write-Through Caching
The Cache
API includes the Cache.loadAll
method that can be used to pre-load a cache. The use of this method results in a call to the loadAll
method of a CacheLoader
implementation. In this case, the CacheLoader
implementation must still be configured on the cache, but read-through caching does not need to be enabled. For example:
cacheLoader = new MyCacheLoader(); MutableConfiguration<String, String> config = new MutableConfiguration<String, String>(); config.setTypes(String.class, String.class) .setReadThrough(false) .setCacheLoaderFactory(FactoryBuilder.factoryOf(cacheLoader));
In the above example, the factoryOf
method takes an instance of the MyCacheLoader
implementation. The method is used for implementations that have state and requires that the implementation class be serializable. If the implementation does not have state, then it is best to use the factoryOf(Class)
or factoryOf(String classname)
methods instead.
Loading a cache from an external resource may take a long time to complete. The CompletionListener
interface allows an application to be notified when the cache has been loaded or if an exception has occurred while loading the cache. The CompletionListenerFuture
class is a default implementation that can be used as required. For example:
cacheLoader = new MyCacheLoader(); MutableConfiguration<String, String> config = new MutableConfiguration<String, String>(); config.setTypes(String.class, String.class) .setReadThrough(false) .setCacheLoaderFactory(FactoryBuilder.factoryOf(cacheLoader)); Cache<String, String> cache = cacheManager.createCache("MyCache", config); CompletionListenerFuture future = new CompletionListenerFuture(); cache.loadAll(keys, true, future);
Parent topic: Using Read-Through and Write-Through Caching
Write-through caching requires an application to implement the CacheWriter
interface. The implementation details are specific to the external resource that is being used. For details about implementing CacheWriter
methods, refer to the JCache API documentation.
The CacheWriter
interface provides methods for writing entries (write
and writeAll
) to an external resource and methods for deleting entries (delete
and deleteAll
) from an external resource. An implementation uses these methods to include the necessary logic to connect and update data on an external resource. A cache writer implementation is automatically invoked whenever the following cache operations are performed: put
, putAll
, putIfAbsent
, remove
, removeAll
, replace
, getAndPut
, getAndRemove
, getAndReplace
, invoke
, and invokeAll
.
Parent topic: Using Read-Through and Write-Through Caching
coherence-pof-config.xml
file. JCache specific POF types are defined in the coherence-jacache.jar\coherence-jcache-pof-config.xml
POF configuration file. If you are using partitioned caches together with pass-through caches, the JCache POF types must be included as part of your POF configuration file. For example:<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config coherence-pof-config.xsd"> <user-type-list> <include>coherence-pof-config.xml</include> <include>coherence-jcache-pof-config.xml</include> ...
Parent topic: Performing Basic Coherence JCache Tasks
CacheMXBean
and CacheStatisticsMXBean
JMX MBeans.This section includes the following topics:
Parent topic: Performing Basic Coherence JCache Tasks
The Coherence JCache provider implements both the CacheMXBean
and CacheStatisticsMXBean
Dynamic MBean interfaces. The interfaces provide the following management information:
CacheMXBean
– Reports configuration information for a cache. Each configuration option and its current settings are listed as attributes.
CacheStatisticsMXBean
– Reports performance information for a cache. The performance statistics are listed as attributes and are used to help troubleshoot possible issues with a cache.
Management information is not enabled by default. See Enabling Management.
Note:
Management information for pass-through caches are reported using the native Coherence JMX management implementation. See Using JMX to Manage Oracle Coherence in Managing Oracle Coherence.
Coherence JCache MBeans
Management information can be viewed using any JMX MBean-compliant browser such as the Java VisualVM console that is included with the JDK (JDK_HOME
/bin/jvisualvm
). Management MBeans for local and partitioned caches are registered to the default MBean server and are found in a JMX browser under javax.cache
.
Coherence-Java VisualVM Plug-in
JCache management information can be viewed using the Coherence-Java VisiualVM plug-in. The plug-in includes a JCache tab that aggregates the management information over time and is used to troubleshoot configuration and performance issues. See Monitor a Coherence Cluster Using the Coherence-JVisualVM Plug-in in Managing Oracle Coherence.
Coherence Reports
JCache management information can also be viewed using Coherence reports. The Coherence JCache reports aggregate management information over time and are used to troubleshoot configuration and performance issues. See Understanding the JCache Configuration Report and Understanding the JCache Statistics Report in Managing Oracle Coherence.
Parent topic: Viewing JCache Management Information
The CoherenceCacheMXBean
class implements the CacheMXBean
interface and provides configuration information for a cache. An MBean object is registered for each cache. The object name of the MBean is:
javax.cache:type=CacheConfiguration,CacheManager=coherence-jcache-cache-config.xml,Cache=
cache_name
This section includes the following topics:
Parent topic: Viewing JCache Management Information
Table 35-1describes the attributes for the CacheConfiguration
MBean.
Table 35-1 CacheConfiguration MBean Attributes
Attribute | Type | Access | Description |
---|---|---|---|
|
|
read-only |
The required key type for the cache. The default value, if no required key type is configured, is |
|
|
read-only |
Specifies whether management is enabled for the cache. The default value is |
|
|
read-only |
Specifies whether the cache operates in read-through mode. The default value is |
|
|
read-only |
Specifies whether performance statistics are being collected for the cache. The default value is |
|
|
read-only |
Specifies whether the cache uses store-by-value or store by-reference semantics. The default value is |
|
|
read-only |
The required value type for the cache. The default value, if no required value type is configured, is |
|
|
read-only |
Specifies whether the cache operates in write-through mode. The default value is |
Parent topic: Understanding the JCache CacheConfiguration MBean
The CacheConfiguration
MBean includes a clear
operation that resets all configuration management information.
Parent topic: Understanding the JCache CacheConfiguration MBean
The Coherence JCache provider includes two implementations of the JCache CacheStatisticsMXBean
interface. The ContextJCacheStatistics
implementation is used to collect performance statistics for local caches. The PartitionedJCacheStatistics
is used to collect and aggregate performance statistics for all storage members in a Coherence cluster. An MBean object is registered for each cache. The object name of the MBean is:
javax.cache:type=CacheStatistics,CacheManager=coherence-jcache-cache-config.xml,Cache=
cache_name
This section includes the following topics:
Parent topic: Viewing JCache Management Information
Table 35-2 describes the attributes for the CacheStatistics
MBean.
Table 35-2 Cache Statistics Attributes
Attribute | Type | Access | Description |
---|---|---|---|
|
|
read-only |
The average time to perform |
|
|
read-only |
The average time to perform |
|
|
read-only |
The average time to perform |
|
|
read-only |
The total number of evictions from the cache. An eviction is a initiated by the cache to free up space. An eviction is not considered a Note: This attribute is not implemented by the Coherence JCache provider. |
|
|
read-only |
The total number of |
|
|
read-only |
The percentage of cache requests that return an entry. The percentage is reported as a decimal value and is calculated using the value of cache hits divided by cache |
|
|
read-only |
The number of successful |
|
|
read-only |
The percentage of cache requests that do not return an entry. The percentage is reported as a decimal value and is calculated using the value of cache misses divided by cache |
|
|
read-only |
The number of unsuccessful |
|
|
read-only |
The total number of put operations including operations that replace and existing entry. |
|
|
read-only |
The total number of |
Parent topic: Understanding the JCache CacheStatistics MBean
The CacheStatistics
MBean includes a clear
operation that resets all cache statistics.
Parent topic: Understanding the JCache CacheStatistics MBean
The Coherence JCache provider uses a refresh interval to determine when to refresh performance statistics for partitioned caches. The refresh is performed lazily; statistics are refreshed only after the refresh interval is reached and a call to get a statistic is made. Statistics are not refreshed if a call to get a statistic is never made even if the refresh interval is reached.
The default refresh interval is 3 seconds and can be changed to accommodate different cluster sizes and network performance. For example, a cluster with many storage members may require a longer refresh interval to allow statistic aggregation to be performed across all members and to guard against constant updating.
To change the refresh interval, use the coherence.jcache.statistics.refreshtime
system property and set it to a time entered in milliseconds. The following example configures the refresh interval to 5 seconds.
-Dcoherence.jcache.statistics.refreshtime=5000
Parent topic: Viewing JCache Management Information