This chapter includes the following sections:
The META-INF/services/javax.cache.spi.CachingProvider service definition that is located in the coherence-jcache.jar library assures that applications using the javax.cache.Caching bootstrap class use the Coherence JCache provider by default. 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();
The Coherence JCache provider supports four cache types: local, partitioned, pass-through, and remote. A local cache is a cache that is local to the application process. A partitioned cache distributes cached data across Coherence storage-enabled cluster members. A pass-through cache delegates to any native Coherence cache that is configured within a Coherence cache configuration file. A remote cache is a cache that allows Coherence extend clients to access a cache using the proxy service. This section demonstrates how to create each of these cache types using the JCache API.
This section includes the following topics:
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.
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. For details about the operational override file, 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
Note:
For details on using an existing Coherence cache configuration file, see "Using Native Coherence Functionality from JCache".
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. For details about the operational override file, 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.
For details about the cache configuration file, see "Specifying a Cache Configuration File".
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. For details on Coherence*Extend, see 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. For details about the operational override file, 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
Note:
For details on using an existing Coherence cache configuration file, see "Using Native Coherence Functionality from JCache".
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:
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();
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.
Coherence JCache-based caches are configured programmatically using the 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:
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.
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);
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. For details, see "Configuring a JCache POF Configuration file".
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. For details on using read-through and write-through caching, see "Using Read-Through and Write-Through Caching".
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. For details about JCache management, 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);
JCache includes many operations for interacting with a cache. The operations are defined in the 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. For details on performing 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.
JCache supports the use of read-through and write-through caching to integrate caches with external resources. Read-through caching automatically loads entries from external resources and write-through caching automatically writes entries to external resources. Read-through and write-through caching require an application to implement the JCache 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.
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. For details about using entry processors, see "Processing JCache Entries".
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);
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.
The Coherence JCache provider uses POF for serialization and requires the 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>
...
For details on using POF configuration files, see "Specifying a POF Configuration File".
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" for details about enabling management.
Note:
Management information for pass-through caches are reported using the native Coherence JMX management implementation. For details about enabling native Coherence management, see 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. For details on the Coherence reports for JCache, see 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. For details on the Coherence reports for JCache, see Managing Oracle Coherence.
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
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 |
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
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 |
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