acceptor-config

Used in: proxy-scheme.

Description

The acceptor-config element specifies the configuration info for a protocol-specific connection acceptor used by a proxy service to enable Coherence*Extend clients to connect to the cluster and use the services offered by the cluster without having to join the cluster.

The acceptor-config element must contain exactly one protocol-specific connection acceptor configuration element (either jms-acceptor or tcp-acceptor).

Elements

The following table describes the elements you can define within the acceptor-config element.

<use-filters>
    <filter-name>gzip</filter-name>
</use-filters>

<serializer>
  <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
  <init-params>
    <init-param>
      <param-type>string</param-type>
      <param-value>my-pof-types.xml</param-value>
    </init-param>
  </init-params>
</serializer>

async-store-manager

Used in: external-scheme, paged-external-scheme.

Description

The async-store-manager element adds asynchronous write capabilities to other store manager implementations.

Supported store managers include:

• custom-store-manager - allows definition of custom implementations of store managers
• bdb-store-manager - uses Berkeley Database JE to implement an on-disk cache
• lh-file-manager - uses a Coherence LH on-disk database cache
• nio-file-manager - uses NIO to implement memory-mapped file based cache
• nio-memory-manager - uses NIO to implement an off JVM heap, in-memory cache

Implementation

This store manager is implemented by the com.tangosol.io.AsyncBinaryStoreManager class.

Elements

The following table describes the elements you can define within the async-store-manager element.

[\d]+[[.][\d]+]?[K|k|M|m]?[B|b]?

backup-storage

Used in: distributed-scheme.

Description

The backup-storage element specifies the type and configuration of backup storage for a partitioned cache.

Elements

The following table describes the elements you can define within the backup-storage element.

[\d]+[[.][\d]]?[K|k|M|m|G|g|T|t]?[B|b]?

[\d]+[[.][\d]]?[K|k|M|m|G|g|T|t]?[B|b]?

bdb-store-manager

Used in: external-scheme, paged-external-scheme, async-store-manager.

Berkeley Database JE Java class libraries are required to utilize a bdb-store-manager, visit the Berkeley Database JE product page for additional information.

Description

The BDB store manager is used to define external caches which will use Berkeley Database JE on-disk embedded databases for storage. See the persistent disk cache and overflow cache samples for examples of Berkeley based store configurations.

Implementation

This store manager is implemented by the com.tangosol.io.bdb.BerkeleyDBBinaryStoreManager class, and produces BinaryStore objects implemened by the com.tangosol.io.bdb.BerkeleyDBBinaryStore class.

Elements

The following table describes the elements you can define within the bdb-store-manager element.

cache-config

Description

The cache-config element is the root element of the cache configuration descriptor.

At a high level a cache configuration consists of cache schemes and cache scheme mappings. Cache schemes describe a type of cache, for instance a database backed, distributed cache. Cache mappings define what scheme to use for a given cache name.

Elements

The following table describes the elements you can define within the cache-config element.

acceptor-config

Used in: proxy-scheme.

Description

The acceptor-config element specifies the configuration info for a protocol-specific connection acceptor used by a proxy service to enable Coherence*Extend clients to connect to the cluster and use the services offered by the cluster without having to join the cluster.

The acceptor-config element must contain exactly one protocol-specific connection acceptor configuration element (either jms-acceptor or tcp-acceptor).

Elements

The following table describes the elements you can define within the acceptor-config element.

<use-filters>
    <filter-name>gzip</filter-name>
</use-filters>

<serializer>
  <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
  <init-params>
    <init-param>
      <param-type>string</param-type>
      <param-value>my-pof-types.xml</param-value>
    </init-param>
  </init-params>
</serializer>

async-store-manager

Used in: external-scheme, paged-external-scheme.

Description

The async-store-manager element adds asynchronous write capabilities to other store manager implementations.

Supported store managers include:

• custom-store-manager - allows definition of custom implementations of store managers
• bdb-store-manager - uses Berkeley Database JE to implement an on-disk cache
• lh-file-manager - uses a Coherence LH on-disk database cache
• nio-file-manager - uses NIO to implement memory-mapped file based cache
• nio-memory-manager - uses NIO to implement an off JVM heap, in-memory cache

Implementation

This store manager is implemented by the com.tangosol.io.AsyncBinaryStoreManager class.

Elements

The following table describes the elements you can define within the async-store-manager element.

[\d]+[[.][\d]+]?[K|k|M|m]?[B|b]?

backup-storage

Used in: distributed-scheme.

Description

The backup-storage element specifies the type and configuration of backup storage for a partitioned cache.

Elements

The following table describes the elements you can define within the backup-storage element.

[\d]+[[.][\d]]?[K|k|M|m|G|g|T|t]?[B|b]?

[\d]+[[.][\d]]?[K|k|M|m|G|g|T|t]?[B|b]?

bdb-store-manager

Used in: external-scheme, paged-external-scheme, async-store-manager.

Berkeley Database JE Java class libraries are required to utilize a bdb-store-manager, visit the Berkeley Database JE product page for additional information.

Description

The BDB store manager is used to define external caches which will use Berkeley Database JE on-disk embedded databases for storage. See the persistent disk cache and overflow cache samples for examples of Berkeley based store configurations.

Implementation

This store manager is implemented by the com.tangosol.io.bdb.BerkeleyDBBinaryStoreManager class, and produces BinaryStore objects implemened by the com.tangosol.io.bdb.BerkeleyDBBinaryStore class.

Elements

The following table describes the elements you can define within the bdb-store-manager element.

cache-config

Description

The cache-config element is the root element of the cache configuration descriptor.

At a high level a cache configuration consists of cache schemes and cache scheme mappings. Cache schemes describe a type of cache, for instance a database backed, distributed cache. Cache mappings define what scheme to use for a given cache name.

Elements

The following table describes the elements you can define within the cache-config element.

cache-mapping

Used in: caching-scheme-mapping

Description

Each cache-mapping element specifyies the cache-scheme which is to be used for a given cache name or pattern.

Elements

The following table describes the elements you can define within the cache-mapping element.

<cache-mapping>
  <cache-name>My*</cache-name>
  <scheme-name>my-scheme</scheme-name>
  <init-params>
    <init-param>
      <param-name>cache-loader</param-name>
      <param-value>com.acme.MyCacheLoader</param-value>
    </init-param>
    <init-param>
      <param-name>size-limit</param-name>
      <param-value>1000</param-value>
    </init-param>
  </init-params>
</cache-mapping>

cache-service-proxy

Used in: proxy-config

Description

The cache-service-proxy element contains the configuration info for a clustered cache service proxy managed by a proxy service.

Elements

The following table describes the elements you can define within the cache-service-proxy element.

caching-scheme-mapping

Used in: cache-config

Description

Defines mappings between cache names, or name patterns, and caching-schemes. For instance you may define that caches whose names start with "accounts-" will use a distributed caching scheme, while caches starting with the name "rates-" will use a replicated caching scheme.

Elements

The following table describes the elements you can define within the caching-scheme-mapping element.

caching-schemes

Used in: cache-config

Description

The caching-schemes element defines a series of cache scheme elements. Each cache scheme defines a type of cache, for instance a database backed partitioned cache, or a local cache with an LRU eviction policy. Scheme types are bound to actual caches using cache-scheme-mappings.

Scheme Types and Names

Each of the cache scheme element types is used to describe a different type of cache, for instance distributed, versus replicated. Multiple instances of the same type may be defined so long as each has a unique scheme-name.

For example the following defines two different distributed schemes:

<distributed-scheme>
  <scheme-name>DistributedInMemoryCache</scheme-name>
  <service-name>DistributedCache</service-name>
  <backing-map-scheme>
    <local-scheme/>
  </backing-map-scheme>
</distributed-scheme>

<distributed-scheme>
  <scheme-name>DistributedOnDiskCache</scheme-name>
  <service-name>DistributedCache</service-name>
  <backing-map-scheme>
    <external-scheme>
      <nio-file-manager>
        <initial-size>8MB</initial-size>
        <maximum-size>512MB</maximum-size>
        <directory></directory>
      </nio-file-manager>
    </external-scheme>
  </backing-map-scheme>
</distributed-scheme>

Nested Schemes

Some caching scheme types contain nested scheme definitions. For instance in the above example the distributed schemes include a nested scheme defintion describing their backing map.

Scheme Inheritance

Caching schemes can be defined by specifying all the elements required for a given scheme type, or by inheriting from another named scheme of the same type, and selectively overriding specific values. Scheme inheritance is accomplished by including a <scheme-ref> element in the inheriting scheme containing the scheme-name of the scheme to inherit from.

For example:

The following two configurations will produce equivalent "DistributedInMemoryCache" scheme defintions:

<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>

Please note that while the first is somewhat more compact, the second offers the ability to easily resuse the "LocalSizeLimited" scheme within multiple schemes. The following example demonstrates multiple schemes reusing the same "LocalSizeLimited" base defintion, but the second imposes a diffrent expiry-delay.

<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>

Elements

The following table describes the different types of schemes you can define within the caching-schemes element.

class-scheme

Used in: caching-schemes, local-scheme, distributed-scheme, replicated-scheme, optimistic-scheme, near-scheme, versioned-near-scheme, overflow-scheme, read-write-backing-map-scheme, versioned-backing-map-scheme, cachestore-scheme, listener

Description

Class schemes provide a mechanism for instantiating an arbitrary Java object for use by other schemes. The scheme which contains this element will dictate what class or interface(s) must be extended. See the database cache sample for an example of using a class-scheme.

The class-scheme may be configured to either instantiate objects directly via their class-name, or indirectly via a class-factory-name and method-name. The class-scheme must be configured with either a class-name or class-factory-name and method-name.

Elements

The following table describes the elements you can define within the class-scheme element.

cachestore-scheme

Used in: local-scheme, read-write-backing-map-scheme, versioned-backing-map-scheme.

Description

Cache store schemes define a mechanism for connecting a cache to a backend data store. The cache store scheme may use any class implementing either the com.tangosol.net.cache.CacheStore or com.tangosol.net.cache.CacheLoader interfaces, where the former offers read-write capabilities, where the latter is read-only. Custom implementations of these interfaces may be produced to connect Coherence to various data stores. See the database cache sample for an example of using a cachestore-scheme.

Elements

The following table describes the elements you can define within the cachestore-scheme element.

custom-store-manager

Used in: external-scheme, paged-external-scheme, async-store-manager.

Description

Used to create and configure custom implementations of a store manager for use in external caches.

Elements

The following table describes the elements you can define within the custom-store-manager element.

disk-scheme

As of Coherence 3.0, the disk-scheme configuration element has been deprecated and replaced with by the external-scheme and paged-external-scheme configuration elements.

distributed-scheme

Used in: caching-schemes, near-scheme, versioned-near-scheme, overflow-scheme, versioned-backing-map-scheme

Description

The distributed-scheme defines caches where the storage for entries is partitioned across cluster nodes. See the service overview for a more detailed description of partitioned caches. See the partitioned cache samples for examples of various distributed-scheme configurations.

Clustered Concurrency Control

Partitioned caches support cluster wide key-based locking so that data can be modified in a cluster without encountering the classic missing update problem. Note that any operation made without holding an explicit lock is still atomic but there is no guarantee that the value stored in the cache does not change between atomic operations.

Cache Clients

The partitioned cache service supports the concept of cluster nodes which do not contribute to the overall storage of the cluster. Nodes which are not storage enabled are considered "cache clients".

Cache Partitions

The cache entries are evenly segmented into a number of logical partitions, and each storage enabled cluster node running the specified partitioned service will be responsible for maintain a fair-share of these partitions.

Key Association

By default the specific set of entries assigned to each partition is transparent to the application. In some cases it may be advantageous to keep certain related entries within the same cluster node. A key-associator may be used to indicate related entries, the partitioned cache service will ensure that associated entries reside on the same partition, and thus on the same cluster node. Alternatively, key association may be specified from within the application code by using keys which implement the com.tangosol.net.cache.KeyAssociation interface.

Cache Storage (Backing Map)

Storage for the cache is specified via the backing-map-scheme. For instance a partitioned cache which uses a local cache for its backing map will result in cache entries being stored in-memory on the storage enabled cluster nodes.

Failover

For the purposes of failover a configurable number of backups of the cache may be maintained in backup-storage across the cluster nodes. Each backup is also divided into partitions, and when possible a backup partition will not reside on the same physical machine as the primary partition. If a cluster node abruptly leaves the cluster, responsibility for its partitions will automatically be reassigned to the existing backups, and new backups of those partitions will be created (on remote nodes) in order to maintain the configured backup count.

Partition Redistribution

When a node joins or leaves the cluster, a background redistribution of partitions occurs to ensure that all cluster nodes manage a fair-share of the total number of partitions. The amount of bandwidth consumed by the background transfer of partitions is governed by the transfer-threshold.

Elements

The following table describes the elements you can define within the distributed-scheme element.

Element	Required/Optional	Description
<scheme-name>	Optional	Specifies the scheme's name. The name must be unique within a configuration file.
<scheme-ref>	Optional	Specifies the name of another scheme to inherit from.
<service-name>	Optional	Specifies the name of the service which will manage caches created from this scheme. services are configured from within the operational descriptor.
<listener>	Optional	Specifies an implementation of a com.tangosol.MapListener which will be notified of events occurring on the cache.
<backing-map-scheme>	Optional	Specifies what type of cache will be used within the cache server to store the entries. Legal values are: local-scheme external-scheme paged-external-scheme class-scheme overflow-scheme read-write-backing-map-scheme versioned-backing-map-scheme When using an overflow-based backing map it is important that the corresponding backup-storage be configured for overflow (potentially using the same scheme as the backing-map). See the partitioned cache with overflow sample for an example configuration.
<partition-count>	Optional	Specifies the number of partitions that a partitioned cache will be "chopped up" into. Each node running the partitioned cache service that has the local-storage option set to true will manage a "fair" (balanced) number of partitions. The number of partitions should be larger than the square of the number of cluster members to achieve a good balance, and it is suggested that the number be prime. Good defaults include 257 and 1021 and prime numbers in-between, depending on the expected cluster size. For large clusters it is recommended that the partition count not exceeded 16,381, regardless of the number of storage enabled members. A list of first 1,000 primes can be found at http://www.utm.edu/research/primes/lists/small/1000.txt Legal values are prime numbers. Default value is the value specified in the tangosol-coherence.xml descriptor.
<key-associator>	Optional	Specifies a class that will be responsible for providing associations between keys and allowing associated keys to reside on the same partition. This implementation must have a zero-parameter public constructor.
<key-partitioning>	Optional	Specifies a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface, which will be responsible for assigning keys to partitions. This implementation must have a zero-parameter public constructor. If unspecified, the default key partitioning algorithm will be used, which ensures that keys are evenly segmented across partitions.
<partition-listener>	Optional	Specifies a class that implements the com.tangosol.net.partition.PartitionListener interface.
<backup-count>	Optional	Specifies the number of members of the partitioned cache service that hold the backup data for each unit of storage in the cache. Value of 0 means that in the case of abnormal termination, some portion of the data in the cache will be lost. Value of N means that if up to N cluster nodes terminate at once, the cache data will be preserved. To maintain the partitioned cache of size M, the total memory usage in the cluster does not depend on the number of cluster nodes and will be in the order of M*(N+1). Recommended values are 0, 1 or 2. Default value is the value specified in the tangosol-coherence.xml descriptor.
<backup-storage>	Optional	Specifies the type and configuration for the partitioned cache backup storage.
<thread-count>	Optional	Specifies the number of daemon threads used by the partitioned cache service. If zero, all relevant tasks are performed on the service thread. Legal values are positive integers or zero. Default value is the value specified in the tangosol-coherence.xml descriptor.
<lease-granularity>	Optional	Specifies the lease ownership granularity. Available since release 2.3. Legal values are: thread member A value of thread means that locks are held by a thread that obtained them and can only be released by that thread. A value of member means that locks are held by a cluster node and any thread running on the cluster node that obtained the lock can release it. Default value is the value specified in the tangosol-coherence.xml descriptor.
<transfer-threshold>	Optional	Specifies the threshold for the primary buckets distribution in kilo-bytes. When a new node joins the partitioned cache service or when a member of the service leaves, the remaining nodes perform a task of bucket ownership re-distribution. During this process, the existing data gets re-balanced along with the ownership information. This parameter indicates a preferred message size for data transfer communications. Setting this value lower will make the distribution process take longer, but will reduce network bandwidth utilization during this activity. Legal values are integers greater then zero. Default value is the value specified in the tangosol-coherence.xml descriptor.
<local-storage>	Optional	Specifies whether or not a cluster node will contribute storage to the cluster, i.e. maintain partitions. When disabled the node is considered a cache client. Normally this value should be left unspecified within the configuration file, and instead set on a per-process basis using the tangosol.coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptor. Legal values are true or false. Default value is the value specified in the tangosol-coherence.xml descriptor.
<autostart>	Optional	The autostart element is intended to be used by cache servers (i.e. com.tangosol.net.DefaultCacheServer). It specifies whether or not the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. Default value is false.
<task-hung-threshold>	Optional	Specifies the amount of time in milliseconds that a task can execute before it is considered "hung". Note: a posted task that has not yet started is never considered as hung. This attribute is applied only if the Thread pool is used (the "thread-count" value is positive). Legal values are positive integers or zero (indicating no default timeout). Default value is the value specified in the tangosol-coherence.xml descriptor.
<task-timeout>	Optional	Specifies the timeout value in milliseconds for requests executing on the service worker threads. This attribute is applied only if the thread pool is used (the "thread-count" value is positive). Legal values are positive integers or zero (indicating no default timeout). Default value is the value specified in the tangosol-coherence.xml descriptor.
<request-timeout>	Optional	Specifies the maximum amount of time a client will wait for a response before abandoning the original request. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes the following: (1) the time it takes to deliver the request to an executing node (server); (2) the interval between the time the task is received and placed into a service queue until the execution starts; (3) the task execution time; (4) the time it takes to deliver a result back to the client. Legal values are positive integers or zero (indicating no default timeout). Default value is the value specified in the tangosol-coherence.xml descriptor.
<operation-bundling>	Optional	Specifies the configuration info for a bundling strategy.

external-scheme

Used in: caching-schemes, distributed-scheme, replicated-scheme, optimistic-scheme, near-scheme, versioned-near-scheme, overflow-scheme, read-write-backing-map-scheme, versioned-backing-map-scheme

Description

External schemes define caches which are not JVM heap based, allowing for greater storage capacity. See the local cache samples for examples of various external cache configurations.

Implementaion

This scheme is implemented by:

• com.tangosol.net.cache.SerializationMap - for unlimited size caches
• com.tangosol.net.cache.SerializationCache - for size limited caches

The implementation type is chosen based on the following rule:

• if the high-units element is specified and not zero then SerializationCache is used;
• otherwise SerializationMap is used.

Pluggable Storage Manager

External schemes use a pluggable store manager to store and retrieve binary key value pairs. Supported store managers include:

• async-store-manager - a wrapper providing asynchronous write capabilities for of other store manager implementations
• custom-store-manager - allows definition of custom implementations of store managers
• bdb-store-manager - uses Berkeley Database JE to implement an on-disk cache
• lh-file-manager - uses a Coherence LH on-disk database cache
• nio-file-manager - uses NIO to implement memory-mapped file based cache
• nio-memory-manager - uses NIO to implement an off JVM heap, in-memory cache

Size Limited Cache

The cache may be configured as size-limited, which means that once it reaches its maximum allowable size it prunes itself.

Eviction against disk based caches can be expensive, consider using a paged-external-scheme for such cases.

Entry Expiration

External schemes support automatic expiration of entries based on the age of the value, as configured by the expiry-delay.

Persistence (long-term storage)

External caches are generally used for temporary storage of large data sets, for example as the back-tier of an overflow-scheme. Certain implementations do however support persistence for non-clustered caches, see the bdb-store-manager and lh-file-manager for details. Clustered persistence should be configured via a read-write-backing-map-scheme on a distributed-scheme.

Elements

The following table describes the elements you can define within the external-scheme element.