B Cache Configuration Elements

The cache configuration element reference provides a detailed description of the cache configuration deployment descriptor elements.

This appendix includes the following sections:

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:

http://xmlns.oracle.com/coherence/coherence-cache-config/1.3/coherence-cache-config.xsd

The <cache-config> element is the root element of the cache configuration descriptor and includes the XSD and namespace declarations. For example:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">

Note:

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

Cache Configuration Element Reference

The cache configuration element reference includes all non-terminal cache configuration elements.Each section includes instructions on how to use the element and also includes descriptions for all valid subelements.

acceptor-config

Used in: proxy-scheme

Description

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.

Elements

Table B-1 describes the subelements of the acceptor-config element.

Table B-1 acceptor-config Subelements

Element Required/Optional Description

<http-acceptor>

Optional

Specifies the configuration information for a connection acceptor that accepts connections from remote REST clients over HTTP. This element cannot be used together with the <tcp-acceptor> or <memcached-acceptor> elements.

<tcp-acceptor>

Optional

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> or <memcached-acceptor> elements.

<memcached-acceptor>

Optional

Specifies the configuration information for a connection acceptor that accepts connections from remote memcached clients over TCP/IP. This element cannot be used together with the <tcp-acceptor> or <http-acceptor> elements.

<incoming-message-handler>

Optional

Specifies the configuration information that is used to regulate client-to-cluster connection resource usage.

<outgoing-message-handler>

Optional

Specifies the configuration information used by the connection acceptor to detect dropped client-to-cluster connections.

<use-filters>

Optional

Contains the list of filter names to be used by this connection acceptor. For example, specifying <use-filter> as follows activates gzip compression for all network messages, which can help substantially with WAN and low-bandwidth networks.

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

<serializer>

Optional

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:

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

<connection-limit>

Optional

The maximum number of simultaneous connections allowed by this connection acceptor. Valid values are positive integers and zero. A value of zero implies no limit. The default value is zero.

address-provider

Description

The address-provider element specifies either socket address information (IP, or DNS name, and port) or an implementation of the com.tangosol.net.AddressProvider interface. The interface offers a programmatic way to define socket addresses.

The preferred approach is to reference an address provider definition that is included in an operational override file. This approach decouples deployment configuration from application configuration. However, socket addresses can also be configured in-line and is typical during development. See address-provider.

The following example references an address provider definition that contains the socket address to which a TCP/IP acceptor is bound.

<tcp-acceptor>
   <address-provider>ap2</address-provider>
</tcp-acceptor>

The following example references an address provider definition that contains the socket address of a TCP/IP acceptor on the cluster.

<tcp-initiator>
   <remote-addresses>
      <address-provider>ap3</address-provider>
   </remote-addresses>
</tcp-initiator>

The following example references an address provider definition that contains the socket address of a name service TCP/IP acceptor on the cluster.

<tcp-initiator>
   <name-service-addresses>
      <address-provider>ap4</address-provider>
   </name-service-addresses>
</tcp-initiator>

The following example references an address provider definition that contains the socket address to which a TCP/IP memcached acceptor is bound.

<memcached-acceptor>
   <address-provider>ap5</address-provider>
</memcached-acceptor>

Elements

Table B-2 describes the subelements of the address-provider element.

Table B-2 address-provider Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the fully qualified name of a class that implements the com.tangosol.net.AddressProvider interface.

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

<class-factory-name>

Optional

Specifies the fully qualified name of a factory class for creating address provider instances. The instances must implement the com.tangosol.net.AddressProvider interface.

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.

<init-params>

Optional

Specifies initialization parameters which are accessible by implementations that 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.

<socket-address>

Optional

Specifies the address (IP, or DNS name, and port) to which a socket is bound.

This element cannot be used if an address provider implementation is defined using the <class-name> or <class-factory-name> element.

async-store-manager

Description

The async-store-manager element adds asynchronous write capabilities to other store manager implementations. Supported store managers include:

Implementation

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

Elements

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

Table B-3 async-store-manager Subelements

Element Required/ Optional Description

<class-name>

Optional

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

<init-params>

Optional

Specifies initialization parameters, for use in custom async-store-manager implementations.

<bdb-store-manager>

Optional

Configures the external cache to use Berkeley Database JE on disk databases for cache storage.

<custom-store-manager>

Optional

Configures the external cache to use a custom storage manager implementation.

<nio-file-manager>

Optional

Configures the external cache to use a memory-mapped file for cache storage.

<async-limit>

Optional

Specifies the maximum number of bytes that are queued to be written asynchronously. Setting the value to zero indicates that the implementation default for the maximum number of bytes is used. The 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

Used in: tcp-acceptor.

Description

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.

Elements

Table B-4 describes the subelements of the authorized-hosts element.

Table B-4 authorized-hosts Subelements

Element Required/ Optional Description

<host-address>

Optional

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.

back-scheme

Description

The back-scheme element specifies the back-tier cache of a composite cache.

Elements

Table B-5 describes the subelements of the back-scheme element.

Table B-5 back-scheme Subelements

Element Required/ Optional Description

<distributed-scheme>

Optional

Defines a cache scheme where storage of cache entries is partitioned across the cluster nodes.

<federated-scheme>

Optional

Defines a distributed scheme that synchronizes cache entries across clusters that are participants of a federation.

<replicated-scheme>

Optional

Defines a cache scheme where each cache entry is stored on all cluster nodes.

<optimistic-scheme>

Optional

Defines a replicated cache scheme which uses optimistic rather then pessimistic locking.

<transactional-scheme>

Optional

Defines a cache scheme where storage of cache entries is partitioned across the cluster nodes with transactional guarantees.

<local-scheme>

Optional

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.

<external-scheme>

Optional

External schemes define caches which are not JVM heap based, allowing for greater storage capacity.

<paged-external-scheme>

Optional

As with external-scheme, paged-external-schemes define caches which are not JVM heap based, allowing for greater storage capacity.

<class-scheme>

Optional

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.

<flashjournal-scheme>

Optional

Specifies a scheme that uses journaling to store data to flash memory.

<ramjournal-scheme>

Optional

Specifies a scheme that uses journaling to store data to RAM memory.

<remote-cache-scheme>

Optional

Defines a cache scheme that enables caches to be accessed from outside a Coherence cluster by using Coherence*Extend.

backing-map-scheme

Description

Specifies what type of cache is used within the cache server to store 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.

Note:

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

Elements

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

Table B-6 backing-map-scheme Subelements

Element Required/ Optional Description

<federate-apply-synthetic>

Optional

Specifies whether the changes received from remote federation participants should be applied locally as synthetic updates.

Valid values are true or false. The default value is false.

Note: As a federation origin (source cluster), synthetic updates are not considered for federation to destination participants. Enabling this property may disable/cause disruption for topologies other than active-active or active-standby; multihop federation topologies may not forward changes if this flag is set.

<partitioned>

Optional

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

  • com.tangosol.net.partition.ObservableSplittingBackingCache

  • com.tangosol.net.partition.PartitionSplittingBackingCache

  • com.tangosol.net.partition.ReadWriteSplittingBackingMap

Valid values are true or false. The default value is false. Note: Backing maps that use RAM and Flash journaling are always partitioned.

<transient>

Optional

Specifies whether or not the enclosed backing map should be persisted using a persistence environment. This element is respected only for the backing-map-scheme element that is a child of a distributed-scheme element. Valid values are true or false. If set to false, a persistence environment is used to persist the contents of the backing map. If set to true, the backing map is assumed to be transient and its contents will not be recoverable upon cluster restart. The default value is false.

<sliding-expiry>

Optional

Specifies whether or not the expiry delay of entries should be extended by read operations. By default the expiry delay is only extended upon updates. The default value is false. For details on setting the expiry delay, see the <expiry-delay> element.

<storage-authorizer>

Optional

Specifies a reference to a storage access authorizer that is defined in an operational configuration file. The storage access authorizer is used by a partitioned cache to authorize access to the underlying cache data. If configured, all read and write access to the data in the cache storage (backing map) will be validated and/or audited by the configured authorizer.

The following example references a storage access authorizer definition with the id attribute authorizer1.

<storage-authorizer>auditing</storage-authorizer>

See storage-authorizer.

<local-scheme>

Optional

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.

<external-scheme>

Optional

External schemes define caches which are not JVM heap based, allowing for greater storage capacity.

<paged-external-scheme>

Optional

As with external-scheme, paged-external-schemes define caches which are not JVM heap based, allowing for greater storage capacity.

<overflow-scheme>

Optional

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.

<class-scheme>

Optional

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.

<flashjournal-scheme>

Optional

Specifies a scheme that uses journaling to store data to flash memory.

<ramjournal-scheme>

Optional

Specifies a scheme that uses journaling to store data to RAM memory.

<read-write-backing-map-scheme>

Optional

The read-write-backing-map-scheme defines a backing map which provides a size limited cache of a persistent store.

backup-storage

Used in: distributed-scheme.

Description

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

Elements

Table B-7 describes the subelements of the backup-storage element.

Table B-7 backup-storage Subelements

Element Required/ Optional Description

<type>

Optional

Specifies the type of the storage used to hold the backup data. Legal values are:

  • on-heap— (default) The corresponding implementations class is java.util.HashMap.

  • off-heap—The corresponding implementations class is com.tangosol.io.nio.BinaryMap using the com.tangosol.io.nio.DirectBufferManager.

  • file-mapped—The corresponding implementations class is com.tangosol.io.nio.BinaryMap using the com.tangosol.io.nio.MappedBufferManager.

  • 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 preconfigured system property override is coherence.distributed.backup.

<initial-size>

Optional

Specifies the initial buffer size in bytes. The class name is only applicable if the <type> element is set to off-heap or file-mapped. Specifies the initial buffer size in bytes.The value of this element must be in the following format:

(\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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

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 (2147483647). The default value is 1MB.

<maximum-size>

Optional

Specifies the initial buffer size in bytes. The class name is only applicable if the <type> element is set to off-heap or file-mapped. The value of this element must be in the following format:

(\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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

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 (2147483647). The default value is 1024MB.

<directory>

Optional

Specifies the path name for the directory that the disk persistence manager (com.tangosol.util.nio.MappedBufferManager) uses as the root to store files. The directory is only applicable if the <type> element is set to file-mapped. If a value is not specified or a non-existent directory is specified, a temporary file in the default location is used. The default value is the default temporary directory designated by the Java run time.

<class-name>

Optional

Specifies a class name for the custom storage implementation. The class name is only applicable if the <type> element is set to custom.

<scheme-name>

Optional

Specifies a scheme name for the ConfigurableCacheFactory. The scheme name is only applicable if the <type> element is set to scheme.

bdb-store-manager

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

Note:

Berkeley Database JE Java class libraries are required to use a bdb-store-manager. See Oracle Berkeley Database JE.

Description

The BDB store manager is used to define external caches which uses Berkeley Database JE on disk embedded databases for storage. See Persistent Cache on Disk and In-memory Cache with Disk Based Overflow.

Implementation

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

Elements

Table B-8 describes the subelements of the bdb-store-manager element.

Table B-8 bdb-store-manager Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies a custom implementation of the Berkeley Database BinaryStoreManager. Any custom implementation must extend the com.tangosol.io.bdb.BerkeleyDBBinaryStoreManager class and declare the exact same set of public constructors.

<init-params>

Optional

Specifies additional Berkeley DB configuration settings. See The JE Properties File in Getting Started with Berkeley DB Java Edition.

Also used to specify initialization parameters, for use in custom implementations.

<directory>

Optional

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.

bundle-config

Used in: operation-bundling.

Description

The bundle-config element specifies the bundling strategy configuration for one or more bundle-able operations.

Elements

Table B-9 describes the subelements of the bundle-config element.

Table B-9 bundle-config Subelements

Element Required/ Optional Description

<operation-name>

Optional

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:

  • load"

  • store

  • erase

For the <distributed-scheme> and <remote-cache-scheme> the valid operations are:

  • get

  • put

  • remove

In all cases there is a pseudo operation named all, referring to all valid operations. The default value is all.

<preferred-size>

Optional

Specifies the bundle size threshold. When a bundle size reaches this value, the corresponding "bulk" operation is invoked immediately. This value is measured in context-specific units.

Valid values are zero (disabled bundling) or positive values. The default value is zero.

<delay-millis>

Optional

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.

Valid values are true or false. The default value is false.

cache-config

Root Element

Description

The cache-config element is the root element of the cache configuration descriptor, coherence-cache-config.xml. See Cache Configuration Deployment Descriptor.

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

Elements

Table B-10 describes the subelements of the cache-config element.

Table B-10 cache-config Subelements

Element Required/ Optional Description

<defaults>

Optional

Defines factory wide default settings.

<interceptors>

Optional

Specifies any number of event interceptors that process events. Specifiying the <interceptors> element as a child of the <cache-config> element scopes the interceptors to the cache configuration and allows interceptors to receive events such as ConfigurableCacheFactory lifecycle events.

<caching-scheme-mapping>

Required

Specifies the caching-scheme that is used for caches, based on the cache's name.

<caching-schemes>

Required

Defines the available caching-schemes for use in the cluster.

cache-mapping

Description

Each cache-mapping element specifies the caching-schemes which are to be used for a given cache name or cache name pattern used by an application.

Elements

Table B-11 describes the subelements of the cache-mapping element.

Table B-11 cache-mapping Subelements

Element Required/ Optional Description

<cache-name>

Required

Specifies a cache name or name pattern. The name is unique within a cache factory. The slash (/) and colon (:) are reserved characters and cannot be used in cache names. The following cache name patterns are supported:

  • Exact match. For example, MyCache.

  • Prefix match using a wildcard (prefix*). For example, My* that matches to any cache name starting with My.

  • Any match using a wildcard (*). Matches to any cache name.

If a cache name can be matched to multiple cache mappings, then exact matches are selected over wildcard matches. If no exact match is specified, then the last matching wildcard pattern (based on the order in which they are defined in the file) is selected.

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

<key-type>

Optional

Specifies the fully-qualified name of the Java class for NamedCache entry keys.

<value-type>

Optional

Specifies the fully-qualified name of the Java class for NamedCache entry values.

<init-params>

Optional

Allows specifying replaceable cache scheme parameters. During cache scheme parsing, any occurrence of any replaceable parameter in format param-name is replaced with the corresponding parameter value. Consider the following cache mapping example:

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

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.

<interceptors>

Optional

Specifies any number of event interceptors that process events for a specific cache.

<federated>

Optional

Specifies whether a cache that is mapped to a federated-scheme should be federated. Valid values are true or false. Default value is true.

cache-service-proxy

Used in: proxy-config

Description

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

Elements

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

Table B-12 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.

<init-params>

Optional

Contains initialization parameters for the CacheService implementation.

<enabled>

Optional

Specifies whether the cache service proxy is enabled. If disabled, clients are not able to access any proxied caches. Legal values are true or false. The default value is true.

<lock-enabled>

Optional

Specifies whether lock requests from remote clients are permitted on a proxied cache. Legal values are true or false. The default value is false.

<read-only>

Optional

Specifies whether requests from remote clients that update a cache are prohibited on a proxied cache. Legal values are true or false. The default value is false.

cachestore-scheme

Description

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.

Elements

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

Table B-13 cachestore-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-scheme>

Optional

Specifies the implementation of the cache store. The specified class must implement either of the following interfaces.

  • com.tangosol.net.cache.CacheStore—for read-write support

  • com.tangosol.net.cache.CacheLoader—for read-only support

  • com.tangosol.net.cache.BinaryEntryStore— similar to CacheStore, but operates on BinaryEntry objects.

<remote-cache-scheme>

Optional

Configures the cachestore-scheme to use Coherence*Extend as its cache store implementation.

<operation-bundling>

Optional

Specifies the configuration information for a bundling strategy.

<federated-loading>

Optional

Specifies whether the federation service federates entries loaded from the cache store to remote participants. Valid values are true or false. The default value is false.

caching-scheme-mapping

Used in: cache-config

Description

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

Elements

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

Table B-14 caching-scheme-mapping Subelement

Element Required/ Optional Description

<cache-mapping>

Required

Contains a single binding between a cache name and the caching scheme this cache uses.

caching-schemes

Used in: cache-config

Description

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

Elements

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

Table B-15 caching-schemes Subelements

Element Required/ Optional Description

<distributed-scheme>

Optional

Defines a cache scheme where storage of cache entries is partitioned across the cluster nodes.

<optimistic-scheme>

Optional

Defines a replicated cache scheme which uses optimistic rather then pessimistic locking.

<replicated-scheme>

Optional

Defines a cache scheme where each cache entry is stored on all cluster nodes.

<transactional-scheme>

Optional

Defines a cache scheme where storage of cache entries is partitioned across the cluster nodes with transactional guarantees.

<local-scheme>

Optional

Defines a cache scheme which provides on-heap cache storage.

<external-scheme>

Optional

Defines a cache scheme which provides off-heap cache storage, for instance on disk.

<paged-external-scheme>

Optional

Defines a cache scheme which provides off-heap cache storage, that is size-limited by using time based paging.

<overflow-scheme>

Optional

Defines a two tier cache scheme where entries evicted from a size-limited front-tier overflow and are stored in a much larger back-tier cache.

<class-scheme>

Optional

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.

<flashjournal-scheme>

Optional

Specifies a scheme that stores data to flash memory.

<ramjournal-scheme>

Optional

Specifies a scheme that stores data to RAM memory.

<near-scheme>

Optional

Defines a two tier cache scheme which consists of a fast local front-tier cache of a much larger back-tier cache.

<invocation-scheme>

Optional

Defines an invocation service which can be used for performing custom operations in parallel across cluster nodes.

<read-write-backing-map-scheme>

Optional

Defines a backing map scheme which provides a cache of a persistent store.

<remote-cache-scheme>

Optional

Defines a cache scheme that enables caches to be accessed from outside a Coherence cluster by using Coherence*Extend.

<remote-invocation-scheme>

Optional

Defines an invocation scheme that enables invocations from outside a Coherence cluster by using Coherence*Extend.

<proxy-scheme>

Optional

Defines a proxy service scheme that enables remote connections to a cluster using Coherence*Extend.

class-scheme

Description

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.

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.

Elements

Table B-16 describes the subelements of the class-scheme element.

Table B-16 class-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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.

<init-params>

Optional

Specifies initialization parameters which are accessible by implementations that include a public constructor with a matching signature.

custom-store-manager

Description

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

Elements

Table B-17 describes the subelements of the custom-store-manager element.

Table B-17 custom-store-manager Subelements

Element Required/ Optional Description

<class-name>

Required

Specifies the implementation of the store manager. The specified class must implement the com.tangosol.io.BinaryStoreManager interface.

<init-params>

Optional

Specifies initialization parameters, for use in custom store manager implementations.

defaults

Used in: cache-config

Description

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.

Elements

Table B-18 describes the subelements of the defaults element.

Table B-18 defaults Subelements

Element Required/ Optional Description

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<serializer>

Optional

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:

<serializer>pof</serializer>

<socket-provider>

Optional

Specifies either: the configuration for a socket provider, or it references a socket provider configuration that is defined within the <socket-providers> element of the operational deployment descriptor. The following socket providers are available: system (default), tcp, ssl, and sdp. Refer to the socket providers 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

Description

The distributed-scheme defines caches where the storage for entries is partitioned across cluster nodes. See Understanding Distributed Caches and Partitioned Cache.

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-19 describes the subelements of the distributed-scheme element.

Table B-19 distributed-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies a name for the distributed cache service instance that manages the cache that is created from this distributed scheme. The distributed cache service definition is defined within the <services> element in the tangosol-coherence.xml file. See DistributedCache Service Parameters. Different distributed schemes can use different partitioned cache service instances to maintain separate caches. The slash (/) and colon (:) are reserved characters and cannot be used in service names. The default name if no name is specified is DistributedCache.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the service-priority value specified in the tangosol-coherence.xml descriptor. See the service-priority parameter in DistributedCache Service Parameters.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the event-dispatcher-priority value specified in the tangosol-coherence.xml descriptor. See the event-dispatcher-priority parameter in DistributedCache Service Parameters.

<serializer>

Optional

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.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in DistributedCache Service Parameters.

<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. Valid values are:

  • none – Disables delta backup; no compressor is used. The whole backup binary entry is replaced when the primary entry changes.

  • 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

Note: The thread-count element is deprecated and is replaced by setting the thread-count-min and thread-count-max elements to the same value.

Specifies the number of daemon threads used by the partitioned cache service. Legal values are positive integers, 0, or -1. The value 0 indicates that all relevant tasks are performed on the service thread. The value -1 indicates that tasks are performed on the caller's thread where possible.

<thread-count-max>

Optional

Specifies the maximum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers greater or equal to the value of the thread-count-min element. The default value is the thread-count-max value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in DistributedCache Service Parameters.

<thread-count-min>

Optional

Specifies the minimum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers less than or equal to the value of the thread-count-max element. The default value is the thread-count-min value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in DistributedCache Service Parameters.

<worker-priority>

Optional

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the worker-priority value specified in the tangosol-coherence.xml descriptor. See the worker-priority parameter in DistributedCache Service Parameters.

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

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

<partition-count>

Optional

Specifies the number of distributed cache partitions. Each storage-enabled cluster member that is running the distributed cache service manages a balanced number of partitions.

Valid values are positive integers between 1 and 32767 and should be a prime number. A list of primes can be found at http://primes.utm.edu/lists/. The default value is the value 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.

<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. The default value is the backup-count value specified in the tangosol-coherence.xml descriptor. See DistributedCache Service Parameters.

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

Recommended value is 0 or this element should be omitted.

<backup-storage>

Optional

Specifies the type and configuration for the partitioned cache backup storage.

<key-associator>

Optional

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.

<key-partitioning>

Optional

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. The default value is the partition-assignment-strategy value specified in the tangosol-coherence.xml descriptor. See the partition-assignment-strategy parameter in DistributedCache Service Parameters.

  • simple – The simple assignment strategy attempts to balance partition distribution while ensuring machine-safety

  • mirror:<service-name> – The mirror assignment strategy attempts to co-locate the service's partitions with the partitions of the specified service. This strategy is used to increase the likelihood that key-associated, cross-service cache access remains local to a member.

  • custom – a class that implements the com.tangosol.net.partition.PartitionAssignmentStrategy interface. Enter a custom strategy using the <instance> element.

<partition-listener>

Optional

Specifies a class that implements the com.tangosol.net.partition.PartitionListener interface.

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

<task-timeout>

Optional

Specifies the timeout value in milliseconds for requests executing on the service worker threads. This attribute applies only if the thread pool is used (the thread-count-min value is positive) and only applies to entry processor implementations that implement the PriorityTask interface. 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.

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

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.

<operation-bundling>

Optional

Specifies the configuration information for a bundling strategy.

<backing-map-scheme>

Optional

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

Legal schemes are:

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.

<persistence>

Optional

Specifies the persistence-related configuration for a partitioned cache service.

<partitioned-quorum-policy-scheme>

Optional

Specifies quorum policy settings for the partitioned cache service.

<listener>

Optional

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.

<interceptors>

Optional

Specifies any number of event interceptors that process events for all caches of a specific distributed service.

<async-backup>

Optional

Specifies whether the partitioned cache service backs up data asynchronously while concurrently responding to the client. Asynchronous backup is often used to increase client performance. However, applications that require strict data integrity must be designed and tested to ensure that data is not at risk. Legal values are true or false. The default value is false.

external-scheme

Description

External schemes define caches which are not JVM heap based, allowing for greater storage capacity. See Local Caches (accessible from a single JVM).

Implementation

This scheme is implemented by:

  • com.tangosol.net.cache.SerializationMap—for unlimited size caches

  • com.tangosol.net.cache.SerializationCache—for size limited caches

The implementation type is chosen based on the following rule:

  • if the <high-units> subelement is specified and not zero then SerializationCache is used;

  • otherwise SerializationMap is used.

Pluggable Storage Manager

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

  • a wrapper providing asynchronous write capabilities for of other store manager implementations

  • allows definition of custom implementations of store managers

  • uses Berkeley Database JE to implement an on disk cache

  • uses NIO to implement memory-mapped file based cache

Size Limited Cache

The cache may be configured as size-limited, which means that when it reaches its maximum allowable size (that is, the <high-units> subelement) it prunes itself.

Note:

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

Entry Expiration

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

Persistence (long-term storage)

External caches are generally used for temporary storage of large data sets, for example as the back-tier of an overflow-scheme. The Berkly database JE implementation does however support persistence for non-clustered caches, see the <store-name> subelement of bdb-store-manager. Clustered persistence should be configured by using a read-write-backing-map-scheme on a distributed-scheme.

Elements

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

Table B-20 external-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

Specifies a custom implementation of the external cache. Any custom implementation must extend either of the following classes:

  • com.tangosol.net.cache.SerializationCache—for size limited caches

  • com.tangosol.net.cache.SerializationMap—for unlimited size caches

  • com.tangosol.net.cache.SimpleSerializationMap—for unlimited size caches

  • com.tangosol.net.cache.CompactSerializationCache—for compact on-heap footprint

and declare the exact same set of public constructors as the superclass.

<init-params>

Optional

Specifies initialization parameters, for use in custom external cache implementations.

<async-store-manager>

Optional

Configures the external cache to use an asynchronous storage manager wrapper for any other storage manager. See Pluggable Storage Manager.

<bdb-store-manager>

Optional

Configures the external cache to use Berkeley Database JE on disk databases for cache storage.

<custom-store-manager>

Optional

Configures the external cache to use a custom storage manager implementation.

<nio-file-manager>

Optional

Configures the external cache to use a memory-mapped file for cache storage.

<high-units>

Optional

Specifies the size limit of the cache. The value represents 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 the <unit-calculator> subelement). 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. Valid values are positive integers and 0. The value of this element must be in the following format:

(\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:

  • B or b (byte, 1)

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

The default value is 0 and implies no limit. If the value exceeds Integer.MAX_VALUE, then a unit factor is automatically used to adjust the value accordingly. If the value does not contain a factor, a factor of one is assumed.

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

  • <class-scheme> – A custom unit calculator, specified as a class scheme. The class specified within this scheme must implement the com/tangosol/net/cache/ConfigurableCacheMap.UnitCalculator interface.

<unit-factor>

Optional

Specifies the factor by which the <low-units> and <high-units> settings are automatically adjusted if their values exceed Integer.MAX_VALUE. The <unit-factor> value is automatically calculated and does not need to be explicitly set.

<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 proactively evicted.

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.

<listener>

Optional

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

federated-scheme

Used in: caching-schemes

Description

The federated-scheme element contains the federated caching scheme configuration information. A federated cache is a partitioned cache that can be synchronized across clusters that are participants of a federation.

Elements

Table B-21 describes the subelements of the federated-scheme element.

Table B-21 federated-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies a name for the federated cache service instance that manages the cache that is created from this federated scheme. The federated cache service definition is defined within the <services> element in the tangosol-coherence.xml file. See FederatedCache Service Parameters. Different federated schemes can use different federated cache service instances to maintain separate caches. The default name if no name is specified is FederatedCache.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the service-priority value specified in the tangosol-coherence.xml descriptor. See the service-priority parameter in FederatedCache Service Parameters.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the event-dispatcher-priority value specified in the tangosol-coherence.xml descriptor. See the event-dispatcher-priority parameter in FederatedCache Service Parameters.

<serializer>

Optional

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.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in FederatedCache Service Parameters.

<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 FederatedCache Service Parameters. Valid values are:

  • none – Disables delta backup; no compressor is used. The whole backup binary entry is replaced when the primary entry changes.

  • 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

Note: The thread-count element is deprecated and is replaced by setting the thread-count-min and thread-count-max elements to the same value.

Specifies the number of daemon threads used by the partitioned cache service. Legal values are positive integers, 0, or -1. The value 0 indicates that all relevant tasks are performed on the service thread. The value -1 indicates that tasks are performed on the caller's thread where possible.

<thread-count-max>

Optional

Specifies the maximum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers greater or equal to the value of the thread-count-min element. The default value is the thread-count-max value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in DistributedCache Service Parameters.

<thread-count-min>

Optional

Specifies the minimum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers less than or equal to the value of the thread-count-max element. The default value is the thread-count-min value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in DistributedCache Service Parameters.

<worker-priority>

Optional

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the worker-priority value specified in the tangosol-coherence.xml descriptor. See the worker-priority parameter in FederatedCache Service Parameters.

<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 FederatedCache Service Parameters.

<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 FederatedCache Service Parameters.

<partition-count>

Optional

Specifies the number of federated cache partitions. Each storage-enabled cluster member that is running the federated cache service manages a balanced number of partitions.

Valid values are positive integers between 1 and 32767 and should be a prime number. A list of primes can be found at http://primes.utm.edu/lists/. The default value is the value specified in the tangosol-coherence.xml descriptor. See the partition-count parameter in FederatedCache Service Parameters.

<transfer-threshold>

Optional

Specifies the threshold for the primary buckets distribution in kilobytes. When a new node joins the federated 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 FederatedCache Service Parameters.

<backup-count>

Optional

Specifies the number of members of the federated 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. The default value is the backup-count value specified in the tangosol-coherence.xml descriptor. See FederatedCache Service Parameters.

<backup-count-after-writebehind>

Optional

Specifies the number of members of the federated 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.

Recommended value is 0 or this element should be omitted.

<backup-storage>

Optional

Specifies the type and configuration for the federated cache backup storage.

<key-associator>

Optional

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.

<key-partitioning>

Optional

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 federated service to manage partition distribution. The default value is the partition-assignment-strategy value specified in the tangosol-coherence.xml descriptor. See the partition-assignment-strategy parameter in FederatedCache Service Parameters.

  • simple – The simple assignment strategy attempts to balance partition distribution while ensuring machine-safety.

  • mirror:<service-name> – The mirror assignment strategy attempts to co-locate the service's partitions with the partitions of the specified service. This strategy is used to increase the likelihood that key-associated, cross-service cache access remains local to a member.

  • custom – a class that implements the com.tangosol.net.partition.PartitionAssignmentStrategy interface. Enter a custom strategy using the <instance> element.

<partition-listener>

Optional

Specifies a class that implements the com.tangosol.net.partition.PartitionListener interface.

<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-min 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 FederatedCache Service Parameters.

<task-timeout>

Optional

Specifies the timeout value in milliseconds for requests executing on the service worker threads. This attribute applies only if the thread pool is used (the thread-count-min value is positive) and only applies to entry processor implementations that implement the PriorityTask interface. 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 FederatedCache 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 FederatedCache Service 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. See the subelements for instance.

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.

<operation-bundling>

Optional

Specifies the configuration information for a bundling strategy.

<backing-map-scheme>

Optional

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

Legal schemes are:

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.

<persistence>

Optional

Specifies the persistence-related configuration for a federated cache service.

<partitioned-quorum-policy-scheme>

Optional

Specifies quorum policy settings for the federated cache service.

<listener>

Optional

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.

<interceptors>

Optional

Specifies any number of event interceptors that process events for all caches of a specific service.

<async-backup>

Optional

Specifies whether the partitioned cache service backs up data asynchronously while concurrently responding to the client. Asynchronous backup is often used to increase client performance. However, applications that require strict data integrity must be designed and tested to ensure that data is not at risk. Legal values are true or false. The default value is false.

<journalcache-highunits>

Optional

Specifies either a memory limit or maximum number of cache entries that the federated cache service's internal cache holds for replication to remote participants. It provides a mechanism to constrain resources utilized by federation service internal caches. Once the high-units is reached, the federation service moves all the remote participants to ERROR state and drops all the pending entries from the internal cache. Valid values are memory values (e.g. "1G") or positive integers and 0. A memory value is treated as a memory limit on federation's backlog. If no units are specified, then the value is treated as a limit on the number of entries in the backlog. A value of 0 implies no limit. The default value is 0.

<journalcache-backing-map-scheme>

Optional

Specifies a backing-map-scheme-type that contains the backing map configuration for federation's internal caches. By default, federation uses Elastic Data for its internal caches.

<socket-provider>

Optional

Specifies the configuration for a socket and channel factory.

<address-provider>

Optional

Specifies either the local address (IP, or DNS name, and port) on which the TCP/IP server socket is bound or an implementation of the com.tangosol.net.AddressProvider interface that programmatically provides a socket address. The address-provider element also supports socket address references.

<load-balancer>

Optional

Specifies a pluggable strategy that is used by a federated service to distribute connections across the set of clustered federated service members. Legal values are:

  • federation – (default) This strategy attempts to distribute connections equally across federated service members based upon existing connection count and incoming message backlog.

  • client – This strategy relies upon the address provider implementation to dictate the distribution across federation service members. If no address provider implementation is provided, then each federation service member is tried 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.federation.FederatedServiceLoadBalancer interface.

<topologies>

Optional

Specifies the configuration information for one or more topology definitions.

flashjournal-scheme

Used in: back-scheme, backing-map-scheme, caching-schemes, internal-cache-scheme

Description

The flashjournal-scheme element contains the configuration information for a scheme that stores data to external block-based file stores (flash). A flash journal resource manager controls flash journal behavior. See flashjournal-manager.

This scheme uses the com.tangosol.net.cache.CompactSerializationCache 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-22 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.

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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

<init-params>

Optional

Specifies the initialization parameters for a custom serialization map cache.

<eviction-policy>

Optional

Specifies the type of eviction policy to use. Legal values are:

  • 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 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 ConfigurableCacheMap.EvictionPolicy interface or extend the AbstractEvictionPolicy class.

<high-units>

Optional

Specifies the size limit of the cache. The value represents 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 the <unit-calculator> subelement). When this limit is exceeded, the cache begins the pruning process and evicts entries according to the eviction policy. Valid values are positive integers and 0. The value of this element must be in the following format:

(\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:

  • B or b (byte, 1)

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

The default value is 0 and implies no limit. If the value exceeds Integer.MAX_VALUE, then a unit factor is automatically used to adjust the value accordingly. If the value does not contain a factor, a factor of one is assumed.

<low-units>

Optional

Specifies 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 the <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 80% of the <high-units> setting (that is, for a <high-units> setting of 1000 the default <low-units> is 800).

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

  • <class-scheme> – A custom unit calculator, specified as a class scheme. The class specified within this scheme must implement the com/tangosol/net/cache/ConfigurableCacheMap.UnitCalculator interface.

<unit-factor>

Optional

Specifies the factor by which the <low-units> and <high-units> settings are automatically adjusted if their values exceed Integer.MAX_VALUE. The <unit-factor> value is automatically calculated and does not need to be explicitly set.

<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 proactively evicted.

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.

<listener>

Optional

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

front-scheme

Description

The front-scheme element specifies the front-tier cache of a composite cache.

Elements

Table B-23 describes the subelements of the front-scheme element.

Table B-23 front-scheme Subelements

Element Required/ Optional Description

<local-scheme>

Optional

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.

<class-scheme>

Optional

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.

http-acceptor

Used in acceptor-config

Description

The http-acceptor element specifies an acceptor for connections from remote REST clients over HTTP.

Elements

Table B-24 describes the subelements of the http-acceptor element.

Table B-24 http-acceptor subelements

Elements Required/ Optional Description

<class-name>

Optional

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 the following implementations:

  • com.tangosol.coherence.rest.server.DefaultHttpServer (backed by Oracle's lightweight HTTP server)

  • com.tangosol.coherence.rest.server.NettyHttpServer (backed by Netty)

  • com.tangosol.coherence.rest.server.SimpleHttpServer (backed by Simple HTTP server)

  • com.tangosol.coherence.rest.server.JettyHttpServer (backed by Jetty HTTP server)

  • com.tangosol.coherence.rest.server.GrizzlyHttpServer (backed by Grizzly)

The default value if no value is specified is com.tangosol.coherence.rest.server.DefaultHttpServer.

<init-params>

Optional

Contains class initialization parameters for the HTTP server class.

<socket-provider>

Optional

Specifies the configuration for a socket and channel factory.

<local-address>

Required

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 is used by the HTTP acceptor to load resource and provider classes.

<auth-method>

Optional

Specifies the authentication mechanism for the HTTP server. A client must have authenticated using the configured mechanism as a prerequisite to gaining access to any resources exposed by the server. Legal values are:

  • basic – This method requires the client to be authenticated using HTTP basic authentication.

  • cert – This method requires the client to be authenticated using client-side SSL certificate-based authentication. The certificate must be passed to the server to authenticate. An SSL-based socket provider must be configured using the <socket-provider> element.

  • cert+basic – This method requires the client to be authenticated using both client-side SSL certificate and HTTP basic authentication.

  • none (default) – This method does not require the client to be authenticated.

identity-manager

Used in: ssl.

Description

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.

<provider>

Optional

Specifies the configuration for a security provider instance.

<key-store>

Optional

Specifies the configuration for a key store implementation.

<password>

Optional

Specifies the private key password.

<password-provider>

Optional

Specifies a password provider implementation for retrieving the private key password.

This element cannot be used with the <password> element.

incoming-message-handler

Description

The <incoming-message-handler> element contains the configuration information that is used to regulate client-to-cluster connection resource usage. Connection initiators and acceptors use this information to proactively detect and release connections that use excessive resources.

Elements

Table B-25 describes the elements you can define within the incoming-message-handler element.

Table B-26 incoming-message-handler Subelements

Element Required/ Optional Description

max-message-size

Optional

Specifies the size limit of messages being sent over Coherence*Extend connections. The value of this element must be in the following format:

(\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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

If the value does not contain a factor, a factor of kilo is assumed. Legal values are positive integers between 0 and Integer.MAX_VALUE (2147483647). The default value is 0 and indicates that there is no limit on the message size.

initiator-config

Description

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.

Elements

Table B-27 describes the subelements of the initiator-config element.

Table B-27 initiator-config Subelements

Element Required/ Optional Description

<tcp-initiator>

Optional

Specifies the configuration information for a connection initiator that connects to the cluster over TCP/IP.

<incoming-message-handler>

Optional

Specifies the configuration information that is used to regulate client-to-cluster connection resource usage.

<outgoing-message-handler>

Optional

Specifies the configuration information used by the connection initiator to detect dropped client-to-cluster connections.

<use-filters>

Optional

Contains the list of filter names to be used by this connection acceptor. For example, specifying <use-filter> as follows activates gzip compression for all network messages, which can help substantially with WAN and low-bandwidth networks.

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

<serializer>

Optional

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.

<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 the <request-timeout> value. See Table B-47.

init-param

Used in: init-params.

Description

Defines a parameter and value that is used in the constructor of a class when it is instantiated. See Cache of a Database.

Initialization parameters can be specified by type or name. When using the <param-type> element, an object of the specified type is instantiated and initialized with the value specified in <param-value>. A constructor for <param-type> with the value of <param-value> is called to instantiate the object. When using the <param-name> element, a constructor for <param-name> with the value of <param-value> is called to instantiate the object.

Elements

Table B-28 describes the subelements of the init-param element.

Table B-28 init-param Subelements

Element Required/ Optional Description

<param-name>

Optional

Specifies the name of the initialization parameter. For example:

<init-param>
   <param-name>sTableName</param-name>
   <param-value>EmployeeTable</param-value>
</init-param>

The <param-name> element cannot be specified if the <param-type> element is specified.

<param-type>

Optional

Specifies the Java type of the initialization parameter. The following standard types are supported:

  • java.lang.String (string)

  • java.lang.Boolean (boolean)

  • java.lang.Integer (int)

  • java.lang.Long (long)

  • java.lang.Double (double)

  • java.math.BigDecimal

  • java.io.File

  • java.sql.Date

  • java.sql.Time

  • java.sql.Timestamp

For example:

<init-param>
   <param-type>java.lang.String</param-type>
   <param-value>EmployeeTable</param-value>
</init-param>

The <param-type> element cannot be specified if the <param-name> element is specified.

<param-value>

Required

Specifies the value of the initialization parameter. The value is in the format specific to the Java type of the parameter.

<description>

Optional

Specifies a description for the initialization parameter.

init-params

Description

Defines a series of initialization parameters as name-value pairs.

Elements

Table B-29 describes the subelements of the init-params element.

Table B-29 init-params Subelements

Element Required/ Optional Description

<init-param>

Optional

Defines an individual initialization parameter.

instance

Used in: interceptor, serializer, service-failure-policy, load-balancer, and partition-assignment-strategy

Description

The <instance> element contains the configuration of an implementation class or class factory that is used to plug in custom functionality. You can initialize parameters by writing XML which nests <instance> and <class-scheme> (or any other custom namespace) inside of <param-value> elements.

For example, given the following Java code:

public class MyClass
  {
  public MyClass(String s, OtherClass o, int i) { ... }
  }
 
public class OtherClass
  {
  public OtherClass(String s) { ... }
  }
 

You can initialize the MyClass and OtherClass classes by writing the following XML. In the XML, the MyClass class is initialized with the string Hello World and the integer 42. The instance of the OtherClass class which appears in the MyClass class, is initialized with the string Goodbye World.

<instance>
  <class-name>MyClass</class-name>
    <init-params>
      <init-param>
        <param-value>Hello World</param-value>
      </init-param>
      <init-param>
        <param-value>
          <instance>
            <class-name>OtherClass</class-name>
              <init-params>
                <init-param>
                  <param-value>Goodbye World</param-value>
                </init-param>
              </init-params>
          </instance>
        </param-value>
      </init-param>
      <init-param>
        <param-value>42</param-value>
      </init-param>
    </init-params>
  </instance>

Elements

Table B-30 describes the subelements of the instance element.

Table B-30 instance Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the fully qualified name of an implementation class.

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

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.

interceptor

Used in: interceptors

Description

The interceptor element defines the configuration associated with an event interceptor that is responsible for processing live events. Event interceptors implement the com.tangosol.net.events.EventInterceptor interface. The interface includes support to restrict an event interceptor to a specific cache or service. The interface also provides support for the @Interceptor annotation, which allows an implementation to register for a subset of events based on event types and to configure an event interceptor identifier and the ordering of event interceptors. Specifying an interceptor's identifier and ordering within the interceptor element overrides the settings in the implementation.

The Interceptor Element for Federation

Interceptors can be used within federation schemes to capture federation change records. When defined within federation schemes, the interceptor is applied only to the configured federated cache service. Interceptors that are defined as part of a participant definition in an operational file are applied to all federated cache services that use the participant. See participant.

Elements

Table B-31 describes the subelements of the interceptor element.

Table B-31 interceptor Subelements

Element Required/ Optional Description

<name>

Optional

Specifies a unique identifier for the interceptor.

<order>

Optional

Specifies whether the interceptor is the first interceptor in a chain of interceptors. The legal values are LOW and HIGH. A value of HIGH indicates that the interceptor is first in the chain of interceptors. A value of LOW indicates no order preference. The default value is LOW.

<instance>

Required

Specifies the interceptor class to instantiate. The interceptor class must implement the EventInterceptor interface.

interceptors

Description

The interceptors element contains any number of event interceptor definitions.

Elements

Table B-32 describes the subelements of the interceptors element.

Table B-32 interceptors Subelements

Element Required/ Optional Description

<interceptor>

Optional

Specifies an event interceptor implementation.

invocation-scheme

Used in: caching-schemes.

Description

Defines an Invocation Service (com.tangosol.net.InvocationService). The invocation service may be used to perform custom operations in parallel on any number of cluster nodes.

Elements

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

Table B-33 invocation-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service which manages invocations from this scheme. The slash (/) and colon (:) are reserved characters and cannot be used in service names.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the service-priority value specified in the tangosol-coherence.xml descriptor. See the service-priority parameter in Invocation Service Parameters.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the event-dispatcher-priority value specified in the tangosol-coherence.xml descriptor. See the event-dispatcher-priority parameter in Invocation Service Parameters.

<serializer>

Optional

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.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in Invocation Service Parameters.

<thread-count>

Optional

Note: The thread-count element is deprecated and is replaced by setting the thread-count-min and thread-count-max elements to the same value.

Specifies the number of daemon threads used by the partitioned cache service. Legal values are positive integers, 0, or -1. The value 0 indicates that all relevant tasks are performed on the service thread. The value -1 indicates that tasks are performed on the caller's thread where possible.

<thread-count-max>

Optional

Specifies the maximum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers greater or equal to the value of the thread-count-min element. The default value is the thread-count-max value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in Invocation Service Parameters.

<thread-count-min>

Optional

Specifies the minimum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers less than or equal to the value of the thread-count-max element. The default value is the thread-count-min value specified in the tangosol-coherence.xml descriptor. See the thread-count-max parameter in Invocation Service Parameters.

<worker-priority>

Optional

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the worker-priority value specified in the tangosol-coherence.xml descriptor. See the worker-priority parameter in Invocation Service 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-min 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 Invocation Service Parameters.

<task-timeout>

Optional

Specifies the default timeout value for tasks that can time 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-min 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 Invocation 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 request-timeout value specified in the tangosol-coherence.xml descriptor. See the request-timeout parameter in Invocation Service 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

Used in: proxy-config

Description

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

Elements

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

Table B-34 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.

<init-params>

Optional

Contains initialization parameters for the InvocationService implementation.

<enabled>

Optional

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.

key-associator

Description

Specifies an implementation of a com.tangosol.net.partition.KeyAssociator which is used to determine associations between keys, allowing related keys to reside on the same partition.

Alternatively the cache's keys may manage the association by implementing the com.tangosol.net.cache.KeyAssociation interface.

Elements

Table B-35 describes the subelements of the key-associator element.

Table B-35 key-associator Subelements

Element Required/ Optional Description

<class-name>

Required

The name of a class that implements the com.tangosol.net.partition.KeyAssociator interface. This implementation must have a zero-parameter public constructor. The default value is the value of the key-associator parameter specified in the tangosol.coherence.xml descriptor. See DistributedCache Service Parameters.

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.

key-partitioning

Description

Specifies an implementation of a com.tangosol.net.partition.KeyPartitioningStrategy which is used to determine the partition in which a key resides.

Elements

Table B-36 describes the subelements of the key-partitioning element.

Table B-36 key-partitioning Subelements

Element Required/ Optional Description

<class-name>

Required

The name of a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface. This implementation must have a zero-parameter public constructor. The default value is the value of the key-partitioning parameter specified in the tangosol-coherence.xml descriptor. See DistributedCache Service Parameters.

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.

key-store

Description

The key-store element specifies the configuration for a key store implementation to use when implementing SSL. The key store implementation is an instance of the java.security.KeyStore class.

Elements

Table B-37 describes the elements you can define within the key-store element.

Table B-37 key-store Subelements

Element Required/ Optional Description

<url>

Required

Specifies the Uniform Resource Locator (URL) to a key store.

<password>

Optional

Specifies the password for the key store.

<password-provider>

Optional

Specifies a password provider implementation for retrieving the key store password.

This element cannot be used with the <password> element.

<type>

Optional

Specifies the type of a java.security.KeyStore instance. The default value is JKS.

listener

Description

The Listener element specifies an implementation of a com.tangosol.util.MapListener which is notified of events occurring on a cache.

Elements

Table B-38 describes the subelements of the listener element.

Table B-38 listener Subelement

Element Required/ Optional Description

<class-scheme>

Required

Specifies the full class name of the listener implementation to use. The specified class must implement the com.tangosol.util.MapListener interface.

local-address

Description

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

A local address for the <tcp-acceptor> element specifies a TCP/IP server socket that is used by the proxy service to accept connections from Coherence*Extend clients. A local address for the <http-acceptor> element specifies a HTTP server socket that is used to accept connections from REST clients. The following example binds a server socket to 192.168.0.2:7077.

<local-address>
  <address>192.168.0.2</address>
  <port>7077</port>
</local-address>

A local address for the <tcp-initiator> element specifies a TCP/IP client socket that 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 7077:

<local-address>
  <address>192.168.0.1</address>
  <port>7077</port>
</local-address>

Note:

A socket address for the TCP/IP acceptor can also be defined using an address-provider element. See address-provider.

Elements

Table B-39 describes the subelements of the local-address element.

Table B-39 local-address Subelements

Element Required/ Optional Description

<address>

Optional

Specifies the address (IP or DNS name) on which a socket listens and publishes. If the address is a bind address, then the address may also be entered using CIDR notation as a subnet and mask (for example, 192.168.1.0/24), which allows runtime resolution against the available local IP addresses. The bind address can also be an external NAT address that routes to a local address; however, both addresses must use the same port.

<port>

Optional

Specifies the port on which a TCP/IP socket listens and publishes. The legal values are from 0 to 65535. The default value is 0 and indicates that the listener ports are automatically assigned from a computer's available ephemeral ports so as to avoid port conflicts with other applications.

<port-auto-adjust>

Optional

Specifies whether the port automatically increments if the specified port cannot be bound to because it is already in use. Alternatively, port conflicts can be avoided by setting the <port> element to 0. Valid values are true, false, or the upper limit on the port range. The lower limit is the value specified for the <port> element. The default value is true.

local-scheme

Description

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.

Implementation

Local caches are implemented by the com.tangosol.net.cache.LocalCache class.

Cache of an External Store

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. See 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).

Elements

Table B-40 describes the subelements of the local-scheme element.

Table B-40 local-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service which manages caches created from this scheme. The slash (/) and colon (:) are reserved characters and cannot be used in service names. Services are configured from within the <services> element in the tangosol-coherence.xml descriptor. See Operational Configuration Elements.

<eviction-policy>

Optional

Specifies the type of eviction policy to use.Legal values are:

  • 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 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 ConfigurableCacheMap.EvictionPolicy interface or extend the AbstractEvictionPolicy class.

<high-units>

Optional

Specifies the size limit of the cache. The value represents 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 the <unit-calculator> subelement). When this limit is exceeded, the cache begins the pruning process and evicts entries according to the eviction policy. Valid values are positive integers and 0. The value of this element must be in the following format:

(\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:

  • B or b (byte, 1)

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

The default value is 0 and implies no limit. If the value exceeds Integer.MAX_VALUE, then a unit factor is automatically used to adjust the value accordingly. If the value does not contain a factor, a factor of one is assumed.

<low-units>

Optional

Specifies 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 the <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 80% of the <high-units> setting (that is, for a <high-units> setting of 1000 the default <low-units> is 800).

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

  • <class-scheme> – A custom unit calculator, specified as a class scheme. The class specified within this scheme must implement the com/tangosol/net/cache/ConfigurableCacheMap.UnitCalculator interface.

<unit-factor>

Optional

Specifies the factor by which the <low-units> and <high-units> settings are automatically adjusted if their values exceed Integer.MAX_VALUE. The <unit-factor> value is automatically calculated and does not need to be explicitly set.

<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 proactively evicted. When using a cache store, 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.

<cachestore-scheme>

Optional

Specifies the store which is being cached. If unspecified the cached data only resides in memory, and only reflects operations performed on the cache itself.

<pre-load>

Optional

Specifies whether a cache pre-loads data from its CacheLoader (or CacheStore) object. Valid values are true and false. The default value is false.

<listener>

Optional

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

memcached-acceptor

Used in: acceptor-config

Description

The memcached-acceptor element contains the configuration information for an acceptor that accepts connections from remote memcached clients over TCP/IP. The acceptor allows memcached clients to use a Coherence cache over the memcached binary protocol.

Elements

Table B-41 describes the subelements of the memcached-acceptor element.

Table B-41 memcached-acceptor Subelements

Element Required/ Optional Description

<cache-name>

Required

Specifies the cache that is used by memcached clients that connect to the memcached acceptor. The cache name is resolved to an actual cache scheme using cache mappings. See cache-mapping. The cache name must resolve to a partitioned cache scheme.

<interop-enabled>

Optional

Specifies wether the memcached acceptor can by-pass the configured cache service serializer while storing the values in the cache. This is only required when sharing data between Coherence*Extend and memcached clients. The assumption is that memcached clients are using a Coherence serializer, like the POF serializer, to convert the objects into byte[] and the cache service is also using the same serializer. Legal values are true or false. The default value is false.

<memcached-auth-method>

Optional

Specifies the authentication mechanism for the memcached acceptor. A client must authenticate using the configured mechanism to gain access to any resources exposed by the server. Legal values are plain (SASL PLAIN) and none. The default value is none.

<socket-provider>

Optional

Specifies the configuration for a socket and channel factory.

<address-provider>

Required

Specifies either the local address (IP, or DNS name, and port) on which the TCP/IP server socket is bound or an implementation of the com.tangosol.net.AddressProvider interface that programmatically provides a socket address. The address-provider element also supports socket address references.

name-service-addresses

Used in: tcp-initiator

Description

The name-service-addresses element contains the address (IP, or DNS name, and port) of one or more name service TCP/IP acceptors. A TCP/IP initiator uses this information to establish a connection with a remote cluster. The TCP/IP initiator attempts to connect to the addresses in a random order until either the list is exhausted or a connection is established. See Defining a Remote Cache in Developing Remote Clients for Oracle Coherence.

Elements

Table B-42 describes the subelements of the name-service-addresses element.

Table B-42 name-service-addresses Subelements

Element Required/ Optional Description

<socket-address>

Optional

Specifies the address (IP, or DNS name, and port) on which a name service TCP/IP acceptor is listening. Multiple <socket-address> elements can be defined. The <socket-address> element cannot be used together with an <address-provider> element or an <address> element.

<address-provider>

Optional

Specifies the address (IP, or DNS name, and port) on which a name service TCP/IP acceptor is listening or the configuration for a com.tangosol.net.AddressProvider implementation that supplies the address. The address-provider element also supports socket address references. The <address-provider> element cannot be used together with a <socket-address> element or an <address> element.

<address>

Optional

Specifies an IP address or DNS name. The bind address can also be an external NAT address that routes to a local address; however, both addresses must use the same port. Multiple <address> elements can be defined. The <address> element cannot be used together with an <address-provider> element or a <socket-address> element.

near-scheme

Used in: caching-schemes.

Description

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 cache 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 Understanding Near Caches and Near Cache.

Note that:

  • The front map is reset if the back cache is destroyed.

  • The front map is reset if all storage nodes are gone.

  • The front map is reset if an extend client is disconnected with the proxy and the invalidation strategy is set to none. Use none as the invalidation strategy if you want the front map to continue to functioning after proxy disconnect.

Implementation

The near scheme is implemented by the com.tangosol.net.cache.NearCache class.

Front-tier Invalidation

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.

Elements

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

Table B-43 near-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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

<init-params>

Optional

Specifies initialization parameters for custom near cache implementations.

<front-scheme>

Required

Specifies the cache to use as the front-tier cache.

<back-scheme>

Required

Specifies the cache to use as the front-tier cache.

<invalidation-strategy>

Optional

Specifies the strategy used keep the front-tier in-sync with the back-tier. Legal values are:

  • auto (default) – This strategy is identical to the present strategy.

  • 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. Note that the front map is reset if an extend client is disconnected with the proxy.

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

  • logical – instructs a near cache to listen to all backing map events that are not synthetic deletes. A synthetic delete event could be emitted as a result of eviction or expiration. With this invalidation strategy, it is possible for the front map to contain cache entries that have been synthetically removed from the backing map. Any subsequent re-insertion of the entries to the backing map causes the corresponding entries in the front map to be invalidated.

<listener>

Optional

Specifies an implementation of a com.tangosol.util.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.

nio-file-manager

Description

Configures an external store which uses memory-mapped file for storage.

Implementation

This store manager is implemented by the com.tangosol.io.nio.MappedStoreManager class. The BinaryStore objects created by this class are instances of the com.tangosol.io.nio.BinaryMapStore.

Elements

Table B-44 describes the subelements of the nio-file-manager element.

Table B-44 nio-file-manager Subelements

Element Required/ Optional Description

<class-name>

Optional

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

<init-params>

Optional

Specifies initialization parameters, for use in custom nio-file-manager implementations.

<initial-size>

Optional

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

(\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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

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 (2147483647). 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)+[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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

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 (2147483647). 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.

operation-bundling

Description

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.

See com.tangosol.net.cache.AbstractBundler for additional implementation details.

Elements

Table B-45 describes the subelement for the operation-bundling element.

Table B-45 operation-bundling Subelement

Element Required/ Optional Description

<bundle-config>

Required

Describes one or more bundle-able operations.

optimistic-scheme

Used in: caching-schemes, near-scheme, overflow-scheme

The optimistic scheme defines a cache which fully replicates all of its data to all cluster nodes that run the service. See Understanding 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-46 describes the subelements of the optimistic-scheme element.

Table B-46 optimistic-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service which manages caches created from this scheme. The slash (/) and colon (:) are reserved characters and cannot be used in service names. Services are configured from within the <services> parameter in tangosol-coherence.xml. See Operational Configuration Elements.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 10.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 10.

<serializer>

Optional

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.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in OptimisticCache 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 ReplicatedCache Service 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 cache service lifecycle events. The <member-listener> element is used as an alternative to programmatically adding a MapListener on a service.

<backing-map-scheme>

Optional

Specifies what type of cache is used within the cache server to store the entries. Legal values are:

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.

<listener>

Optional

Specifies an implementation of a com.tangosol.util.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.

outgoing-message-handler

Description

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-47 describes the subelements of the outgoing-message-handler element.

Table B-47 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 the heartbeat ping request before closing the underlying 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.

<max-message-size>

Optional

Specifies the size limit of messages being sent over Coherence*Extend connections. The value of this element must be in the following format:

(\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, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

If the value does not contain a factor, a factor of kilo is assumed. Legal values are positive integers between 0 and Integer.MAX_VALUE (2147483647). The default value is 0 and indicates that there is no limit on the message size.

<request-timeout>

Optional

Specifies the maximum amount of time a client waits for a response message before abandoning the request. The connection is not closed until the <heartbeat-timeout> value is reached.

Note: This element is not used by a proxy service acceptor, because proxies never send requests to extend clients.

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 30s.

overflow-scheme

Description

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.

Implementation

Implemented by either com.tangosol.net.cache.OverflowMap or com.tangosol.net.cache.SimpleOverflowMap. See expiry-enabled for details.

Entry Expiration

Overflow supports automatic expiration of entries based on the age of the value, as configured by the <expiry-delay> subelement.

Elements

Table B-48 describes the subelements of the overflow-scheme element.

Table B-48 overflow-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

Specifies a custom implementation of the overflow cache. Any custom implementation must extend either the com.tangosol.net.cache.OverflowMap or com.tangosol.net.cache.SimpleOverflowMap class, and declare the exact same set of public constructors.

<init-params>

Optional

Specifies initialization parameters, for use in custom overflow cache implementations.

<front-scheme>

Required

Specifies the cache to use as the front-tier cache.

<back-scheme>

Required

Specifies the cache-scheme to use in creating the back-tier cache.

<miss-cache-scheme>

Optional

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:

<expiry-enabled>

Optional

Turns on support for automatically-expiring data, as provided by the com.tangosol.net.cache.CacheMap API. When enabled, the overflow-scheme is implemented using com.tangosol.net.cache.OverflowMap, rather than com.tangosol.net.cache.SimpleOverflowMap. Legal values are true or false. The default value is false.

<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 proactively evicted.

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.

<listener>

Optional

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

paged-external-scheme

Description

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 Serialization Paged Cache.

Implementation

This scheme is implemented by the com.tangosol.net.cache.SerializationPagedCache class.

Paging

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

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:

Persistence (long-term storage)

Paged external caches are used for temporary storage of large data sets, for example as the back-tier of an overflow-scheme. These caches are not used for long-term storage (persistence) and do not survive beyond the life of the JVM. Clustered persistence should be configured by using a read-write-backing-map-scheme on a distributed-scheme. If a non-clustered persistent cache is what is needed, see Persistence (long-term storage).

Elements

Table B-49 describes the subelements of the paged-external-scheme element.

Table B-49 paged-external-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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

<init-params>

Optional

Specifies initialization parameters, for use in custom external paged cache implementations.

<async-store-manager>

Optional

Configures the paged external cache to use an asynchronous storage manager wrapper for any other storage manager. See Pluggable Storage Manager.

<bdb-store-manager>

Optional

Configures the paged external cache to use Berkeley Database JE on disk databases for cache storage.

<custom-store-manager>

Optional

Configures the paged external cache to use a custom storage manager implementation.

<nio-file-manager>

Optional

Configures the paged external cache to use a memory-mapped file 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.

<listener>

Optional

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

partitioned-quorum-policy-scheme

Description

The partitioned-quorum-policy-scheme element contains quorum policy settings for the partitioned cache service.

Elements

Table B-50 describes the subelements of the partitioned-quorum-policy-scheme element.

Table B-50 partitioned-quorum-policy-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<distribution-quorum>

Optional

Specifies the minimum number of storage members of a partitioned service that must be present to perform partition distribution. Valid values are non-negative integers.

<restore-quorum>

Optional

Specifies the minimum number of storage members of a partitioned service that must be present to restore lost primary partitions from backup. Valid values are non-negative integers.

<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. Valid values are non-negative integers.

<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. Valid values are non-negative integers.

<recover-quorum>

Optional

Specifies the minimum number of storage members of a partitioned service that must be present in order to recover orphaned partitions from the persistence storage, or assign empty partitions if the persistence storage is unavailable or lost. Valid values are non-negative integers. A value of zero enables the dynamic recovery policy, which ensures availability of all persisted state and is based on the last good cluster membership information to determine how many members must be present for the recovery. The default value is zero.

<recovery-hosts>

Optional

Specifies a reference to the set of host-addresses that is configured in an operational configuration file. The set of host-addresses must be represented by the set of storage members in order to recover orphaned partitions from the persistent storage, or assign empty partitions if the persistent storage is unavailable or lost.

The following example references a host address list that is called persistence-host-list.

<partitioned-quorum-policy-scheme>
   <recovery-hosts>persistence-host-list</recovery-hosts>
</partitioned-quorum-policy-scheme>

See The address-provider Element for Persistence.

Note: A host address list must not be specified if the recover-quorum element is set to 0.

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.

partition-listener

Description

Specifies an implementation of a com.tangosol.net.partition.PartitionListener interface, which allows receiving partition distribution events.

Elements

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

Table B-51 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 parameter in the tangosol-coherence.xml descriptor. See DistributedCache Service Parameters.

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.

persistence

Description

The persistence element contains the persistence-related configuration for a distributed cache service.

Elements

Table B-53 describes the subelements you can define within the persistence element.

Table B-52 persistence Subelements

Element Required/ Optional Description

<environment>

Optional

Specifies a reference to a persistence environment configuration that is defined in the operational configuration file. The persistence environment is used by the enclosing distributed cache service to persist the contents of backing maps. If configured, a persistence environment enables cache contents to be automatically recovered either after a cluster restart or loss of multiple members, or on-demand from a named snapshot.

The following example references a persistence environment that is called environment1.

<persistence>
   <environment>environment1</environment>
</persistence>

See persistence-environments.

<archiver>

Optional

Specifies a reference to a snapshot archiver definition that is defined in the operational configuration file. The archiver is used to archive, retrieve, or purge persistent snapshots. The following example reference an archiver that is called archiver1.

<persistence>
   <archiver>archiver1</archiver>
</persistence>

See snapshot-archivers.

<active-failure-mode>

Optional

Specifies how the service responds to an unexpected failure while performing persistence operations in active persistence mode. Legal values are:

  • stop-service (default): persistence is critical and failures encountered while writing to or recovering from the active persistent store should result in stopping the service rather than continuing without persistence.

  • stop-persistence: persistence is desirable, but the service should continue servicing requests if there is a failure encountered while writing to or recovering from the active persistent store.

provider

Description

The provider element contains the configuration information for a security provider that extends the java.security.Provider class.

Elements

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

Table B-53 provider Subelements

Element Required/ Optional Description

<name>

Optional

Specifies the name of a security provider that extends the java.security.Provider class.

The class name can be entered using either this element or by using the <class-name> element or by using the <class-factory-name> element.

<class-name>

Optional

Specifies the name of a security provider that extends the java.security.Provider class.

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

<class-factory-name>

Optional

Specifies a factory class for creating Provider instances. The instances must implement the java.security.Provider class.

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

This element can be 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.

<init-params>

Optional

Contains class initialization parameters for the provider implementation.

This element cannot be used with the <name> element.

proxy-config

Used in: proxy-scheme.

Description

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.

Elements

Table B-54 describes the subelements of the proxy-config element.

Table B-54 proxy-config Subelements

Element Required/ Optional Description

<cache-service-proxy>

Optional

Specifies the configuration information for a cache service proxy managed by the proxy service.

<invocation-service-proxy>

Optional

Specifies the configuration information for an invocation service proxy managed by the proxy service.

proxy-quorum-policy-scheme

Used in: proxy-scheme

Description

The proxy-quorum-policy-scheme element contains quorum policy settings for the Proxy service.

Elements

Table B-56 describes the subelements of the proxy-quorum-policy-scheme element.

Table B-55 proxy-quorum-policy-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<connect-quorum>

Optional

specifies the minimum number of members of a proxy service that must be present to allow client connections.

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 <connect-quorum> element 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 <connect-quorum> element 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.

<init-params>

Optional

Contains class initialization parameters for the implementation class.

proxy-scheme

Used in: caching-schemes.

Description

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.

Elements

Table B-56 describes the subelements of the proxy-scheme element.

Table B-56 proxy-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service. The slash (/) and colon (:) are reserved characters and cannot be used in service names.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 10. The default value is the value specified in the service-priority parameter in the tangosol-coherence.xml descriptor. See Proxy Service Parameters.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the value specified in the event-dispatcher-priority parameter in the tangosol-coherence.xml descriptor. See Proxy Service Parameters.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in Proxy Service Parameters.

<thread-count>

Optional

Note: The thread-count element is deprecated and is replaced by setting the thread-count-min and thread-count-max elements to the same value.

Specifies the number of daemon threads used by the partitioned cache service. Legal values are positive integers, 0, or -1. The value 0 indicates that all relevant tasks are performed on the service thread. The value -1 indicates that tasks are performed on the caller's thread where possible.

<thread-count-max>

Optional

Specifies the maximum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers greater or equal to the value of the thread-count-min element. The default value is the value specified in the thread-count-max parameter in the tangosol-coherence.xml descriptor. See Proxy Service Parameters.

<thread-count-min>

Optional

Specifies the minimum number of daemon threads. Usage of daemon threads varies for different service types. If zero or negative, the service does not use daemon threads and all relevant tasks are performed on the service thread. Furthermore, if negative, tasks are performed on the caller's thread where possible. Valid values are integers less than or equal to the value of the thread-count-max element. The default value is the value specified in the thread-count-min parameter in the tangosol-coherence.xml descriptor. See Proxy Service Parameters.

<worker-priority>

Optional

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the value specified in the worker-priority parameter in the tangosol-coherence.xml descriptor. See Proxy Service Parameters.

<task-hung-threshold>

Optional

Specifies the amount of time in milliseconds that a task can execute before it is considered hung. Note that 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-min 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 Proxy Service Parameters.

<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-min 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 Proxy Service Parameters.

<request-timeout>

Optional

Specifies the maximum amount of time a proxy waits for requests that are sent to other proxies of the same name. This element should not be used because requests are never sent between proxies.

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

<acceptor-config>

Required

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.

<proxy-config>

Optional

Contains the configuration of the clustered service proxies managed by this service.

<load-balancer>

Optional

Specifies a pluggable strategy used by the proxy service to distribute client connections across the set of clustered proxy service members. Legal values are:

  • proxy – (default) This strategy attempts to distribute client connections equally across proxy service members based upon existing connection count, connection limit, incoming and outgoing message backlog, and daemon pool utilization.

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

<proxy-quorum-policy-scheme>

Optional

Specifies quorum policy settings for the Proxy 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.

ramjournal-scheme

Used in: back-scheme, backing-map-scheme, caching-schemes, internal-cache-scheme

Description

The ramjournal-scheme element contains the configuration information for a scheme that stores data to buffers (journal files) in-memory. A RAM journal resource manager controls RAM journal behavior. See ramjournal-manager.

This scheme uses the com.tangosol.net.cache.CompactSerializationClass 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-57 describes the subelements of the ramjournal-scheme element.

Table B-57 ramjournal-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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

<init-params>

Optional

Specifies the initialization parameters for a custom serialization map cache.

<eviction-policy>

Optional

Specifies the type of eviction policy to use. Legal values are:

  • 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 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 ConfigurableCacheMap.EvictionPolicy interface or extend the AbstractEvictionPolicy class.

<high-units>

Optional

Specifies the size limit of the cache. The value represents 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 the <unit-calculator> subelement). When this limit is exceeded, the cache begins the pruning process and evicts entries according to the eviction policy. Valid values are positive integers and 0. The value of this element must be in the following format:

(\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:

  • B or b (byte, 1)

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

  • T or t (tera, 240)

The default value is 0 and implies no limit. If the value exceeds Integer.MAX_VALUE, then a unit factor is automatically used to adjust the value accordingly. If the value does not contain a factor, a factor of one is assumed.

<low-units>

Optional

Specifies 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 the <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 80% of the high-units setting (that is, for a <high-units> setting of 1000 the default <low-units> is 800).

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

  • <class-scheme> – A custom unit calculator, specified as a class scheme. The class specified within this scheme must implement the com/tangosol/net/cache/ConfigurableCacheMap.UnitCalculator interface.

<unit-factor>

Optional

Specifies the factor by which the <low-units> and <high-units> settings are automatically adjusted if their values exceed Integer.MAX_VALUE. The <unit-factor> value is automatically calculated and does not need to be explicitly set.

<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 proactively evicted.

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.

<listener>

Optional

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

read-write-backing-map-scheme

Description

The read-write-backing-map-scheme defines a backing map which provides a size limited cache of a persistent store. See Caching Data Sources.

Implementation

The read-write-backing-map-scheme is implemented by the com.tangosol.net.cache.ReadWriteBackingMap class.

Cache of an External Store

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-58 describes the subelements of the read-write-backing-map-scheme element.

Table B-58 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.

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<class-name>

Optional

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.

<internal-cache-scheme>

Required

Specifies a cache-scheme which is used to cache entries. Legal values are:

<write-max-batch-size>

Optional

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:

<cachestore-scheme>

Optional

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:

D' = (1.0 - F) * D where D = write-delay interval and F = write-batch-factor.

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

  1. The thread waits for a queued entry to become ripe.

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

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

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

<listener>

Optional

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

remote-addresses

Used in: tcp-initiator

Description

The remote-addresses element contains the address (IP, or DNS name, and port) of one or more TCP/IP acceptors. A TCP/IP initiator uses this information to establish a connection with a proxy service on a 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 connection is established. See Defining a Remote Cache in Developing Remote Clients for Oracle Coherence.

Note:

The name-service-addresses element can also be used to establish a connection with a proxy service on a a remote cluster. See name-service-addresses.

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

<remote-addresses>
  <socket-address>
    <address>192.168.0.2</address>
    <port>7077</port>
  </socket-address>
  <socket-address>
    <address>192.168.0.3</address>
    <port>7077</port>
  </socket-address>
</remote-addresses>

Elements

Table B-59 describes the subelements of the remote-addresses element.

Table B-59 remote-addresses Subelements

Element Required/ Optional Description

<socket-address>

Optional

Specifies the address (IP, or DNS name, and port) on which a TCP/IP acceptor is listening. Multiple <socket-address> elements can be used within a <remote-addresses> element.

<address-provider>

Optional

Specifies the address (IP, or DNS name, and port) on which a TCP/IP acceptor is listening or the configuration for a com.tangosol.net.AddressProvider implementation that supplies the address. The address-provider element also supports socket address references.

A <remote-addresses> element can include either a <socket-address> element or an <address-provider> element but not both.

remote-cache-scheme

Description

The remote-cache-scheme element contains the configuration information necessary to use a clustered cache from outside the cluster by using Coherence*Extend.

Elements

Table B-60 describes the subelements of the remote-cache-scheme element.

Table B-60 remote-cache-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service which manages caches created from this scheme. The slash (/) and colon (:) are reserved characters and cannot be used in service names.

<proxy-service-name>

Optional

Specifies the proxy service name to which this remote service connects. This element is only used if this remote service uses a name service to lookup a proxy service. See name-service-addresses.

The value must match the <service-name> value of the proxy service. This element can be omitted if the <service-name> value of this remote service matches the <service-name> value of the proxy service. See proxy-scheme.

<operation-bundling>

Optional

Specifies the configuration information for a bundling strategy.

<initiator-config>

Required

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. A value of false indicates that key association processing is done by the extend client. If the value is set to true, then .NET and C++ clients must include a parallel Java implementation of the key class on the cluster cache servers. The default value is the value specified in the tangosol-coherence.xml descriptor. See RemoteCache Service Parameters.

<listener>

Optional

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

remote-invocation-scheme

Used in: caching-schemes

Description

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-61 describes the subelements of the remote-invocation-scheme element.

Table B-61 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.

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service. The slash (/) and colon (:) are reserved characters and cannot be used in service names.

<proxy-service-name>

Optional

Specifies the proxy service name to which this remote service connects. This element is only used if this remote service uses a name service to lookup a proxy service. See name-service-addresses.

The value must match the <service-name> value of the proxy service. This element can be omitted if the <service-name> value of this remote service matches the <service-name> value of the proxy service. See proxy-scheme.

<initiator-config>

Required

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

replicated-scheme

Description

The replicated scheme defines caches which fully replicate all their cache entries on each cluster nodes running the specified service. See Understanding 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-62 describes the subelements of the replicated-scheme element.

Table B-62 replicated-scheme Subelements

Element Required/ Optional Description

<scheme-name>

Optional

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

<scheme-ref>

Optional

Specifies the name of another scheme to inherit from. See Using Scheme Inheritance.

<scope-name>

Optional

Specifies the scope name for this configuration. The scope name is added (as a prefix) to all services generated by a cache factory. The name is used to isolate services when using multiple cache factories; thus, avoiding unintended joining of services with similar names from different configurations.

<service-name>

Optional

Specifies the name of the service which manages caches created from this scheme. The slash (/) and colon (:) are reserved characters and cannot be used in service names. Services are configured from within the <services> element in the tangosol-coherence.xml file. See Operational Configuration Elements.

<service-priority>

Optional

Specifies the priority for the service thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the service-priority value specified in the tangosol-coherence.xml descriptor. See ReplicatedCache Service Parameters.

<event-dispatcher-priority>

Optional

Specifies the priority for the event dispatcher thread for each service. Legal values are from 1 to 10 where 10 is the highest priority. The default value is the event-dispatcher-priority value specified in the tangosol-coherence.xml descriptor. See ReplicatedCache Service Parameters.

<serializer>

Optional

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.

<reliable-transport>

Optional

Specifies the transport protocol used by this service for reliable point-to-point communication. Specifying a value results in the use of a service-specific transport instance rather then the shared transport instance that is defined by the <unicast-listener> element. A service-specific transport instance can result in higher performance but at the cost of increased resource consumption and should be used sparingly for select, high priority services. In general, a shared transport instance uses less resource consumption than service-specific transport instances. Valid values are:

  • datagram – UDP protocol

  • tmb (default) – TCP/IP message bus protocol

  • tmbs – TCP/IP message bus protocol with SSL support. TMBS requires the use of an SSL socket provider. See socket-provider.

  • sdmb – Socket Direct Protocol (SDP) message bus.

  • sdmbs – SDP message bus with SSL support. SDMBS requires the use of an SSL socket provider. See socket-provider.

  • imb (default on Exalogic) – InfiniBand message bus. IMB is automatically used on Exalogic systems as long as TCMP has not been configured with SSL.

The default value is the <reliable-transport> value specified in the tangosol-coherence.xml descriptor. See the reliable-transport parameter in ReplicatedCache Service Parameters.

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

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

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

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

<backing-map-scheme>

Optional

Specifies what type of cache is used within the cache server to store the entries. Legal values are:

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.

<listener>

Optional

Specifies an implementation of a com.tangosol.util.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.

resource-config

Used in: http-acceptor

Description

The resource-config element contains the configuration information for a class that extends the com.sun.jersey.api.core.ResourceConfig class. The instance is used by the HTTP acceptor to load resource and provider classes for the Coherence REST application that is mapped to the specified context path. Multiple resource configuration classes can be configured and mapped to different context paths.

Elements

Table B-63 describes the subelements of the resource-config element.

Table B-63 resource-config Subelements

Element Required/ Optional Description

<context-path>

Optional

Specifies a root URI path for a REST application. The first character of the path must be /. The default value is /.

<instance>

Optional

Contains the configuration information for a class that extends the com.sun.jersey.api.core.ResourceConfig class. The default instance is the com.tangosol.coherence.rest.server.DefaultResourceConfig class.

serializer

Description

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:

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

Elements

Table B-64 describes the subelements of the serializer element.

Table B-64 serializer Subelements

Element Required/ Optional Description

<instance>

Optional

Contains the class configuration information for a com.tangosol.io.Serializer implementation.

socket-address

Description

The socket-address element specifies the address and port on which a TCP/IP acceptor is listening.

Elements

Table B-65 describes the subelements of the socket-address element.

Table B-65 socket-address Subelements

Element Required/ Optional Description

<address>

Required

Specifies the IP address (IP or DNS name) on which a TCP/IP acceptor socket is listening. If the address is a bind address, then the address may also be entered using CIDR notation as a subnet and mask (for example, 192.168.1.0/24), which allows runtime resolution against the available local IP addresses. The bind address can also be an external NAT address that routes to a local address; however, both addresses must use the same port.

<port>

Required

Specifies the port on which a TCP/IP acceptor socket is listening. Legal values are from 0 to 65535. The default value is 0 and indicates that the listener port is automatically assigned from a computer's available ephemeral ports so as to avoid port conflicts with other applications.

socket-provider

Description

The <socket-provider> element contains the configuration information for a socket and channel factory. The socket providers that are configured within the <tcp-acceptor> and <tcp-initiator> elements are for use with Coherence*Extend. A socket provider that is configured within the <http-acceptor> element is used by Coherence REST. A socket provider that is configured within the <memcached-acceptor> element is used by memcached clients. Socket providers for TCMP are configured in an operational override 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-provider. The following socket providers are available: system (default), ssl, tcp, and sdp. 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>

The preconfigured override is coherence.socketprovider.

Elements

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

Table B-66 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.

<ssl>

Optional

Specifies a socket provider that produces socket and channel implementations which use SSL.

<tcp>

Optional

Specifies a socket provider that produces TCP-based sockets and channel implementations.

<sdp>

Optional

Specifies a socket provider that produce SDP-based sockets and channel implementations provided that the JVM and underlying network stack supports SDP.

ssl

Used in: socket-provider.

Description

The <ssl> element contains the configuration information for a socket provider that produces socket and channel implementations which use SSL.

Elements

Table B-67 describes the elements you can define within the ssl element.

Table B-67 ssl Subelements

Element Required/ Optional Description

<protocol>

Optional

Specifies the name of the protocol used by the socket and channel implementations produced by the SSL socket provider. The default value is TLS.

<provider>

Optional

Specifies the configuration for a security provider instance.

<executor>

Optional

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.

<identity-manager>

Optional

Specifies the configuration information for initializing an identity manager instance.

<trust-manager>

Optional

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.

<socket-provider>

Optional

Specifies the configuration information for a delegate provider for SSL. Valid values are tcp and sdp. The default value is tcp.

<cipher-suites>

Optional

The cipher-suites element lists the names of the ciphers that are allowed or disallowed depending on the usage attribute.

If the usage attribute on the element is "black-list", the specified ciphers will be removed from the default enabled cipher list.

If the usage attribute on the element is "white-list", the specified ciphers will be the enabled ciphers.

If the usage attribute is not defined, the cipher list will be considered a white-list.

<protocol-versions>

Optional

The protocol-versions element lists the names of the protocol versions that are allowed or disallowed depending on usage attribute.

If the usage attribute on the element is "black-list", the specified protocol versions will be removed from the default enabled protocol list.

If the usage attribute on the element is "white-list", the specified protocol versions will be the enabled protocols.

If the usage attribute is not defined, the protocol list will be considered a white-list.

tcp-acceptor

Used in: acceptor-config.

Description

The tcp-acceptor element specifies the configuration information for a connection acceptor that accepts connections from Coherence*Extend clients over TCP/IP. See Explicitly Configuring Proxy Addresses in Developing Remote Clients for Oracle Coherence.

Elements

Table B-68 describes the subelements of the tcp-acceptor element.

Table B-68 tcp-acceptor Subelements

Element Required/ Optional Description