This chapter provides detailed instructions on how to configure caches within a cache configuration deployment descriptor. Refer to Appendix B, "Cache Configuration Elements," for a complete reference of all the elements available in the descriptor. In addition, see Chapter 18, "Cache Configurations by Example," for various sample cache configurations.
This chapter includes the following sections:
Caches are configured in a cache configuration deployment descriptor. By default, Coherence attempts to load the first coherence-cache-config.xml deployment descriptor that is found in the classpath. Coherence includes a sample coherence-cache-config.xml file in the coherence.jar. To use a different coherence-cache-config.xml file, the file must be located on the classpath and must be loaded before the coherence.jar library; otherwise, the sample cache configuration deployment descriptor is used. See "Specifying a Cache Configuration File" for alternate methods that are available for specifying a cache configuration deployment descriptor.
The cache configuration descriptor allows caches to be defined independently from the application code. At run time, applications get an instance of a cache by referring to a cache using the name that is defined in the descriptor. This allows application code to be written independent of the cache definition. Based on this approach, cache definitions can be modified without making any changes to the application code. This approach also maximizes cache definition reuse.
The schema definition of the cache configuration descriptor is the coherence-cache-config.xsd file, which imports the coherence-cache-config-base.xsd file, which, in turn, implicitly imports the coherence-config-base.xsd file. This file is located in the root of the coherence.jar file. A cache configuration deployment descriptor consists of two primary elements that are detailed in this chapter: the <caching-scheme-mapping> element and the <caching-schemes> element. These elements are used to define caches schemes and to define cache names that map to the cache schemes.
Cache mappings map a cache name to a cache scheme definition. The mappings provide a level of separation between applications and the underlying cache definitions. The separation allows cache implementations to be changed as required without having to change application code. Cache mappings can also be used to set initialization parameters that are applied to the underlying cache scheme definition.
Cache mappings are defined using a <cache-mapping> element within the <cache-scheme-mapping> node. Any number of cache mappings can be created. The cache mapping must include the cache name and the scheme name to which the cache name is mapped. See "cache-mapping" for a detailed reference of the <cache-mappings> element.
One-to-one cache mappings map a specific cache name to a cache scheme definition. An applications must provide the exact name as specified in the mapping to use a cache. Example 13-1 creates a single cache mapping that maps the cache name example to a distributed cache scheme definition with the scheme name distributed.
Example 13-1 Sample One-to-One Cache Mapping
<?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>example</cache-name>
<scheme-name>distributed</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>distributed</scheme-name>
</distributed-scheme>
</caching-schemes>
</cache-config>
Cache name pattern mappings allow applications to use patterns when specifying a cache name. Patterns use the asterisk (*) wildcard. Cache name patterns alleviate an application from having to know the exact name of a cache. Example 13-2 creates two cache mappings. The first mapping uses the wildcard (*) to map any cache name to a distributed cache scheme definition with the scheme name distributed. The second mapping maps the cache name pattern account-* to the cache scheme definition with the scheme name account-distributed.
Example 13-2 Sample Cache Name Pattern Mapping
<?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>*</cache-name>
<scheme-name>distributed</scheme-name>
</cache-mapping>
<cache-mapping>
<cache-name>account-*</cache-name>
<scheme-name>account-distributed</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>distributed</scheme-name>
</distributed-scheme>
<distributed-scheme>
<scheme-name>account-distributed</scheme-name>
</distributed-scheme>
</caching-schemes>
</cache-config>
For the first mapping, an application can use any name when creating a cache and the name is mapped to the cache scheme definition with the scheme name distributed. The second mapping requires an application to use a pattern when specifying a cache name. In this case, an application must use the prefix account- before the name. For example, an application that specifies account-overdue as the cache name uses the cache scheme definition with the scheme name account-distributed.
Cache mappings support the use of initialization parameters to override the properties of the underlying cache scheme definition. Initialization parameters are typically used to facilitate cache scheme definition reuse. In such cases, multiple cache names map to the same cache scheme definition, but each mapping overrides cache properties as required.
Initialization parameters are defined using an <init-param> element within the <init-params> node. The <init-param> element must include the <param-name> element and the <param-value> element. Any number of parameters can be specified. See "init-param" for a detailed reference of the <init-param> element.
Example 13-3 creates two cache mappings that map to the same cache scheme definition. However, the first mapping overrides the back-size-limit property on the underlying cache scheme definition; while, the second mapping uses the back-size-limit as configured in the underlying cache scheme definition.
Example 13-3 Initialization Parameters in a Cache Mapping
<?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>*</cache-name>
<scheme-name>distributed</scheme-name>
<init-params>
<init-param>
<param-name>back-size-limit</param-name>
<param-value>8MB</param-value>
</init-param>
</init-params>
</cache-mapping>
<cache-mapping>
<cache-name>account-*</cache-name>
<scheme-name>distributed</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
...
</cache-config>
See "Using Cache Scheme Properties" for more information on how cache scheme properties are configured for a cache scheme definition.
Cache schemes are used to define the caches that are available to an application. Cache schemes provide a declarative mechanism that allows caches to be defined independent of the applications that use them. This removes the responsibility of defining caches from the application and allows caches to change without having to change an application's code. Cache schemes also promote cache definition reuse by allowing many applications to use the same cache definition.
Cache schemes are defined within the <caching-schemes> element. Each cache type (distributed, replicated, and so on) has a corresponding scheme element and properties that are used to define a cache of that type. Cache schemes can also be nested to allow further customized and composite caches such as near caches. See "caching-schemes" for a detailed reference of the <caching-schemes> element.
This section describes how to define cache schemes for the most often used cache types and does not represent the full set of cache types provided by Coherence. Instructions for defining cache schemes for additional cache types are found throughout this guide and are discussed as part of the features that they support. This section includes the following topics:
The <distributed-scheme> element is used to define distributed caches. A distributed cache utilizes a distributed (partitioned) cache service instance. Any number of distributed caches can be defined in a cache configuration file. See "distributed-scheme" for a detailed reference of the <distributed-scheme> element.
Example 13-4 defines a basic distributed cache that uses distributed as the scheme name and is mapped to the cache name example. The <autostart> element is set to true to start the service on a cache server node.
Example 13-4 Sample Distributed Cache Definition
<?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>example</cache-name>
<scheme-name>distributed</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>distributed</scheme-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
</caching-schemes>
</cache-config>
In the example, the distributed cache defines a local cache to be used as the backing map. See Chapter 14, "Implementing Storage and Backing Maps" for more information on configuring backing maps.
The <replicated-scheme> element is used to define replicated caches. A replicated cache utilizes a replicated cache service instance. Any number of replicated caches can be defined in a cache configuration file. See "replicated-scheme" for a detailed reference of the <replicated-scheme> element.
Example 13-5 defines a basic replicated cache that uses replicated as the scheme name and is mapped to the cache name example. The <autostart> element is set to true to start the service on a cache server node.
Example 13-5 Sample Replicated Cache Definition
<?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>example</cache-name>
<scheme-name>replicated</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<replicated-scheme>
<scheme-name>replicated</scheme-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</replicated-scheme>
</caching-schemes>
</cache-config>
In the example, the replicated cache defines a local cache to be used as the backing map. See Chapter 14, "Implementing Storage and Backing Maps" for more information on configuring backing maps.
The <optimistic-scheme> element is used to define optimistic caches. An optimistic cache utilizes an optimistic cache service instance. Any number of optimistic caches can be defined in a cache configuration file. See "optimistic-scheme" for a detailed reference of the <optimistic-scheme> element.
Example 13-6 defines a basic optimistic cache that uses optimistic as the scheme name and is mapped to the cache name example. The <autostart> element is set to true to start the service on a cache server node.
Example 13-6 Sample Optimistic Cache Definition
<?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>example</cache-name>
<scheme-name>optimistic</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<optimistic-scheme>
<scheme-name>optimistic</scheme-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</optimistic-scheme>
</caching-schemes>
</cache-config>
In the example, the optimistic cache defines a local cache to be used as the backing map. See Chapter 14, "Implementing Storage and Backing Maps" for more information on configuring backing maps.
The <local-scheme> element is used to define local caches. Local caches are generally nested within other cache schemes, for instance as the front-tier of a near cache. Thus, this element can appear as a sub-element of any of the following elements: <caching-schemes>, <distributed-scheme>, <replicated-scheme>, <optimistic-scheme>, <near-scheme>, <overflow-scheme>, <read-write-backing-map-scheme>, and <backing-map-scheme>. See "local-scheme" for a detailed reference of the <local-scheme> element.
Example 13-7 defines a local cache that uses local as the scheme name and is mapped to the cache name example.
Note:
A local cache is not typically used as a standalone cache on a cache server; moreover, a clustering cache server distribution does not start if the only cache definition in the cache configuration file is a local cache.
Example 13-7 Sample Local Cache Definition
<?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>example</cache-name>
<scheme-name>local</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<local-scheme>
<scheme-name>local</scheme-name>
<eviction-policy>LRU</eviction-policy>
<high-units>32000</high-units>
<low-units>10</low-units>
<unit-calculator>FIXED</unit-calculator>
<expiry-delay>10ms</expiry-delay>
</local-scheme>
</caching-schemes>
</cache-config>
See "Defining a Local Cache for C++ Clients" and "Configuring a Local Cache for .NET Clients" in the Developing Remote Clients for Oracle Coherence when using Coherence*Extend.
As shown in Table 13-0, the <local-scheme> provides several optional sub-elements that control the growth of the cache. For example, the <low-units> and <high-units> sub-elements limit the cache in terms of size. When the cache reaches its maximum allowable size it prunes itself back to a specified smaller size, choosing which entries to evict according to a specified eviction-policy (<eviction-policy>). The entries and size limitations are measured in terms of units as calculated by the scheme's unit-calculator (<unit-calculator>).
Local caches use the <expiry-delay> cache configuration element to configure the amount of time that items may remain in the cache before they expire. Client threads initiate these actions while accessing the cache. Therefore, the <expiry-delay> may be reached, but not initiated until a client thread accesses the cache. For example, if the <expiry-delay> value is set at 10 seconds (10s) and a client accesses the cache after 15 seconds, then expiry occurs after 15 seconds.
Note:
The client thread performs the evictions, not a background thread. In addition, the expiry delay parameter (cExpiryMillis) is defined as an integer and is expressed in milliseconds. Therefore, the maximum amount of time can never exceed Integer.MAX_VALUE (2147483647) milliseconds or approximately 24 days.
The LocalCache class is used for size-limited caches. It is used both for caching on-heap objects (as in a local cache or the front portion of a near cache) and as the backing map for a partitioned cache. Applications can provide custom eviction policies for use with a LocalCache.
Coherence's default eviction policy is very effective for most workloads; the majority of applications do not have to provide a custom policy. Generally, it is best to restrict the use of eviction policies to scenarios where the evicted data is present in a backing system (that is, the back portion of a near cache or a database). Eviction should be treated as a physical operation (freeing memory) and not a logical operation (deleting an entity).
Example 13-8 shows the implementation of a simple custom eviction policy:
Example 13-8 Implementing a Custom Eviction Policy
package com.tangosol.examples.eviction;
import com.tangosol.net.cache.AbstractEvictionPolicy;
import com.tangosol.net.cache.ConfigurableCacheMap;
import com.tangosol.net.cache.LocalCache;
import com.tangosol.net.BackingMapManagerContext;
import com.tangosol.util.ConverterCollections;
import java.util.Iterator;
import java.util.Map;
/**
* Custom eviction policy that evicts items randomly (or more specifically,
* based on the natural order provided by the map's iterator.)
* This example may be used in cases where fast eviction is required
* with as little processing as possible.
*/
public class SimpleEvictionPolicy
extends AbstractEvictionPolicy
{
/**
* Default constructor; typically used with local caches or the front
* parts of near caches.
*/
public SimpleEvictionPolicy()
{
}
/**
* Constructor that accepts {@link BackingMapManagerContext}; should
* be used with partitioned cache backing maps.
*
* @param ctx backing map context
*/
public SimpleEvictionPolicy(BackingMapManagerContext ctx)
{
m_ctx = ctx;
}
/**
* {@inheritDoc}
*/
public void entryUpdated(ConfigurableCacheMap.Entry entry)
{
}
/**
* {@inheritDoc}
*/
public void entryTouched(ConfigurableCacheMap.Entry entry)
{
}
/**
* {@inheritDoc}
*/
public void requestEviction(int cMaximum)
{
ConfigurableCacheMap cache = getCache();
Iterator iter = cache.entrySet().iterator();
for (int i = 0, c = cache.getUnits() - cMaximum; i < c && iter.hasNext();
i++)
{
ConfigurableCacheMap.Entry entry = (ConfigurableCacheMap.Entry)
iter.next();
StringBuffer buffer = new StringBuffer();
// If the contents of the entry (for example the key/value) need
// to be examined, invoke convertEntry(entry) in case
// the entry must be deserialized
Map.Entry convertedEntry = convertEntry(entry);
buffer.append("Entry: ").append(convertedEntry);
// Here's how to get metadata about creation/last touched
// timestamps for entries. This information might be used
// in determining what gets evicted.
if (entry instanceof LocalCache.Entry)
{
buffer.append(", create millis=");
buffer.append(((LocalCache.Entry) entry).getCreatedMillis());
}
buffer.append(", last touch millis=");
buffer.append(entry.getLastTouchMillis());
// This output is for illustrative purposes; this may generate
// excessive output in a production system
System.out.println(buffer);
// iterate and remove items
// from the cache until below the maximum. Note that
// the non converted entry key is passed to the evict method
cache.evict(entry.getKey());
}
}
/**
* If a {@link BackingMapManagerContext} is configured, wrap the
* Entry with {@link ConverterCollections.ConverterEntry} in order
* to deserialize the entry.
*
* @see ConverterCollections.ConverterEntry
* @see BackingMapManagerContext
*
* @param entry entry to convert if necessary
*
* @return an entry that deserializes its key and value if necessary
*/
protected Map.Entry convertEntry(Map.Entry entry)
{
BackingMapManagerContext ctx = m_ctx;
return ctx == null ? entry :
new ConverterCollections.ConverterEntry(entry,
ctx.getKeyFromInternalConverter(),
ctx.getValueFromInternalConverter(),
ctx.getValueToInternalConverter());
}
private BackingMapManagerContext m_ctx;
}
Example 13-9 illustrates a Coherence cache configuration file (coherence-cache-config.xml) with an eviction policy:
Example 13-9 Custom Eviction Policy in a coherence-cache-config.xml 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>*</cache-name>
<scheme-name>example-near</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<near-scheme>
<scheme-name>example-near</scheme-name>
<front-scheme>
<local-scheme>
<eviction-policy>
<class-scheme>
<class-name>
com.tangosol.examples.eviction.SimpleEvictionPolicy
</class-name>
</class-scheme>
</eviction-policy>
<high-units>1000</high-units>
</local-scheme>
</front-scheme>
<back-scheme>
<distributed-scheme>
<scheme-ref>example-distributed</scheme-ref>
</distributed-scheme>
</back-scheme>
<invalidation-strategy>all</invalidation-strategy>
<autostart>true</autostart>
</near-scheme>
<distributed-scheme>
<scheme-name>example-distributed</scheme-name>
<service-name>DistributedCache</service-name>
<backing-map-scheme>
<local-scheme>
<eviction-policy>
<class-scheme>
<class-name>
com.tangosol.examples.eviction.SimpleEvictionPolicy
</class-name>
<init-params>
<!--
Passing the BackingMapManagerContext to the eviction policy;
this is required for deserializing entries
-->
<init-param>
<param-type>
com.tangosol.net.BackingMapManagerContext</param-type>
<param-value>{manager-context}</param-value>
</init-param>
</init-params>
</class-scheme>
</eviction-policy>
<high-units>20m</high-units>
<unit-calculator>binary</unit-calculator>
</local-scheme>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
</caching-schemes>
</cache-config>
The <near-scheme> element is used to define a near cache. A near cache is a composite cache because it contains two caches: the <front-scheme> element is used to define a local (front-tier) cache and the <back-scheme> element is used to define a (back-tier) cache. Typically, a local cache is used for the front-tier, however, the front-tier can also use schemes based on Java Objects (using the <class-scheme>) and non-JVM heap-based caches (using <external-scheme> or <paged-external-scheme>). The back-tier cache is described by the <back-scheme> element. A back-tier cache can be any clustered cache type and any of the standalone cache types. See "near-scheme" for a detailed reference of the <near-scheme> element.
Example 13-10 defines of a near cache that uses near as the scheme name and is mapped to the cache name example. The front-tier is a local cache and the back-tier is a distributed cache.
Note:
Near caches are used for cache clients and are not typically used on a cache server; moreover, a cache server does not start if the only cache definition in the cache configuration file is a near cache.
Example 13-10 Sample Near Cache Definition
<?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>example</cache-name>
<scheme-name>near</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<near-scheme>
<scheme-name>near</scheme-name>
<front-scheme>
<local-scheme/>
</front-scheme>
<back-scheme>
<distributed-scheme>
<scheme-name>near-distributed</scheme-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
</back-scheme>
</near-scheme>
</caching-schemes>
</cache-config>
See "Defining a Near Cache for C++ Clients" and "Defining a Near Cache for .NET Clients" in the Developing Remote Clients for Oracle Coherence when using Coherence*Extend.
The <invalidation-strategy> is an optional subelement for a near cache. An invalidation strategy is used to specify how the front-tier and back-tier objects are kept synchronous. A near cache can be configured to listen to certain events in the back cache and automatically update or invalidate entries in the front cache. Depending on the interface that the back cache implements, the near cache provides five different strategies of invalidating the front cache entries that have changed by other processes in the back cache.
Table 13-1 describes the invalidation strategies. You can find more information on the invalidation strategies and the read-through/write-through approach in Chapter 15, "Caching Data Sources."
Table 13-1 Near Cache Invalidation Strategies
| Strategy Name | Description |
|---|---|
|
|
The default strategy if no strategy is specified. This strategy is identical to the |
|
|
This strategy instructs a near cache to listen to the back cache events related only to the items currently present in the front cache. This strategy works best when each instance of a front cache contains distinct subset of data relative to the other front cache instances (for example, sticky data access patterns). |
|
|
This strategy instructs a near cache to listen to all back cache events. This strategy is optimal for read-heavy tiered access patterns where there is significant overlap between the different instances of front caches. |
|
|
This strategy instructs a near cache to listen to all backing map events that are not synthetic deletes. A synthetic delete event could be emitted as a result of eviction or expiration. With this invalidation strategy, it is possible for the front map to contain cache entries that have been synthetically removed from the backing map. Any subsequent re-insertion of the entries to the backing map causes the corresponding entries in the front map to be invalidated. |
|
|
This strategy instructs the cache not to listen for invalidation events at all. This is the best choice for raw performance and scalability when business requirements permit the use of data which might not be absolutely current. Freshness of data can be guaranteed by use of a sufficiently brief eviction policy for the front cache. |
Scheme inheritance allows cache schemes to be created by inheriting another scheme and selectively overriding the inherited scheme's properties as required. This flexibility enables cache schemes to be easily maintained and promotes cache scheme reuse. The <scheme-ref> element is used within a cache scheme definition and specifies the name of the cache scheme from which to inherit.
Example 13-11 creates two distributed cache schemes that are equivalent. The first explicitly configures a local scheme to be used for the backing map. The second definition use the <scheme-ref> element to inherit a local scheme named LocalSizeLimited:
Example 13-11 Using Cache Scheme References
<distributed-scheme>
<scheme-name>DistributedInMemoryCache</scheme-name>
<service-name>DistributedCache</service-name>
<backing-map-scheme>
<local-scheme>
<eviction-policy>LRU</eviction-policy>
<high-units>1000</high-units>
<expiry-delay>1h</expiry-delay>
</local-scheme>
</backing-map-scheme>
</distributed-scheme>
<distributed-scheme>
<scheme-name>DistributedInMemoryCache</scheme-name>
<service-name>DistributedCache</service-name>
<backing-map-scheme>
<local-scheme>
<scheme-ref>LocalSizeLimited</scheme-ref>
</local-scheme>
</backing-map-scheme>
</distributed-scheme>
<local-scheme>
<scheme-name>LocalSizeLimited</scheme-name>
<eviction-policy>LRU</eviction-policy>
<high-units>1000</high-units>
<expiry-delay>1h</expiry-delay>
</local-scheme>
In Example 13-11, the first distributed scheme definition is more compact; however, the second definition offers the ability to easily reuse the LocalSizeLimited scheme within multiple schemes. Example 13-12 demonstrates multiple schemes reusing the same LocalSizeLimited base definition and overriding the expiry-delay property.
Example 13-12 Multiple Cache Schemes Using Scheme Inheritance
<distributed-scheme>
<scheme-name>DistributedInMemoryCache</scheme-name>
<service-name>DistributedCache</service-name>
<backing-map-scheme>
<local-scheme>
<scheme-ref>LocalSizeLimited</scheme-ref>
</local-scheme>
</backing-map-scheme>
</distributed-scheme>
<replicated-scheme>
<scheme-name>ReplicatedInMemoryCache</scheme-name>
<service-name>ReplicatedCache</service-name>
<backing-map-scheme>
<local-scheme>
<scheme-ref>LocalSizeLimited</scheme-ref>
<expiry-delay>10m</expiry-delay>
</local-scheme>
</backing-map-scheme>
</replicated-scheme>
<local-scheme>
<scheme-name>LocalSizeLimited</scheme-name>
<eviction-policy>LRU</eviction-policy>
<high-units>1000</high-units>
<expiry-delay>1h</expiry-delay>
</local-scheme>
Cache scheme properties modify cache behavior as required for a particular application. Each cache scheme type contains its own set of properties that are valid for the cache. Cache properties are set within a cache scheme definition using their respective elements. See Appendix B, "Cache Configuration Elements," for a reference of all the properties that are supported for each cache scheme type.
Many cache properties use default values unless a different value is explicitly given within the cache scheme definition. The clustered caches (distributed, replicated and optimistic) use the default values as specified by their respective cache service definition. Cache services are defined in the operational deployment descriptor. While it is possible to change property values using an operational override file, cache properties are most often set within the cache scheme definition.
Example 13-13 creates a basic distributed cache scheme that sets the service thread count property and the request timeout property. In addition, the local scheme that is used for the backing map sets properties to limit the size of the local cache. Instructions for using cache scheme properties are found throughout this guide and are discussed as part of the features that they support.
Example 13-13 Setting Cache Properties
<?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>example</cache-name>
<scheme-name>DistributedInMemoryCache</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>DistributedInMemoryCache</scheme-name>
<service-name>DistributedCache</service-name>
<thread-count>4</thread-count>
<request-timeout>60s</request-timeout>
<backing-map-scheme>
<local-scheme>
<scheme-ref>LocalSizeLimited</scheme-ref>
</local-scheme>
</backing-map-scheme>
</distributed-scheme>
<local-scheme>
<scheme-name>LocalSizeLimited</scheme-name>
<eviction-policy>LRU</eviction-policy>
<high-units>1000</high-units>
<expiry-delay>1h</expiry-delay>
</local-scheme>
</caching-schemes>
</cache-config>
The cache configuration deployment descriptor supports parameter macros to minimize custom coding and enable specification of commonly used attributes when configuring class constructor parameters. The macros should be entered enclosed in curly braces as shown below, without any quotes or spaces.
Table 13-2 describes the parameter macros that may be specified:
Table 13-2 Parameter Macros for Cache Configuration
| <param-type> | <param-value> | Description |
|---|---|---|
|
|
|
Used to pass the current cache name as a constructor parameter For example:
<class-name>com.mycompany.cache.CustomCacheLoader
</class-name>
<init-params>
<init-param>
<param-type>java.lang.String</param-type>
<param-value>{cache-name}</param-value>
</init-param>
</init-params>
|
|
|
|
Used to pass the current classloader as a constructor parameter. For example:
<class-name>com.mycompany.cache.CustomCacheLoader
</class-name>
<init-params>
<init-param>
<param-type>java.lang.ClassLoader</param-type>
<param-value>{class-loader}</param-value>
</init-param>
</init-params>
|
|
|
|
Used to pass the current
<class-name>com.mycompany.cache.CustomCacheLoader
</class-name>
<init-params>
<init-param>
<param-type>
com.tangosol.net.BackingMapManagerContext
</param-type>
<param-value>{manager-context}</param-value>
</init-param>
</init-params>
|
|
|
|
Instantiates an object defined by the <class-scheme> <scheme-name>dbconnection</scheme-name> <class-name>com.mycompany.dbConnection</class-name> <init-params> <init-param> <param-name>driver</param-name> <param-type>String</param-type> <param-value>org.gjt.mm.mysql.Driver </param-value> </init-param> <init-param> <param-name>url</param-name> <param-type>String</param-type> <param-value> jdbc:mysql://dbserver:3306/companydb </param-value> </init-param> <init-param> <param-name>user</param-name> <param-type>String</param-type> <param-value>default</param-value> </init-param> <init-param> <param-name>password</param-name> <param-type>String</param-type> <param-value>default</param-value> </init-param> </init-params> </class-scheme> ... <class-name>com.mycompany.cache.CustomCacheLoader </class-name> <init-params> <init-param> <param-type>{scheme-ref}</param-type> <param-value>dbconnection</param-value> </init-param> </init-params> |
|
|
cache name |
Used to obtain a
<cache-config>
<caching-scheme-mapping>
<cache-mapping>
<cache-name>boston-*</cache-name>
<scheme-name>wrapper</scheme-name>
<init-params>
<init-param>
<param-name>delegate-cache-name</param-name>
<param-value>london-*</param-value>
</init-param>
</init-params>
</cache-mapping>
<cache-mapping>
<cache-name>london-*</cache-name>
<scheme-name>partitioned</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<class-scheme>
<scheme-name>wrapper</scheme-name>
<class-name>
com.tangosol.net.cache.WrapperNamedCache
</class-name>
<init-params>
<init-param>
<param-type>{cache-ref}</param-type>
<param-value>{delegate-cache-name}
</param-value>
</init-param>
<init-param>
<param-type>string</param-type>
<param-value>{cache-name}</param-value>
</init-param>
</init-params>
</class-scheme>
<distributed-scheme>
<scheme-name>partitioned</scheme-name>
<service-name>partitioned</service-name>
<backing-map-scheme>
<local-scheme>
<unit-calculator>BINARY</unit-calculator>
</local-scheme>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
</caching-schemes>
</cache-config>
The |