B.1 Cache Configuration Deployment Descriptor

The cache configuration deployment descriptor specifies the various types of caches that can be used within a cluster. The name and location of the descriptor is specified in the operational deployment descriptor and defaults to coherence-cache-config.xml. A sample configuration descriptor is packaged in the root of the coherence.jar library and is used unless a custom coherence-cache-config.xml file is found before the coherence.jar file within the application's classpath. All cluster members should use identical cache configuration descriptors if possible.

The cache configuration deployment descriptor schema is defined in the coherence-cache-config.xsd file, which imports the coherence-cache-config-base.xsd file, which, in turn, imports the coherence-config-base.xsd file. These XSD files are located in the root of the coherence.jar library and at the following Web URL:

The <cache-config> element is the root element of the cache configuration descriptor and typically includes an XSD and Coherence namespace reference and the location of the coherence-cache-config.xsd file. For example:

The schema located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.

The xsi:schemaLocation attribute can be omitted to disable schema validation.

When deploying Coherence into environments where the default character set is EBCDIC rather than ASCII, ensure that the deployment descriptor file is in ASCII format and is deployed into its run-time environment in the binary format.

acceptor-config

The acceptor-config element specifies the configuration information for a TCP/IP or HTTP (for REST) connection acceptor. The connection acceptor is used by a proxy service to enable Coherence*Extend clients to connect to the cluster and use cluster services without having to join the cluster.

Specifies the configuration information for a connection acceptor that enables Coherence*Extend clients to connect to the cluster over TCP/IP. This element cannot be used together with the <http-acceptor> element.

Specifies the class configuration information for a com.tangosol.io.Serializer implementation used by the connection acceptor to serialize and deserialize user types. For example, the following configures a ConfigurablePofContext that uses the my-pof-types.xml POF type configuration file to deserialize user types to and from a POF stream:

Specifies initialization parameters which are accessible by implementations which support the com.tangosol.run.xml.XmlConfigurable interface, or which include a public constructor with a matching signature. Initialization parameters can be specified for both the <class-name> element and the <class-factory-name> element.

Table B-4 describes the subelements of the async-store-manager element.

Table B-4 async-store-manager Subelements

Element

Required/
Optional

Description

<class-name>

Optional

Specifies a custom implementation of the async-store-manager. Any custom implementation must extend the com.tangosol.io.AsyncBinaryStoreManager class and declare the exact same set of public constructors.

Configures the external cache to use an off JVM heap, memory region for cache storage.

<async-limit>

Optional

Specifies the maximum number of bytes that are queued to be written asynchronously. Setting the value to zero does not disable the asynchronous writes; instead, it indicates that the implementation default for the maximum number of bytes are necessaries value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K (kilo, 210)

M (mega, 220)

If the value does not contain a factor, a factor of one is assumed. Valid values are any positive memory sizes and zero. The default value is 4MB.

authorized-hosts

This element contains the collection of IP addresses of TCP/IP initiator hosts that are allowed to connect to the cluster using a TCP/IP acceptor. If this collection is empty no constraints are imposed. Any number of host-address and host-range elements may be specified.

Specifies an IP address or host name. If any are specified, only hosts with specified host-addresses or within the specified host-ranges are allowed to join the cluster. The content override attributes id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.

<host-range>

Optional

Specifies a range of IP addresses. If any are specified, only hosts with specified host-addresses or within the specified host-ranges are allowed to join the cluster.

<host-filter>

Optional

Specifies class configuration information for a com.tangosol.util.Filter implementation that is used by a TCP/IP acceptor to determine whether to accept a particular TCP/IP initiator. The evaluate() method is passed to the java.net.InetAddress of the client. Implementations should return true to allow the client to connect. Classes are specified using the <class-name> subelement. Any initialization parameters can be defined within an <init-params> subelement.

The content override attributes xml-override and id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document. See "Attribute Reference".

backing-map-scheme

Specifies what type of cache is used within the cache server to store the entries.

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 "Partitioned Cache with Overflow" for an example configuration.

Note:

The partitioned subelement is used if and only if the parent element is the distributed-scheme.

Elements

Table B-7 describes the subelements of the backing-map-scheme element.

Table B-7 backing-map-scheme Subelements

Element

Required/
Optional

Description

<partitioned>

Optional

Specifies whether the enclosed backing map is a PartitionAwareBackingMap. (This element is respected only within a distributed-scheme.) If set to true, the scheme that is specified as the backing map is used to configure backing maps for each individual partition of the PartitionAwareBackingMap; otherwise, it is used for the entire backing map itself.The concrete implementations of the PartitionAwareBackingMap interface are:

custom—The corresponding implementations class is the class specified by the class-name element.

scheme—The corresponding implementations class is specified as a caching-scheme by the scheme-name element.

The default value is the value specified in the tangosol-coherence.xml descriptor. For more information, see the <backup-storage/type> parameter in "DistributedCache Service Parameters".

<initial-size>

Optional

Only applicable with the off-heap and file-mapped types.Specifies the initial buffer size in bytes.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is the backup-storage/initial-size value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<maximum-size>

Optional

Only applicable with the off-heap and file-mapped types. Specifies the initial buffer size in bytes.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is the backup-storage/maximum-size value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<directory>

Optional

Only applicable with the file-mapped type. Specifies the path name for the directory that the disk persistence manager (com.tangosol.util.nio.MappedBufferManager) uses as "root" to store files in. If not specified or specifies a non-existent directory, a temporary file in the default location is used. The default value is the backup-storage/directory value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<class-name>

Optional

Only applicable with the custom type. Specifies a class name for the custom storage implementation. If the class implements com.tangosol.run.xml.XmlConfigurable interface then upon construction, the setConfig method is called passing the entire backup-storage element. The default value is the backup-storage/class-name value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<scheme-name>

Optional

Only applicable with the scheme type. Specifies a scheme name for the ConfigurableCacheFactory. The default value is the backup-storage/scheme-name value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

Specifies the path name to the root directory where the Berkeley Database JE store manager stores files. If not specified or specified with a non-existent directory, a temporary directory in the default location is used.

<store-name>

Optional

Specifies the name for a database table that the Berkeley Database JE store manager uses to store data in. Specifying this parameter causes the bdb-store-manager to use non-temporary (persistent) database instances. This is intended only for local caches that are backed by a cache loader from a non-temporary store, so that the local cache can be pre-populated from the disk on startup. This setting should not be enabled with replicated or distributed caches. Normally, the <store-name> element should be left unspecified, indicating that temporary storage is to be used.

When specifying this property, it is recommended to use the {cache-name} macro. See "Using Parameter Macros" for more information on the {cache-name} macro.

Specifies the operation name for which calls performed concurrently on multiple threads are "bundled" into a functionally analogous "bulk" operation that takes a collection of arguments instead of a single one.

Valid values depend on the bundle configuration context. For the <cachestore-scheme> the valid operations are:

Specifies the maximum amount of time in milliseconds that individual execution requests are allowed to be deferred for a purpose of "bundling" them and passing into a corresponding bulk operation. If the preferred-size threshold is reached before the specified delay, the bundle is processed immediately.

Valid values are positive numbers. The default value is 1.

<thread-threshold>

Optional

Specifies the minimum number of threads that must be concurrently executing individual (non-bundled) requests for the bundler to switch from a pass-through to a bundling mode.

Valid values are positive numbers. The default value is 4.

<auto-adjust>

Optional

Specifies whether the auto adjustment of the preferred-size value (based on the run-time statistics) is allowed.

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.

Specifies the scope name for this configuration. The scope name is typically used (as a prefix) for all services generated by a cache factory to isolate services indicated in this cache configuration from services created by cache factories with other configurations, thus avoiding unintended joining of services with similar names from different configurations.

Specifies a cache name or name pattern. The name is unique within a cache factory.The following cache name patterns are supported:

exact match, for example, MyCache

prefix match, for example, My* that matches to any cache name starting with My

any match "*", that matches to any cache name

The patterns get matched in the order of specificity (more specific definition is selected whenever possible). For example, if both MyCache and My* mappings are specified, the scheme from the MyCache mapping is used to configure a cache named MyCache.

<scheme-name>

Required

Contains the caching scheme name. The name is unique within a configuration file. Caching schemes are configured in the caching-schemes element.

For any cache name match My*, any occurrence of the literal cache-loader in any part of the corresponding cache-scheme element is replaced with the string com.acme.MyCacheLoader and any occurrence of the literal size-limit is replaced with the value of 1000.

cache-service-proxy

The cache-service-proxy element contains the configuration information for a cache service proxy that is managed by a proxy service.

Elements

Table B-13 describes the subelements of the cache-service-proxy element.

Table B-13 cache-service-proxy Subelements

Element

Required/
Optional

Description

<class-name>

Optional

Specifies the fully qualified name of a class that implements the com.tangosol.net.CacheService interface. The class acts as an interceptor between a client and a proxied cache service to implement custom processing as required. For example, the class could be used to perform authorization checks before allowing the use of the proxied cache service.

cachestore-scheme

Cache store schemes define a mechanism for connecting a cache to a back-end 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 "Cache of a Database" for an example of using a cachestore-scheme.

Elements

Table B-14 describes the subelements of the cachestore-scheme element.

Table B-14 cachestore-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

caching-scheme-mapping

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

Elements

Table B-15 describes the subelement you can define within the caching-scheme-mapping element.

caching-schemes

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 mappings (see caching-scheme-mapping).

Elements

Table B-16 describes the different types of schemes you can define within the caching-schemes element.

Defines a cache scheme using a custom cache implementation. Any custom implementation must implement the java.util.Map interface, and include a zero-parameter public constructor. Additionally if the contents of the Map can be modified by anything other than the CacheService itself (for example, if the Map automatically expires its entries periodically or size-limits its contents), then the returned object must implement the com.tangosol.util.ObservableMap interface.

Class schemes provide a mechanism for instantiating an arbitrary Java object for use by other schemes. The scheme which contains this element dictates what class or interface(s) must be extended. See "Cache of a Database" for an example of using a class-scheme.

The class-scheme may be configured to either instantiate objects directly by using their class-name, or indirectly by using 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.

Contains a fully specified Java class name to instantiate. This class must extend an appropriate implementation class as dictated by the containing scheme and must declare the exact same set of public constructors as the superclass.

This element cannot be used with the <class-factory-name> element.

<class-factory-name>

Optional

Specifies a fully specified name of a Java class that is used as a factory for object instantiation.

This element cannot be used with the <class-name> element and is used with the <method-name> element.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which performs object instantiation.

Specifies initialization parameters which are accessible by implementations which support the com.tangosol.run.xml.XmlConfigurable interface, or which include a public constructor with a matching signature.

defaults

The defaults element defines factory wide default settings. This feature enables global configuration of serializers and socket providers used by all services which have not explicitly defined these settings.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation, or it references a serializer class configuration that is defined within the <serializers> element in the operational configuration file. Two pre-defined serializers are available: java (default) and pof and are referred to using their defined id attribute name. For example:

Specifies either: the class configuration information for a com.tangosol.net.SocketProvider implementation, or it references a socket provider configuration that is defined within the <socket-providers> element of the operational deployment descriptor. Two pre-defined socket providers are available: system (default) and ssl and are referred to using their defined id attribute name. For example:

<socket-provider>ssl</socket-provider>

This setting only specifies the socket provider for Coherence*Extend services. The TCMP socket provider is specified within the <unicast-listener> element in the operational configuration.

distributed-scheme

The distributed-scheme defines caches where the storage for entries is partitioned across cluster nodes. See "Distributed Cache" for a more detailed description of partitioned caches. See "Partitioned Cache" 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 (see <local-storage> subelement) are considered "cache clients".

Cache Partitions

The cache entries are evenly segmented into several logical partitions (see <partition-count> subelement), and each storage enabled (see <local-storage> subelement) cluster node running the specified partitioned service (see <service-name> subelement) is 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 (see <key-associator> subelement) may be used to indicate related entries, the partitioned cache service ensures 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 by using the <backing-map-scheme> subelement. For instance a partitioned cache which uses a local-scheme for its backing map results in cache entries being stored in-memory on the storage-enabled cluster nodes.

Failover

For the purposes of failover, a configured number of backups (see <backup-count> subelement) of the cache may be maintained in backup-storage (see <backup-storage> subelement) across the cluster nodes. Each backup is also divided into partitions, and when possible a backup partition does not reside on the same computer as the primary partition. If a cluster node abruptly leaves the cluster, responsibility for its partitions are automatically reassigned to the existing backups, and new backups of those partitions are created (on remote nodes) 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 (see <transfer-threshold> subelement).

Elements

Table B-20 describes the subelements of the distributed-scheme element.

Table B-20 distributed-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies the name of the service which manages caches created from this scheme. Services are configured in the <services> element in the tangosol-coherence.xml descriptor. See Appendix A, "Operational Configuration Elements" for more information.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

<compressor>

Optional

Specifies whether or not backup updates should be compressed in delta form or sent whole. A delta update represents the parts of a backup entry that must be changed in order to synchronize it with the primary version of the entry. Deltas are created and applied using a compressor. The default value is the compressor value specified in the tangosol-coherence.xml descriptor. See the compressor parameter in "DistributedCache Service Parameters" for more information. Valid values are:

standard – Automatically selects a delta compressor based on the serializer being used by the partitioned service.

<instance> – The configuration for a class that implements the com.tangosol.io.DeltaCompressor interface.

<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. The default value is the thread-count value specified in the tangosol-coherence.xml descriptor. See the thread-count parameter in "DistributedCache Service Parameters" for more information.

<lease-granularity>

Optional

Specifies the lease ownership granularity. 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. The default value is the lease-granularity value specified in the tangosol-coherence.xml descriptor. See the lease-granularity parameter in "DistributedCache Service Parameters" for more information.

<local-storage>

Optional

Specifies whether a cluster node contributes storage to the cluster, that is, maintain partitions. When disabled the node is considered a cache client.

Legal values are true or false. The default value is the local-storage value specified in the tangosol-coherence.xml descriptor. See the local-storage parameter in "DistributedCache Service Parameters" for more information.

<partition-count>

Optional

Specifies the number of partitions that a partitioned (distributed) cache is organized into. Each member running the partitioned cache service that has the local-storage (<local-storage> subelement) option set to true manages a balanced number of partitions.

The number of partitions should be a prime number and sufficiently large such that a given partition is expected to be no larger than 50MB.

Valid values are positive integers. The default value is 257 as specified in the tangosol-coherence.xml descriptor. See the partition-count parameter in "DistributedCache Service Parameters".

<transfer-threshold>

Optional

Specifies the threshold for the primary buckets distribution in kilobytes. 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 makes the distribution process take longer, but reduces network bandwidth utilization during this activity. Legal values are integers greater then zero. The default value is the transfer-threshold value specified in the tangosol-coherence.xml descriptor. See the transfer-threshold parameter in "DistributedCache Service Parameters" for more information.

<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. A value of 0 means that for abnormal termination, some portion of the data in the cache is lost. Value of N means that if up to N cluster nodes terminate immediately, the cache data is 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 is in the order of M*(N+1). Recommended values are 0 or 1. The default value is the backup-count value specified in the tangosol-coherence.xml descriptor. See the backup-count parameter in value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<backup-count-after-writebehind>

Optional

Specifies the number of members of the partitioned cache service that holds the backup data for each unit of storage in the cache that does not require write-behind, that is, data that is not vulnerable to being lost even if the entire cluster were shut down. Specifically, if a unit of storage is marked as requiring write-behind, then it is backed up on the number of members specified by the <backup-count> subelement. If the unit of storage is not marked as requiring write-behind, then it is backed up by the number of members specified by the <backup-count-after-writebehind> element.

This value should be set to 0 or this setting should not be specified at all. The rationale is that since this data is being backed up to another data store, no in-memory backup is required, other than the data temporarily queued on the write-behind queue to be written. The value of 0 means that when write-behind has occurred, the backup copies of that data is discarded. However, until write-behind occurs, the data is backed up in accordance with the <backup-count> setting.

Specifies a class that is 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.

Specifies a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface, which is responsible for assigning keys to partitions. This implementation must have a zero-parameter public constructor. If unspecified, the default key partitioning algorithm is used, which ensures that keys are evenly segmented across partitions.

<partition-assignment-strategy>

Optional

Specifies the strategy that is used by a partitioned service to manage partition distribution. Valid values are legacy or a class that implements the com.tangosol.net.partition.PartitionAssignmentStrategy interface. The legacy assignment strategy indicates that partition distribution is managed individually on each cluster member. Whereas; a custom strategy allows for a shared strategy across the cluster. Enter a custom strategy using the <instance> element. The default value is legacy.

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). The default value is the task-hung-threshold value specified in the tangosol-coherence.xml descriptor. See the task-hung-threshold parameter in "DistributedCache Service Parameters" for more information.

<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). If zero is specified, the default service-guardian<timeout-milliseconds> value is used. Legal values are nonnegative integers. The default value is the value specified in the tangosol-coherence.xml descriptor. See the task-timeout parameter in "DistributedCache Service Parameters".

<request-timeout>

Optional

Specifies the maximum amount of time a client waits 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:

the time it takes to deliver the request to an executing node (server)

the interval between the time the task is received and placed into a service queue until the execution starts

the task execution time

the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout). The default value is the value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "DistributedCache Service Parameters" for more information.

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

<member-listener>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.MemberListener interface. The implementation must have a public default constructor. See the subelements for "instance" for the elements used to define the class.

The MemberListener implementation receives cache service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

Note that when using an off-heap backing map it is important that the corresponding <backup-storage> be configured for off-heap (potentially using the same scheme as the backing-map). Here off-heap refers to any storage where some or all entries are stored outside of the JVMs garbage collected heap space. Examples include: <overflow-scheme> and <external-scheme>. See "Partitioned Cache with Overflow" for an example configuration.

Specifies an implementation of a MapListener which is notified of events occurring on the cache.

<autostart>

Optional

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

Configures the external cache to use an off JVM heap, memory region for cache storage.

<high-units>

Optional

Used to limit the size of the cache. Contains the maximum number of units that can be placed in the cache before pruning occurs. An entry is the unit of measurement. When this limit is exceeded, the cache begins the pruning process, evicting the least recently used entries until the number of units is brought below this limit. The scheme's class-name element may be used to provide custom extensions to SerializationCache, which implement alternative eviction policies. Legal values are positive integers or zero. Zero implies no limit. The default value is zero.

<unit-calculator>

Optional

Specifies the type of unit calculator to use. A unit calculator is used to determine the cost (in "units") of a given object. Legal values are:

FIXED— A unit calculator that assigns an equal weight of 1 to all cached objects.

BINARY— A unit calculator that assigns an object a weight equal to the number of bytes of memory that are required to cache the object. This calculator is used for Partitioned Caches that cache data in a binary serialized form. See com.tangosol.net.cache.BinaryMemoryCalculator for additional details.

This element is used only if the high-units element is set to a positive number. The default value is FIXED.

<unit-factor>

Optional

The unit-factor element specifies the factor by which the units, low-units and high-units properties are adjusted. Using a BINARY unit calculator, for example, the factor of 1048576 could be used to count megabytes instead of bytes.

Using a BINARY unit calculator, for example, the factor of 1048576 could be used to count megabytes instead of bytes.

Note: This element was introduced only to avoid changing the type of the units, low units and high units properties from 32-bit values to 64-bit values and is used only if the high-units element is set to a positive number.

Valid values are positive integer numbers. The default value is 1.

<expiry-delay>

Optional

Specifies the amount of time since the last update that entries are kept by the cache before being expired. Entries that have expired are not be accessible and are evicted the next time a client accesses the cache.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of seconds is assumed. A value of zero implies no expiry. The default value is 0.

Note: 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.

This scheme uses the com.tangosol.net.cache.SimpleSerializationMap class as the backing map implementation and the com.tangosol.io.journal.JournalBinaryStore to store and retrieve binary key value pairs to a journal.

Elements

Table B-53 describes the subelements of the flashjournal-scheme element.

Table B-22 flashjournal-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies a custom implementation of the simple serialization map cache. Any custom implementation must extend the com.tangosol.net.cache.SimpleSerializationMap class and declare the exact same set of public constructors as the superclass.

Specifies an HTTP server class that implements the com.tangosol.coherence.rest.server.HttpServer interface. The HTTP server class handles inbound HTTP requests. Coherence REST provides two implementations out of the box: com.tangosol.coherence.rest.server.DefaultHttpServer (backed by Oracle's lightweight HTTP server) and com.tangosol.coherence.rest.server.GrizzlyHttpServer (backed by Grizzly). The default value if no value is specified is com.tangosol.coherence.rest.server.DefaultHttpServer.

Specifies the local address (IP or DNS name) and port on which the HTTP server socket is bound.

<resource-config>

Optional

Specifies a Jersey resource configuration class that extends the com.sun.jersey.api.core.ResourceConfig class. The resource configuration class is responsible for configuring Coherence RESTful Web Services. The instance is used by the HTTP acceptor to load resource and provider classes. The class must be specified within an <instance> subelement. The default value is the com.tangosol.coherence.rest.server.DefaultResource class.

identity-manager

The <identity-manager> element contains the configuration information for initializing a javax.net.ssl.KeyManager instance.

The identity manager is responsible for managing the key material which is used to authenticate the local connection to its peer. If no key material is available, the connection cannot present authentication credentials.

Elements

Table B-25 describes the elements you can define within the identity-manager element.

Table B-25 identity-manager Subelements

Element

Required/
Optional

Description

<algorithm>

Optional

Specifies the algorithm used by the identity manager. The default value is SunX509.

initiator-config

The initiator-config element specifies the configuration information for a TCP/IP connection initiator. A connection initiator allows a Coherence*Extend client to connect to a cluster (by using a connection acceptor) and use the clustered services offered by the cluster without having to first join the cluster.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

invocation-scheme

Defines an Invocation Service. The invocation service may be used to perform custom operations in parallel on any number of cluster nodes. See the com.tangosol.net.InvocationService API for additional details.

Elements

Table B-30 describes the subelements of the invocation-scheme element.

Table B-30 invocation-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

<thread-count>

Optional

Specifies the number of daemon threads used by the invocation service. If zero, all relevant tasks are performed on the service thread. Legal values are positive integers or zero. The default value is the thread-count value specified in the tangosol-coherence.xml descriptor. See the thread-count parameter in "InvocationService Parameters".

<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). The default value is the task-hung-threshold value specified in the tangosol-coherence.xml descriptor. See the task-hung-threshold parameter in "InvocationService Parameters".

<task-timeout>

Optional

Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the com.tangosol.net.PriorityTask interface), but do not explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used (the thread-count value is positive). If zero is specified, the default service-guardian<timeout-milliseconds> value is used. Legal values are nonnegative integers. The default value is the task-timeout value specified in the tangosol-coherence.xml descriptor. See the task-timeout parameter in "InvocationService Parameters".

<request-timeout>

Optional

Specifies the default timeout value in milliseconds for requests that can time out (for example, implement the com.tangosol.net.PriorityTask interface), but do not explicitly specify the request timeout value. 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). The default value is the request-timeout value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "InvocationService Parameters".

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

<member-listener>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.MemberListener interface. The implementation must have a public default constructor.

The MemberListener implementation receives service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

<autostart>

Optional

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether this service should be automatically started at a cluster node. Legal values are true or false. The default value is false.

invocation-service-proxy

The invocation-service-proxy element contains the configuration information for an invocation service proxy managed by a proxy service.

Elements

Table B-31 describes the subelements of the invocation-service-proxy element.

Table B-31 invocation-service-proxy Subelement

Element

Required/
Optional

Description

<class-name>

Optional

Specifies the fully qualified name of a class that implements the com.tangosol.net.InvocationService interface. The class acts as an interceptor between a client and a proxied invocation service to implement custom processing as required. For example, the class could be used to perform authorization checks before allowing the use of the proxied invocation service.

Specifies whether the invocation service proxy is enabled. If disabled, clients are not able to execute Invocable objects on the proxy service JVM. Legal values are true or false. The default value is true.

Specifies a custom implementation of the LH BinaryStoreManager. Any custom implementation must extend the com.tangosol.io.lh.LHBinaryStoreManager class and declare the exact same set of public constructors.

Specifies the path name for the root directory that the LH file manager uses to store files in. If not specified or specifies a non-existent directory, a temporary file in the default location is used.

<file-name>

Optional

Specifies the name for a non-temporary (persistent) file that the LH file manager uses to store data in. Specifying this parameter causes the lh-file-manager to use non-temporary database instances. Use this parameter only for local caches that are backed by a cache loader from a non-temporary file: this allows the local cache to be pre-populated from the disk file on startup. When specified it is recommended that it use the {cache-name} macro described in "Using Parameter Macros". Normally this parameter should be left unspecified, indicating that temporary storage is to be used.

local-address

The local-address element specifies the local address (IP or DNS name) and port to which a TCP/IP socket is bound.

The local-address element is used within a TCP/IP acceptor definition to specify the address and port on which the TCP/IP server socket (opened by the connection acceptor) is bound. The socket is used by the proxy service to accept connections from Coherence*Extend clients. The following example binds the server socket to 192.168.0.2:9099.

The local-address element is used within a TCP/IP initiator definition to specify the local address and port on which the TCP/IP client socket (opened by the connection initiator) is bound. The socket is used by remote services to connect to a proxy service on the cluster. The following example binds the client socket to 192.168.0.1 on port 9099:

local-scheme

Local cache schemes define in-memory "local" caches. Local caches are generally nested within other cache schemes, for instance as the front-tier of a near-scheme. See "Near Cache" for examples of various local cache configurations.

A local cache may be backed by an external cache store (see "cachestore-scheme"). Cache misses are read-through to the back end store to retrieve the data. If a writable store is provided, cache writes are also propagate to the cache store. For optimizing read/write access against a cache store, see the "read-write-backing-map-scheme".

Size Limited Cache

The cache may be configured as size-limited, which means that when it reaches its maximum allowable size (see the <high-units> subelement) it prunes itself back to a specified smaller size (see the <low-units> subelement), choosing which entries to evict according to its eviction-policy (see the <eviction-policy> subelement). The entries and size limitations are measured in terms of units as calculated by the scheme's unit-calculator (see the <unit-calculator> subelement).

Entry Expiration

The local cache supports automatic expiration of entries based on the age of the value (see the <expiry-delay> subelement).

Specifies a custom implementation of the local cache. Any custom implementation must extend the com.tangosol.net.cache.LocalCache class and declare the exact same set of public constructors.

<service-name>

Optional

Specifies the name of the service which manages caches created from this scheme. Services are configured from within the <services> element in the tangosol-coherence.xml descriptor. See Appendix A, "Operational Configuration Elements" for more information.

LRU – Least Recently Used eviction policy chooses which entries to evict based on how recently they were last accessed, evicting those that were not accessed the for the longest period first.

LFU – Least Frequently Used eviction policy chooses which entries to evict based on how often they are being accessed, evicting those that are accessed least frequently first.

HYBRID (default) – Hybrid eviction policy chooses which entries to evict based on the combination (weighted score) of how often and recently they were accessed, evicting those that are accessed least frequently and were not accessed for the longest period first.

<class-scheme> – A custom eviction policy, specified as a class-scheme. The class specified within this scheme must implement the com.tangosol.net.cache.LocalCache.EvictionPolicy interface.

<high-units>

Optional

Used to limit the size of the cache. Contains the maximum number of units that can be placed in the cache before pruning occurs. An entry is the unit of measurement, unless it is overridden by an alternate unit-calculator (see <unit-calculator> subelement). When this limit is exceeded, the cache begins the pruning process, evicting entries according to the eviction policy. Legal values are positive integers or zero. Zero implies no limit. The default value is 0.

<low-units>

Optional

Contains the lowest number of units that a cache is pruned down to when pruning takes place. A pruning does not necessarily result in a cache containing this number of units, however a pruning never results in a cache containing less than this number of units. An entry is the unit of measurement, unless it is overridden by an alternate unit-calculator (see <unit-calculator> subelement). When pruning occurs entries continue to be evicted according to the eviction policy until this size. Legal values are positive integers or zero. Zero implies the default. The default value is 75% of the high-units setting (that is, for a high-units setting of 1000 the default low-units is 750).

<unit-calculator>

Optional

Specifies the type of unit calculator to use. A unit calculator is used to determine the cost (in "units") of a given object. This element is used only if the high-units element is set to a positive number. Legal values are:

FIXED (default) – A unit calculator that assigns an equal weight of 1 to all cached objects.

BINARY – A unit calculator that assigns an object a weight equal to the number of bytes of memory that are required to cache the object. This calculator is used for Partitioned Caches that cache data in a binary serialized form. See com.tangosol.net.cache.BinaryMemoryCalculator for additional details.

The unit-factor element specifies the factor by which the units, low-units and high-units properties are adjusted. Using a BINARY unit calculator, for example, the factor of 1048576 could be used to count megabytes instead of bytes.

Using a BINARY unit calculator, for example, the factor of 1048576 could be used to count megabytes instead of bytes.

Note: This element was introduced only to avoid changing the type of the units, low units and high units properties from 32-bit values to 64-bit values and is used only if the high-units element is set to a positive number.

Valid values are positive integer numbers. The default value is 1.

<expiry-delay>

Optional

Specifies the amount of time since the last update that entries are kept by the cache before being expired. Entries that have expired are not accessible and are evicted the next time a client accesses the cache. Any attempt to read an expired entry results in a reloading of the entry from the configured cache store (see <cachestore-scheme>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of seconds is assumed. A value of zero implies no expiry. The default value is 0.

Note: 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.

near-scheme

The near-scheme defines a two-tier cache consisting of a front-tier which caches a subset of a back-tier cache. The front-tier is generally a fast, size limited cache, while the back-tier is slower, but much higher capacity cache. A typical deployment might use a local cahce for the front-tier, and a distributed cache for the back-tier. The result is that a portion of a large partitioned cache is cached locally in-memory allowing for very fast read access. See "Near Cache" for a more detailed description of near caches, and "Near Cache" for an example of near cache configurations.

The <invalidation-strategy> subelement defines a strategy that is used to keep the front tier of the near cache synchronized with the back tier. Depending on that strategy, a near cache is configured to listen to certain events occurring on the back tier and automatically update (or invalidate) the front portion of the near cache.

none – 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. The worst case performance is identical to a standard Distributed cache.

present – instructs the near cache to listen to the back map events related only to the items currently present in the front map. This strategy works best when cluster nodes have sticky data access patterns (for example, HTTP session management with a sticky load balancer).

all – instructs the near cache to listen to all back map events. This strategy is optimal for read-heavy access patterns where there is significant overlap between the front caches on each cluster member.

auto (default) – instructs the near cache to switch between present and all strategies automatically based on the cache statistics.

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

Specifies the initial buffer size in megabytes.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is 1MB.

<maximum-size>

Optional

Specifies the maximum buffer size in bytes.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is 1024MB.

<directory>

Optional

Specifies the path name for the root directory that the manager uses to store files in. If not specified or specifies a non-existent directory, a temporary file in the default location is used.

nio-memory-manager

Configures a store-manager which uses an off JVM heap, memory region for storage, which means that it does not affect the Java heap size and the related JVM garbage-collection performance that can be responsible for application pauses. See "NIO In-memory Cache" for an example of an NIO cache configuration.

Note:

JVMs require the use of a command line parameter if the total NIO buffers is greater than 64MB. For example: -XX:MaxDirectMemorySize=512M

Specifies the initial buffer size in bytes. The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is 1MB.

<maximum-size>

Optional

Specifies the maximum buffer size in bytes. The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed. Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes). The default value is 1024MB.

operation-bundling

The operation-bundling element specifies the configuration information for a particular bundling strategy.

Bundling is a process of coalescing multiple individual operations into "bundles". It could be beneficial when

there is a continuous stream of operations on multiple threads in parallel;

individual operations have relatively high latency (network or database-related); and

there are functionally analogous "bulk" operations that take a collection of arguments instead of a single one without causing the latency to grow linearly (as a function of the collection size).

Note:

As with any bundling algorithm, there is a natural trade-off between the resource utilization and average request latency. Depending on a particular application usage pattern, enabling this feature may either help or hurt the overall application performance.

Operation bundling affects cache store operations. If operation bundling is configured, the CacheStore.storeAll() method is always called even if there is only one ripe entry.

optimistic-scheme

The optimistic scheme defines a cache which fully replicates all of its data to all cluster nodes that run the service (see <service-name> subelement). See "Optimistic Cache" for a more detailed description of optimistic caches.

Optimistic Locking

Unlike the replicated-scheme and distributed-scheme caches, optimistic caches do not support concurrency control (locking). Individual operations against entries are atomic but there is no guarantee that the value stored in the cache does not change between atomic operations. The lack of concurrency control allows optimistic caches to support very fast write operations.

Cache Storage (Backing Map)

Storage for the cache is specified by using the <backing-map-scheme> subelement). For instance, an optimistic cache which uses a local-scheme for its backing map results in cache entries being stored in-memory.

Elements

Table B-43 describes the subelements of the optimistic-scheme element.

Table B-43 optimistic-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies the name of the service which manages caches created from this scheme. Services are configured from within the <services> parameter in tangosol-coherence.xml. See Appendix A, "Operational Configuration Elements" for more information.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

<request-timeout>

Optional

Specifies the maximum amount of time a client waits 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:

the time it takes to deliver the request to an executing node (server)

the interval between the time the task is received and placed into a service queue until the execution starts

the task execution time

the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout). The default value is the value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "ReplicatedCache Service Parameters" for more information.

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

<member-listener>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.MemberListener interface. The implementation must have a public default constructor.

The MemberListener implementation receives cache service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

To ensure cache coherence, the backing-map of an optimistic cache must not use a read-through pattern to load cache entries. Either use a cache-aside pattern from outside the cache service, or switch to the distributed-scheme, which supports read-through clustered caching.

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

outgoing-message-handler

The outgoing-message-handler specifies the configuration information used to detect dropped client-to-cluster connections. For connection initiators and acceptors that use connectionless protocols, this information is necessary to detect and release resources allocated to dropped connections. Connection-oriented initiators and acceptors can also use this information as an additional mechanism to detect dropped connections.

Elements

Table B-44 describes the subelements of the outgoing-message-handler element.

Table B-44 outgoing-message-handler Subelements

Element

Required/
Optional

Description

<heartbeat-interval>

Optional

Specifies the interval between ping requests. A ping request is used to ensure the integrity of a connection.The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. A value of zero disables ping requests. The default value is zero.

<heartbeat-timeout>

Optional

Specifies the maximum amount of time to wait for a response to a ping request before declaring the underlying connection unusable.The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is the value of the request-timeout element.

<request-timeout>

Optional

Specifies the maximum amount of time to wait for a response message before declaring the underlying connection unusable.The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is an infinite timeout (0s) for clustered client requests and 30 seconds (30s) for non-clustered client requests.

overflow-scheme

The overflow-scheme defines a two-tier cache consisting of a fast, size limited front-tier, and slower but much higher capacity back-tier cache. When the size limited front fills up, evicted entries are transparently moved to the back. In the event of a cache miss, entries may move from the back to the front. A typical deployment might use a local-scheme for the front-tier, and a external-scheme for the back-tier, allowing for fast local caches with capacities larger than the JVM heap allows. In such a deployment, the local-scheme element's high-units and eviction-policy controls the transfer (eviction) of entries from the front to back caches.

Note:

Relying on overflow for normal cache storage is not recommended. It should only be used to help avoid eviction-related data loss in the case where the storage requirements temporarily exceed the configured capacity. In general, the overflow's on-disk storage should remain empty.

Specifies a cache-scheme for maintaining information on cache misses. For caches which are not expiry-enabled (see <expiry-enabled> subelement), the miss-cache is used track keys which resulted in both a front and back tier cache miss. The knowledge that a key is not in either tier allows some operations to perform faster, as they can avoid querying the potentially slow back-tier. A size limited scheme may be used to control how many misses are tracked. If unspecified, no cache-miss data is maintained. Legal values are:

Specifies the amount of time since the last update that entries are kept by the cache before being expired. Entries that have expired are not be accessible and are evicted the next time a client accesses the cache.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of seconds is assumed. A value of zero implies no expiry. The default value is 0.

Note: 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.

<autostart>

Optional

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

paged-external-scheme

As with external-scheme, paged-external-schemes define caches which are not JVM heap based, allowing for greater storage capacity. The paged-external scheme optimizes LRU eviction by using a paging approach. See Chapter 15, "Serialization Paged Cache," for a detailed description of the paged cache functionality.

Cache entries are maintained over a series of pages, where each page is a separate com.tangosol.io.BinaryStore, obtained from the configured storage manager (see "Pluggable Storage Manager"). When a page is created it is considered to be the current page and all write operations are performed against this page. On a configured interval (see <page-duration> subelement), the current page is closed and a new current page is created. Read operations for a given key are performed against the last page in which the key was stored. When the number of pages exceeds a configured maximum (see <page-limit> subelement), the oldest page is destroyed and those items which were not updated since the page was closed are evicted. For example configuring a cache with a duration of ten minutes per page, and a maximum of six pages, results in entries being cached for at most an hour. Paging improves performance by avoiding individual delete operations against the storage manager as cache entries are removed or evicted. Instead the cache simply releases its references to those entries, and relies on the eventual destruction of an entire page to free the associated storage of all page entries in a single stroke.

Pluggable Storage Manager

External schemes use a pluggable store manager to create and destroy pages, and to access entries within those pages. Supported store-managers include:

Configures the paged external cache to use an off JVM heap, memory region for cache storage.

<page-limit>

Optional

Specifies the maximum number of pages that the cache manages before older pages are destroyed. Legal values are zero or positive integers between 2 and 3600. The default value is zero.

<page-duration>

Optional

Specifies the length of time, in seconds, that a page in the cache is current. After the duration is exceeded, the page is closed and a new current page is created. The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of seconds is assumed. Legal values are zero or values between 5 and 604800 seconds (one week). The default value is zero.

partition-listener

Table B-47 describes the subelements of the partition-listener element.

Table B-47 partition-listener Subelements

Element

Required/
Optional

Description

<class-name>

Required

The name of a class that implements the PartitionListener interface. This implementation must have a zero-parameter public constructor. The default value is the value specified in the partition-listener/class-name parameter in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<class-factory-name>

Optional

Specifies the fully qualified name of a factory class for creating implementation class instances.

This element cannot be used with the <class-name> element and is used with the <method-name> element.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which performs object instantiation.

Specifies the minimum number of ownership-enabled members of a partitioned service that must be present to perform partition distribution.

The value must be a nonnegative integer.

<restore-quorum>

Optional

Specifies the minimum number of ownership-enabled members of a partitioned service that must be present to restore lost primary partitions from backup.

The value must be a nonnegative integer.

<read-quorum>

Optional

specifies the minimum number of storage members of a cache service that must be present to process "read" requests. A "read" request is any request that does not mutate the state or contents of a cache.

The value must be a nonnegative integer.

<write-quorum>

Optional

specifies the minimum number of storage members of a cache service that must be present to process "write" requests. A "write" request is any request that may mutate the state or contents of a cache.

The value must be a nonnegative integer.

<class-name>

Optional

Specifies a class that provides custom quorum policies. This element cannot be used with the default quorum elements or the <class-factory-name> element.

The class must implement the com.tangosol.net.ActionPolicy interface. Initialization parameters can be specified using the <init-params> element.

<class-factory-name>

Optional

Specifies a factory class for creating custom action policy instances. This element cannot be used with the default quorum elements or the <class-name> element.

This element is used with the <method-name> element. The action policy instances must implement the com.tangosol.net.ActionPolicy interface.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which performs object instantiation.

proxy-config

The proxy-config element specifies the configuration information for the clustered service proxies managed by a proxy service. A service proxy is an intermediary between a remote client (connected to the cluster by using a connection acceptor) and a clustered service used by the remote client.

proxy-scheme

The proxy-scheme element contains the configuration information for a clustered service that allows Coherence*Extend clients to connect to the cluster and use clustered services without having to join the cluster.

Specifies the number of daemon threads used by the service. If zero, all relevant tasks are performed on the service thread. Legal values are positive integers or zero. The default value is the value specified in the thread-count parameter of the tangosol-coherence.xml descriptor. See "ProxyService Parameters" for more information.

<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). The default value is the value specified in the tangosol-coherence.xml descriptor. See the task-hung-threshold parameter in "ProxyService Parameters" for more information.

<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). If zero is specified, the default service-guardian<timeout-milliseconds> value is used. Legal values are nonnegative integers. The default value is the value specified in the tangosol-coherence.xml descriptor. See the task-timeout parameter in "ProxyService Parameters".

<request-timeout>

Optional

Specifies the maximum amount of time a client waits 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:

the time it takes to deliver the request to an executing node (server)

the interval between the time the task is received and placed into a service queue until the execution starts

the task execution time

the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout). The default value is the value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "ProxyService Parameters" for more information.

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

<member-listener>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.MemberListener interface. The implementation must have a public default constructor.

The MemberListener implementation receives service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

Contains the configuration of the connection acceptor used by the service to accept connections from Coherence*Extend clients and to allow them to use the services offered by the cluster without having to join the cluster.

client – This strategy relies upon the client address provider implementation to dictate the distribution of clients across proxy service members. If no client address provider implementation is provided, the extend client tries each proxy service in a random order until a connection is successful.

a custom class – an <instance> subelement is used to provide the configuration information for a class that implements the com.tangosol.net.proxy.ProxyServiceLoadBalancer interface.

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether this service should be automatically started at a cluster node. Legal values are true or false. The default value is false.

This scheme uses the com.tangosol.net.cache.SimpleSerializationMap class as the backing map implementation and the com.tangosol.io.journal.JournalBinaryStore to store and retrieve binary key value pairs to a journal.

Elements

Table B-53 describes the subelements of the ramjournal-scheme element.

Table B-53 ramjournal-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies a custom implementation of the simple serialization map cache. Any custom implementation must extend the com.tangosol.net.cache.SimpleSerializationMap class and declare the exact same set of public constructors as the superclass.

A read write backing map maintains a cache backed by an external persistent cache store (see <cachestore-scheme> subelement). Cache misses are read-through to the back-end store to retrieve the data. If a writable store is provided, cache writes are also propagate to the cache store.

Refresh-Ahead Caching

When enabled (see <refreshahead-factor> subelement) the cache watches for recently accessed entries which are about to expire, and asynchronously reload them from the cache store. This insulates the application from potentially slow reads against the cache store, as items periodically expire.

Write-Behind Caching

When enabled (see <write-delay> subelement), the cache delays writes to the back-end cache store. This allows for the writes to be batched (see <write-batch-factor> subelement) into more efficient update blocks, which occur asynchronously from the client thread.

Elements

Table B-54 describes the subelements of the read-write-backing-map-scheme element.

Table B-54 read-write-backing-map-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies a custom implementation of the read write backing map. Any custom implementation must extend the com.tangosol.net.cache.ReadWriteBackingMap class and declare the exact same set of public constructors.

Specifies the maximum number of entries to write in a single storeAll operation. Valid values are positive integers or zero. The default value is 128 entries. This value has no effect if write behind is disabled.

<miss-cache-scheme>

Optional

Specifies a cache-scheme for maintaining information on cache misses. The miss-cache is used track keys which were not found in the cache store. The knowledge that a key is not in the cache store allows some operations to perform faster, as they can avoid querying the potentially slow cache store. A size-limited scheme may be used to control how many misses are cached. If unspecified no cache-miss data is maintained. Legal values are:

Specifies the store to cache. If unspecified the cached data only resides within the internal cache (see <internal-cache-scheme> subelement), and only reflect operations performed on the cache itself.

<read-only>

Optional

Specifies if the cache is read only. If true the cache loads data from cachestore for read operations and do not perform any writing to the cachestore when the cache is updated. Legal values are true or false. The default value is false.

<write-delay>

Optional

Specifies the time interval to defer asynchronous writes to the cachestore for a write-behind queue. The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of seconds is assumed. If zero, synchronous writes to the cachestore (without queuing) take place, otherwise the writes are asynchronous and deferred by specified time interval after the last update to the value in the cache. The default value is zero.

This element cannot be used with the <write-delay-seconds> element.

<write-delay-seconds>

Optional

Specifies the number of seconds to defer asynchronous writes to the cachestore for a write-behind queue. If zero, synchronous writes to the cachestore (without queueing) take place; otherwise, the writes are asynchronous and deferred by the number of seconds after the last update to the value in the cache.

This element cannot be used with the <write-delay> element.

<write-batch-factor>

Optional

The write-batch-factor element is used to calculate the "soft-ripe" time for write-behind queue entries. A queue entry is considered to be "ripe" for a write operation if it has been in the write-behind queue for no less than the write-delay interval. The "soft-ripe" time is the point in time before the actual ripe time after which an entry is included in a batched asynchronous write operation to the CacheStore (along with all other ripe and soft-ripe entries). In other words, a soft-ripe entry is an entry that has been in the write-behind queue for at least the following duration:

Conceptually, the write-behind thread uses the following logic when performing a batched update:

The thread waits for a queued entry to become ripe.

When an entry becomes ripe, the thread dequeues all ripe and soft-ripe entries in the queue.

The thread then writes all ripe and soft-ripe entries either by using store() (if there is only the single ripe entry) or storeAll() (if there are multiple ripe/soft-ripe entries). Note: if operation bundling (<operation-bundling>) is configured, then storeAll() is always called even if there is only a single ripe entry.

The thread then repeats (1).

This element is only applicable if asynchronous writes are enabled (that is, the value of the write-delay element is greater than zero) and the CacheStore implements the storeAll() method. The value of the element is expressed as a percentage of the write-delay interval. Legal values are nonnegative doubles less than or equal to 1.0. The default value is zero.

<write-requeue-threshold>

Optional

Specifies the size of the write-behind queue at which additional actions could be taken. If zero, write-behind requeuing is disabled. Otherwise, this value controls the frequency of the corresponding log messages. For example, a value of 100 produces a log message every time the size of the write queue is a multiple of 100. Legal values are positive integers or zero. The default value is zero.

<refresh-ahead-factor>

Optional

The refresh-ahead-factor element is used to calculate the "soft-expiration" time for cache entries. Soft-expiration is the point in time before the actual expiration after which any access request for an entry schedules an asynchronous load request for the entry. This attribute is only applicable if the internal cache is a local-scheme, configured with the <expiry-delay> subelement. The value is expressed as a percentage of the internal LocalCache expiration interval. If zero, refresh-ahead scheduling is disabled. If 1.0, then any get operation immediately triggers an asynchronous reload. Legal values are nonnegative doubles less than or equal to 1.0. The default value is zero.

<cachestore-timeout>

Optional

Specifies the timeout interval to use for CacheStore read and write operations. If a CacheStore operation times out, the executing thread is interrupted and may ultimately lead to the termination of the cache service. Timeouts of asynchronous CacheStore operations (for example, refresh-ahead, write-behind) do not result in service termination. The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. If 0 is specified, the default service-guardian<timeout-milliseconds> value is used. The default value if none is specified is 0.

<rollback-cachestore-failures>

Optional

Specifies whether exceptions caught during synchronous cachestore operations are rethrown to the calling thread (possibly over the network to a remote member). Legal values are true or false. If the value of this element is false, an exception caught during a synchronous cachestore operation is logged locally and the internal cache is updated. If the value is true, the exception is rethrown to the calling thread and the internal cache is not changed. If the operation was called within a transactional context, this would have the effect of rolling back the current transaction. The default value is true.

remote-addresses

The remote-addresses element contains the address (IP or DNS name) and port of one or more TCP/IP acceptors. The TCP/IP initiator uses this information to establish a connection with a proxy service on remote cluster. TCP/IP acceptors are configured within the proxy-scheme element. The TCP/IP initiator attempts to connect to the addresses in a random order until either the list is exhausted or a TCP/IP connection is established. See Oracle Coherence Client Guide for additional details and example configurations.

The following example configuration instructs the initiator to connect to 192.168.0.2:9099 and 192.168.0.3:9099 in a random order:

Contains the configuration of the connection initiator used by the service to establish a connection with the cluster.

<defer-key-association-check>

Optional

Specifies whether key association processing is done by the extend client or deferred to the cluster side. Valid values are true and false. The default value is false and indicates that key association processing is done by the extend client. If the value is set to true, NET and C++ clients must include a parallel Java implementation of the key class on the cluster cache servers.

remote-invocation-scheme

The remote-invocation-scheme element contains the configuration information necessary to execute tasks within a cluster without having to first join the cluster. This scheme uses Coherence*Extend to connect to the cluster.

Elements

Table B-57 describes the subelements of the remote-invocation-scheme element.

Table B-57 remote-invocation-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

replicated-scheme

The replicated scheme defines caches which fully replicate all their cache entries on each cluster nodes running the specified service. See "Replicated Cache" for a more detailed description of replicated caches.

Clustered Concurrency Control

Replicated 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 Storage (Backing Map)

Storage for the cache is specified by using the backing-map scheme (see <backing-map> subelement). For instance, a replicated cache which uses a local-scheme for its backing map results in cache entries being stored in-memory.

Elements

Table B-58 describes the subelements of the replicated-scheme element.

Table B-58 replicated-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies the name of the service which manages caches created from this scheme. Services are configured from within the <services> element in the tangosol-coherence.xml file. See Appendix A, "Operational Configuration Elements" for more information.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

<standard-lease-milliseconds>

Optional

Specifies the duration of the standard lease in milliseconds. When a lease has aged past this number of milliseconds, the lock is automatically released. Set this value to zero to specify a lease that never expires. The purpose of this setting is to avoid deadlocks or blocks caused by stuck threads; the value should be set higher than the longest expected lock duration (for example, higher than a transaction timeout). It's also recommended to set this value higher than packet-delivery/timeout-milliseconds value. Legal values are from positive long numbers or zero. The default value is the value specified for packet-delivery/timeout-milliseconds in the tangosol-coherence.xml descriptor. See "ReplicatedCache Service Parameters" for more information.

<lease-granularity>

Optional

Specifies the lease ownership granularity. 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. The default value is the lease-granularity value specified in the tangosol-coherence.xml descriptor. See "ReplicatedCache Service Parameters" for more information.

<request-timeout>

Optional

Specifies the maximum amount of time a client waits 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:

the time it takes to deliver the request to an executing node (server)

the interval between the time the task is received and placed into a service queue until the execution starts

the task execution time

the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout). The default value is the value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "ReplicatedCache Service Parameters" for more information.

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

<member-listener>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.MemberListener interface. The implementation must have a public default constructor.

The MemberListener implementation receives cache service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

To ensure cache coherence, the backing-map of a replicated cache must not use a read-through pattern to load cache entries. Either use a cache-aside pattern from outside the cache service, or switch to the distributed-scheme, which supports read-through clustered caching.

The autostart element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

serializer

The serializer element contains the class configuration information for a com.tangosol.io.Serializer implementation.

The serializer element accepts either a reference to a serializer configuration or a full serializer configuration. The best practice is to reference a configuration which is defined in the operational configuration file. The operational configuration file contains two pre-defined serializer class configuration: one for Java (default) and one for POF. See "serializer".

The following example demonstrates referring to the POF serializer definition that is in the operational configuration file:

...
<serializer>pof</serializer>
...

The following example demonstrates a full serializer class configuration:

socket-provider

The <socket-provider> element contains the configuration information for a socket and channel factory that implements the com.tangosol.net.SocketProvider interface. The socket providers that are configured within the <tcp-acceptor> and <tcp-initiator> elements are for use with Coherence*Extend. Socket providers for TCMP are configured in an operational override for within the <unicast-listener> element.

The <socket-provider> element accepts either a reference to a socket provider configuration or a full socket provider configuration. The best practice is to reference a configuration which is defined in the operational configuration file. See "socket-providers".

Out-of-box, the operational configuration file contains two pre-defined socket provider configurations: system (default) and ssl. Additional socket providers can be defined in an operational override file as required. Socket provider configurations are referred to using their id attribute name. The following example refers to the pre-defined SSL socket provider configuration:

<socket-provider>ssl</socket-provider>

Preconfigured override is tangosol.coherence.socketprovider.

Elements

Table B-61 describes the subelements you can define within the socket-provider element.

Table B-61 socket-provider Subelements

Element

Required/
Optional

Description

<system>

Optional

Specifies a socket provider that produces instances of the JVM's default socket and channel implementations.

Specifies the configuration information for an implementation of the java.util.concurrent.Executor interface.

A <class-name> subelement is used to provide the name of a class that implements the Executor interface. As an alternative, a <class-factory-name> subelement can specify a factory class for creating Executor instances and a <method-name> subelement that specifies the name of a static factory method on the factory class which performs object instantiation. Either approach can specify initialization parameters using the <init-params> element.

Specifies the configuration information for initializing a trust manager instance.

<hostname-verifier>

Optional

Specifies the configuration information for an implementation of the javax.net.ssl.HostnameVerifier interface. During the SSL handshake, if the URL's host name and the server's identification host name mismatch, the verification mechanism calls back to this instance to determine if the connection should be allowed.

A <class-name> subelement is used to provide the name of a class that implements the HostnameVerifier interface. As an alternative, a <class-factory-name> subelement can specify a factory class for creating HostnameVerifier instances and a <method-name> subelement that specifies the name of a static factory method on the factory class which performs object instantiation. Either approach can specify initialization parameters using the <init-params> element.

tcp-acceptor

The tcp-acceptor element specifies the configuration information for a connection acceptor that accepts connections from Coherence*Extend clients over TCP/IP. See Oracle Coherence Client Guide for additional details and example configurations.

Contains the configuration for a com.tangosol.net.AddressProvider implementation that supplies the local address (IP or DNS name) and port on which the TCP/IP server socket (opened by the connection acceptor) listens.

A <tcp-acceptor> element can include either a <local-address> or an <address-provider> element but not both.

<reuse-address>

Optional

Specifies whether a TCP/IP socket can be bound to an in-use or recently used address.

This setting is deprecated because the resulting behavior is significantly different across operating system implementations. The JVM, in general, selects a reasonable default which is safe for the target operating system.

Valid values are true and false. The default value depends on the operating system.

<keep-alive-enabled>

Optional

Indicates whether SO_KEEPALIVE) is enabled on a TCP/IP socket. Valid values are true and false. The default value is true.

Configures the size of the underlying TCP/IP socket network receive buffer.Increasing the receive buffer size can increase the performance of network I/O for high-volume connections, while decreasing it can help reduce the backlog of incoming data.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of one is assumed. The default value is O/S dependent.

<send-buffer-size>

Optional

Configures the size of the underlying TCP/IP socket network send buffer. The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of one is assumed. The default value is O/S dependent.

A collection of IP addresses of TCP/IP initiator hosts that are allowed to connect to this TCP/IP acceptor.

<suspect-protocol-enabled>

Optional

Specifies whether the suspect protocol is enabled to detect and close rogue Coherence*Extend client connections. The suspect protocol is enabled by default.

Valid values are true and false.

<suspect-buffer-size>

Optional

Specifies the outgoing connection backlog (in bytes) after which the corresponding client connection is marked as suspect. A suspect client connection is then monitored until it is no longer suspect or it is closed to protect the proxy server from running out of memory.

The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 2^10)

M or m (mega, 2^20)

G or g (giga, 2^30)

T or t (tera, 2^40)

If the value does not contain a factor, a factor of one is assumed. The default value is 10000000.

<suspect-buffer-length>

Optional

Specifies the outgoing connection backlog (in messages) after which the corresponding client connection is marked as suspect. A suspect client connection is then monitored until it is no longer suspect or it is closed to protect the proxy server from running out of memory. The default value is 10000.

<nominal-buffer-size>

Optional

Specifies the outgoing connection backlog (in bytes) at which point a suspect client connection is no longer considered to be suspect.

The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 2^10)

M or m (mega, 2^20)

G or g (giga, 2^30)

T or t (tera, 2^40)

If the value does not contain a factor, a factor of one is assumed. The default value is 2000000.

<nominal-buffer-length>

Optional

Specifies the outgoing connection backlog (in messages) at which point a suspect client connection is no longer considered to be suspect. The default value is 2000.

<limit-buffer-size>

Optional

Specifies the outgoing connection backlog (in bytes) at which point the corresponding client connection must be closed to protect the proxy server from running out of memory.

The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 2^10)

M or m (mega, 2^20)

G or g (giga, 2^30)

T or t (tera, 2^40)

If the value does not contain a factor, a factor of one is assumed. The default value is 100000000.

<limit-buffer-length>

Optional

Specifies the outgoing connection backlog (in messages) at which point the corresponding client connection must be closed to protect the proxy server from running out of memory. The default value is 60000.

tcp-initiator

The tcp-initiator element specifies the configuration information for a connection initiator that enables Coherence*Extend clients to connect to a remote cluster by using TCP/IP. See Oracle Coherence Client Guide for additional details and example configurations.

Contains the address of one or more TCP/IP connection acceptors. The TCP/IP connection initiator uses this information to establish a TCP/IP connection with a remote cluster.

<reuse-address>

Optional

Specifies whether a TCP/IP socket can be bound to an in-use or recently used address.

This setting is deprecated because the resulting behavior is significantly different across operating system implementations. The JVM, in general, selects a reasonable default which is safe for the target operating system.

Valid values are true and false. The default value depends on the operating system.

<keep-alive-enabled>

Optional

Indicates whether SO_KEEPALIVE is enabled on a TCP/IP socket. Valid values are true and false. The default value is true.

Configures the size of the underlying TCP/IP socket network receive buffer.Increasing the receive buffer size can increase the performance of network I/O for high-volume connections, while decreasing it can help reduce the backlog of incoming data.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of one is assumed. The default value is O/S dependent.

<send-buffer-size>

Optional

Configures the size of the underlying TCP/IP socket network send buffer.The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 210)

M or m (mega, 220)

G or g (giga, 230)

If the value does not contain a factor, a factor of one is assumed. The default value is O/S dependent.

<connect-timeout>

Optional

Specifies the maximum amount of time to wait while establishing a connection with a connection acceptor.The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is an infinite timeout.

<linger-timeout>

Optional

Enables SO_LINGER on a TCP/IP socket with the specified linger time.The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. Linger is disabled by default.

transactional-scheme

The transactional-scheme element defines a transactional cache, which is a specialized distributed cache that provides transactional guarantees. Multiple transactional-scheme elements may be defined to support different configurations. Applications use transactional caches in one of three ways:

Applications use the CacheFactory.getCache() method to get an instance of a transactional cache. In this case, there are implicit transactional guarantees when performing cache operations. However, default transaction behavior cannot be changed.

Applications explicitly use the Transaction Framework API to create a Connection instance that uses a transactional cache. In this case, cache operations are performed within a transaction and the application has full control to change default transaction behavior as required.

Java EE applications use the Coherence Resource Adapter to create a Transaction Framework API Connection instance that uses a transactional cache. In this case, cache operations are performed within a transaction that can participate as part of a distributed (global) transaction. Applications can change some default transaction behavior.

Elements

Table B-65 describes the subelements of the transactional-scheme element.

Table B-65 transactional-scheme Subelements

Element

Required/
Optional

Description

<scheme-name>

Optional

Specifies the scheme's name. The name must be unique within a configuration file.

Specifies either: the class configuration information for a com.tangosol.io.Serializer implementation used to serialize and deserialize user types, or it references a serializer class configuration that is defined in the operational configuration file (see "serializer").

<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. The default value is the thread-count value specified in the tangosol-coherence.xml descriptor. See the thread-count parameter in "DistributedCache Service Parameters" for more information.

Specifying the thread-count value changes the default behavior of the Transactional Framework's internal transaction caches that are used for transactional storage and recovery.

<local-storage>

Optional

Specifies whether a cluster node contributes storage to the cluster, that is, 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. The default value is the local-storage value specified in the tangosol-coherence.xml descriptor. See the local-storage parameter in "DistributedCache Service Parameters" for more information.

<partition-count>

Optional

Specifies the number of partitions that a partitioned (distributed) cache is "chopped up" into. Each member running the partitioned cache service that has the local-storage (<local-storage> subelement) option set to true manages a "fair" (balanced) number of partitions.

The number of partitions should be a prime number and sufficiently large such that a given partition is expected to be no larger than 50MB.

Valid values are positive integers. The default value is the value specified in the tangosol-coherence.xml descriptor. See the partition-count parameter "DistributedCache Service Parameters" for more information.

<high-units>

Optional

Specifies the transaction storage size. Once the transactional storage size is reached, an eviction policy is used that removes 25% of eligible entries from storage.

The value of this element must be in the following format:

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

where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

K or k (kilo, 2^10)

M or m (mega, 2^20)

G or g (giga, 2^30)

T or t (tera, 2^40)

If the value does not contain a factor, a factor of one is assumed. The default value is 10MB.

<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 makes the distribution process take longer, but reduces network bandwidth utilization during this activity. Legal values are integers greater then zero. The default value is the transfer-threshold value specified in the tangosol-coherence.xml descriptor. See the transfer-threshold parameter in "DistributedCache Service Parameters" for more information.

<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. A value of 0 means that for abnormal termination, some portion of the data in the cache is lost. Value of N means that if up to N cluster nodes terminate immediately, the cache data is 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 is in the order of M*(N+1). Recommended values are 0 or 1. The default value is the backup-count value specified in the tangosol-coherence.xml descriptor. See the backup-count parameter in value specified in the tangosol-coherence.xml descriptor. See "DistributedCache Service Parameters" for more information.

<partition-assignment-strategy>

Optional

Specifies the strategy used by a partitioned service to manage partition distribution. Valid values are legacy or a class that implements the com.tangosol.net.partition.PartitionAssignmentStrategy interface. The legacy assignment strategy indicates that partition distribution is managed individually on each cluster member. Whereas; a custom strategy allows for a shared strategy across the cluster. Enter the custom strategy using the <instance> element. The default value is legacy.

<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). The default value is the task-hung-threshold value specified in the tangosol-coherence.xml descriptor. See the task-hung-threshold parameter in "DistributedCache Service Parameters" for more information.

<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). If zero is specified, the default service-guardian<timeout-milliseconds> value is used. Legal values are nonnegative integers. The default value is the value specified in the tangosol-coherence.xml descriptor. See the task-timeout parameter in "DistributedCache Service Parameters".

<request-timeout>

Optional

Specifies the maximum amount of time a client waits 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:

the time it takes to deliver the request to an executing node (server)

the interval between the time the task is received and placed into a service queue until the execution starts

the task execution time

the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout). The default value is the value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in "DistributedCache Service Parameters" for more information.

<guardian-timeout>

Optional

Specifies the guardian timeout value to use for guarding the service and any dependent threads. If the element is not specified for a given service, the default guardian timeout (as specified by the <timeout-milliseconds> operational configuration element) is used. See <service-guardian>.

The value of this element must be in the following format:

[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

MS or ms (milliseconds)

S or s (seconds)

M or m (minutes)

H or h (hours)

D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed.

<service-failure-policy>

Optional

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian.

Legal values are:

exit-cluster (default) – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy causes the local node to stop the cluster services.

exit-process – attempts to recover threads that appear to be unresponsive. If the attempt fails, an attempt is made to stop the associated service. If the associated service cannot be stopped, this policy cause the local node to exit the JVM and terminate abruptly.

logging – causes any detected problems to be logged, but no corrective action to be taken.

a custom class – an <instance> subelement is used to provide the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

The element is intended to be used by cache servers (that is, com.tangosol.net.DefaultCacheServer). It specifies whether the cache services associated with this cache scheme should be automatically started at a cluster node. Legal values are true or false. The default value is false.

Attribute Reference

Table B-67 describes the system property attribute that is available in the cache configuration deployment descriptor.

Table B-67 Cache Configuration Deployment Descriptor Attribute

Attribute

Required/
Optional

Description

system-property

Optional

This attribute is used to specify a system property name for any element. The system property is used to override the element value from the Java command line. This feature enables the same operational descriptor (and override file) to be used across all cluster nodes and customize each node using the system properties. See Appendix C, "Command Line Overrides," for more information on this feature.

Scripting on this page enhances content navigation, but does not change the content in any way.