A Operational Configuration Elements

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

This appendix includes the following sections:

Operational Deployment Descriptor

The tangosol-coherence.xml operational deployment descriptor specifies the operational and run-time settings that control clustering, communication, and data management services.The operational deployment descriptor is located in the root of the coherence.jar library. A custom tangosol-coherence.xml file can be created; however, the preferred approach to changing the operational settings is to use a tangosol-coherence-override.xml operational override file. See Operational Override File.

The operational deployment descriptor schema is defined in the coherence-operational-config.xsd file, which imports the coherence-operational-config-base.xsd file, which, in turn, implicitly imports the coherence-config-base.xsd file. The operational deployment descriptor schema file is located in the root of the coherence.jar library and at the following Web URL:

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

The <coherence> element is the root element of the operational descriptor and includes the XSD and namespace declarations. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-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.

Operational Override File

The preferred approach for configuring operational settings is to use an operational override file.The schema for the override file and the operational deployment descriptor are the same except that all elements are optional. Any missing elements are loaded from the tangosol-coherence.xml operational deployment descriptor. The default name for the override file is tangosol-coherence-override.xml. At run time, this file must be found in the classpath before the coherence.jar library.

Additional override files can be configured using the xml-override attribute within the <coherence> element. This allows for additional fine tuning between similar deployment environments such as staging and production. For an example of this feature, see the tangosol-coherence-override-eval.xml, tangosol-coherence-override-dev.xml, and tangosol-coherence-override-prod.xml files within coherence.jar. See Operational Configuration Attribute Reference.

Operational Configuration Element Reference

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

access-controller

Used in: security-config.

Description

The access-controller element contains the configuration information for the class that implements the com.tangosol.net.security.AccessController interface, which is used by the Coherence Security Framework to check access right and encrypt/decrypt node-to-node communications.

Elements

Table A-1 describes the subelements of the access-controller element.

Table A-1 access-controller Subelements

Element Required/ Optional Description

<class-name>

Required

Specifies the name of a Java class that implements com.tangosol.net.security.AccessController interface, which is used by the security framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights. See Using an Access Controller in Securing Oracle Coherence. The default value is com.tangosol.net.security.DefaultController.

<init-params>

Optional

Contains one or more initialization parameter(s) for a class that implements the AccessController interface. For the default AccessController implementation the parameters are the paths to the key store file and permissions description file, specified as follows:

<init-params>
  <init-param id="1">
    <param-type>java.io.File</param-type>
    <param-value system-property="coherence.security.keystore">
       </param-value>
  </init-param>
  <init-param id="2">
    <param-type>java.io.File</param-type>
    <param-value system-property="coherence.security.permissions">
       </param-value>
  </init-param>
</init-params>

The preconfigured system property overrides based on the default AccessController implementation and the default parameters as specified above are coherence.security.keystore and coherence.security.permissions. See init-param.

active-active

Description

The active-active element specifies an active-active topology where there are one or more active participants that send data to other active participants. The active participants never re-sends the data. For example:

<active-active>
   <name>MyTopology</name>
   <active>ClusterA</active>
   <active>ClusterB</active>
</active-active>

Elements

Table A-2 describes the subelements of the active-active element.

Table A-2 active-active Subelements

Element Required/ Optional Description

<name>

Required

Specifies a user-defined name for the topology. The name is used to refer to this topology.

<active>

Required

Specifies the name of an active participant in the topology. Multiple active participants can be defined.

<interceptor>

Optional

Specifies the name of a custom participant that is implemented as an interceptor for federated change events. An interceptor participant is a receiver participant only.

active-passive

Description

The active-passive element specifies an active-passive topology where there are one or more active participants that send data to other passive participants. The active participants never re-sends the data and the passive participants only receive data. For example:

<active-passive>
   <name>MyTopology</name>
   <active>ClusterA</active>
   <passive>ClusterB</passive> 
</active-passive>

Elements

Table A-3 describes the subelements of the active-passive element.

Table A-3 active-passive Subelements

Element Required/ Optional Description

<name>

Required

Specifies a user-defined name for the topology. The name is used to refer to this topology.

<active>

Required

Specifies the name of an active participant in the topology. Multiple active participants can be defined.

<passive>

Optional

Specifies the name of a passive participant in the topology. Multiple passive participants can be defined.

<interceptor>

Optional

Specifies the name of a custom participant that is implemented as an interceptor for federated change events. An interceptor participant is a receiver participant only.

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. Many elements make use of the address-provider element.

The address-provider Element for Well Known Addresses

Within the well-known-addresses element, use the address-provider element to specify an address factory that implements the com.tangosol.net.AddressProvider interface. The interface offers a programmatic way to define Well Known Addresses (WKA) members. See Using Well Known Addresses. The following example demonstrates using the address-provider element within the well-known-addresses element:

<unicast-listener>
   <well-known-addresses>
      <address-provider>
         <class-name>package.MyAddressProvider</class-name>
      </address-provider>
   </well-known-addresses>
</unicast-listener>

The address-provider Element for Socket Addresses

Within the address-providers element, use the address-provider element to specify a socket address or an address factory that implements the com.tangosol.net.AddressProvider interface. The address provider definitions are referenced by TCP/IP acceptors and TCP/IP initiators which are used to setup Coherence*Extend. A TCP/IP acceptor is also available for memcached clients.

The tcp-acceptor, memcached-acceptor, remote-addresses, and name-service-addresses elements in the cache configuration file reference address provider definitions using the specified id attribute value. The following example demonstrates defining address provider definitions within the <address-providers> element.

<address-providers>
   <address-provider id="ap1">
      <class-name>package.MyAddressProvider</class-name>
   </address-provider>
   <address-provider id="ap2">
      <socket-address>
         <address>192.168.1.3</address>
         <port>9999</port>
      </socket-address>
   </address-provider>
   <address-provider id="ap3">
      <socket-address>
         <address>192.168.1.4</address>
         <port>9999</port>
      </socket-address>
   </address-provider>
</address-providers>

The address-provider Element for Persistence

Within the address-providers element, use the address-provider element to specify an address or an address factory that implements the com.tangosol.net.AddressProvider interface. The address provider definitions are used when configuring cache persistence. The addresses represent the storage-enabled hosts in the cluster that are required to recover orphaned partition from the persistent storage, or assign empty partitions if the persistent storage is unavailable or lost. For example:

<address-providers>
   <address-provider id="persistence-host-list">
      <address>HOST_NAME/address>
      <address>HOST_NAME</address>
   </address-provider>
</address-providers>

The address-provider Element for Federation

Within the name-service-addresses element, use the address-provider element to specify an address or an address factory that implements the com.tangosol.net.AddressProvider interface. The address provider definitions are used when configuring cluster federation. The addresses represent cluster nodes in the remote cluster participant.

Elements

Table A-4 describes the subelements of the address-provider element.

Table A-4 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 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

Specifies initialization parameters which are accessible by implementations that include a public constructor with a matching signature. Initialization parameters can be specified when using 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 should only be used when defining socket addresses for a TCP/IP acceptor. This element cannot be used if an address provider implementation is defined using the <class-name> or <class-factory-name> element.

<address>

Optional

Specifies an IP address or DNS name. In the case of a bind address, the address can be represented in CIDR format as a subnet and mask (for example, 192.168.1.0/24), allowing runtime resolution against available local IPs. The bind address can also be an external NAT address that routes to a local address; however, both addresses must use the same port.

address-providers

Used in: cluster-config.

Description

The address-providers element contains the declarative data for each address provider.

Elements

Table A-5 describes the subelements of the address-providers element.

Table A-5 address-providers Subelements

Element Required/ Optional Description

<address-provider>

Optional

Specifies either socket address information or an implementation of the com.tangosol.net.AddressProvider interface. Multiple address-provider elements can be specified.

authorized-hosts

Used in: cluster-config.

Description

If specified, restricts cluster membership to the cluster nodes specified in the collection of unicast addresses, or address range. The unicast address is the address value from the authorized cluster nodes' unicast-listener element. Any number of host-address and host-range elements may be specified.

Elements

Table A-6 describes the subelements of the authorized-hosts element.

Table A-6 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 is 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 is 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-filter>

Optional

Specifies class configuration information for a com.tangosol.util.Filter implementation that is used by the cluster to determine whether to accept a new cluster member. The evaluate() method is passed the java.net.InetAddress of the client. Implementations should return true to allow the new member to join the cluster.

cache-factory-builder-config

Used in: coherence.

Description

The cache-factory-builder-config element contains the configuration information for constructing an instance of the com.tangosol.net.CacheFactoryBuilder interface. The default implementation is the com.tangosol.net.DefaultCacheFactoryBuilder class, which can be extended in advanced use-cases to provide further domain-specific logic for creating and managing ConfigurableCacheFactory instances.

A custom CacheFactoryBuilder implementation is used to build and manage multiple cache factory configurations across multiple class loaders. This is an advanced use case that allows applications that are scoped by different class loaders to use separate cache configuration files (as is the case with JavaEE and OSGI). For example, the following code uses a custom ConfigurableCacheFactory implementation from two classloaders.

CacheFactoryBuilder cfb = CacheFactory.getCacheFactoryBuilder();

//load the first configuration
cfb.getConfigurableCacheFactory("example-config.xml", loader0);
CacheFactory.ensureCluster();
NamedCache cache = CacheFactory.getCache("dist-example");

//load the second configuration
cfb.getConfigurableCacheFactory("example-config1.xml", loader1);
CacheFactory.ensureCluster();
NamedCache cache1 = CacheFactory.getCache("dist-example1");

Elements

Table A-7 describes the subelements of the cache-factory-builder-config element.

Table A-7 cache-factory-builder-config Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the name of a Java class that implements the com.tagosol.net.CacheFactoryBuilder interface. The default value is com.tangosol.net.DefaultCacheFactoryBuilder.

<init-params>

Optional

Contains initialization parameters for the cache factory builder implementation.

<scope-resolver>

Optional

Specifies the configuration information for a class that implements the com.tangosol.net.ScopeResolver interface. A scope resolver implementation provides the ability to modify the scope name for a given ConfigurableCacheFactory at run time to enforce (or disable) isolation between applications running in the same cluster. The custom scope resolver implementation is specified within an <class-name> subelement.

See the <scope-name> subelement of the <cache-config> element for details on specifying a scope name within a cache configuration file.

callback-handler

Used in: security-config.

Table A-8 describes the subelements of the callback-handler element.

Table A-8 callback-handler Subelement

Element Required/ Optional Description

<class-name>

Required

Specifies the name of a Java class that provides the implementation for the javax.security.auth.callback.CallbackHandler interface.

<init-params>

Optional

Contains one or more initialization parameter(s) for a CallbackHandler implementation.

central-replication

Description

The central-replication element specifies a central-replication topology where one or more leaf participants send data to the hub participant, and the hub participant re-sends (repeats) the data to all the other leaf participants. Any change that originate at the hub-participant are sent to all the leaf participants.

The following example demonstrates a custom topology:

<central-replication>
   <name>central</name>
   <hub>ClusterA</hub>
   <leaf>ClusterB</leaf>
   <leaf>ClusterC</leaf>
</central-replication>

Elements

Table A-9 describes the subelements of the central-replication element.

Table A-9 central-replication Subelements

Element Required/ Optional Description

<name>

Required

Specifies a user-defined name for the topology. The name is used to refer to this topology.

<hub>

Required

Specifies the name of the hub participant in the topology.

<leaf>

Required

Specifies the name of a leaf participant in the topology. Multiple leaf participants can be defined.

<interceptor>

Optional

Specifies the name of custom participant that is implemented as an interceptor for federated change events. An interceptor participant is a receiver participant only.

cluster-config

Used in: coherence.

Description

Contains the cluster configuration information, including communication and service parameters.

Elements

Table A-10 describes the subelements of the cluster-config element.

Table A-10 cluster-config Subelements

Element Required/ Optional Description

<member-identity>

Optional

Specifies detailed identity information that is useful for defining the location and role of the cluster member.

<unicast-listener>

Required

Specifies the configuration information for the unicast listener, used for receiving point-to-point network communications.

<multicast-listener>

Required

Specifies the configuration information for the multicast listener, used for receiving point-to-multipoint network communications.

<tcp-ring-listener>

Required

Specifies configuration information for the TCP ring listener, used to death detection.

<shutdown-listener>

Required

Specifies the action to take upon receiving an external shutdown request.

<service-guardian>

Required

Specifies the configuration information for the service guardians, used for detecting and resolving service deadlock.

<packet-speaker>

Required

Specifies configuration information for the packet speaker, used for network data transmission.

<packet-publisher>

Required

Specifies configuration information for the packet publisher, used for managing network data transmission.

<incoming-message-handler>

Required

Specifies configuration information for the incoming message handler, used for dispatching incoming cluster communications.

<outgoing-message-handler>

Required

Specifies configuration information for the outgoing message handler, used for dispatching outgoing cluster communications.

<authorized-hosts>

Optional

Specifies the hosts which are allowed to join the cluster.

<services>

Required

Specifies the declarative data for all available Coherence services.

<filters>

Optional

Specifies data transformation filters, which can perform custom transformations on data being transferred between cluster nodes.

<serializers>

Optional

Specifies any number of serializer class configurations that implement com.tangosol.io.Serializer.

<persistence-environments>

Optional

Specifies the declarative data for each persistence environment.

<address-providers>

Optional

Specifies any number of address provider definitions.

<socket-providers>

Required

Contains socket provider definitions.

<cluster-quorum-policy>

Optional

Contains the configuration information for the quorum-based action policy for the Cluster service.

<journaling-config>

Optional

Specifies configuration for the journaling subsystem.

<storage-authorizers>

Optional

Contains the declarative data for each storage access authorizer implementation.

password-providers

Optional

Contains password provider definitions.

cluster-quorum-policy

Used in: cluster-config.

Description

The cluster-quorum-policy element contains quorum policy settings for the Cluster service.

Element

Table A-11 describes the subelements of the cluster-quorum-policy element.

Table A-11 cluster-quorum-policy-scheme Subelements

Element Required/ Optional Description
<timeout-site-quorum>

Optional

Specifies the minimum number of sites that must remain in order to terminate one or more cluster members due to a detected network timeout, irrespective of the root cause. The value must be a nonnegative integer.

Use the role attribute to specify this value for cluster members of a given role (as defined in the <role-name> element). For example:

<timeout-site-quorum role="Server">2
</timeout-site-quorum>
<timeout-machine-quorum>

Optional

Specifies the minimum number of machines that must remain in order to terminate one or more cluster members due to a detected network timeout, irrespective of the root cause. The value must be a nonnegative integer.

Use the role attribute to specify this value for cluster members of a given role (as defined in the <role-name> element). For example:

<timeout-machine-quorum role="Server">4
</timeout-machine-quorum>

<timeout-survivor-quorum>

Optional

Specifies the minimum number of cluster members that must remain to terminate one or more cluster members due to a detected network timeout, irrespective of the root cause. The value must be a nonnegative integer.

Use the role attribute to specify this value for cluster members of a given role (as defined in the <role-name> element). For example:

<timeout-survivor-quorum role="Server">50
</timeout-survivor-quorum>

<class-name>

Optional

Specifies a class that provides custom quorum policies. This element cannot be used with any of the cluster quorums 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 any of the cluster quorums 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. In addition, initialization parameters can be specified using the <init-params> element.

coherence

root element

Description

The coherence element is the root element of the operational deployment descriptor tangosol-coherence.xml.

Elements

Table A-12 describes the subelements of the coherence element.

Table A-12 coherence Subelements

Element Required/ Optional Description

<cluster-config>

Required

Contains the cluster configuration information. This element is where most communication and service parameters are defined.

<logging-config>

Required

Contains the configuration information for the logging facility.

<configurable-cache-factory-config>

Required

Contains configuration information for the configurable cache factory, which controls from where and how the cache configuration settings are loaded.

<cache-factory-builder-config>

Required

Contains the configuration information for a cache factory builder, which allows building and managing multiple cache factory configurations across multiple class loaders.

<management-config>

Required

Contains the configuration information for the coherence management framework. See Configuring JMX Management in Managing Oracle Coherence.

<security-config>

Optional

Contains the configuration information for the Coherence Security Framework.

<license-config>

Optional

Contains the edition and operational mode configuration.

<federation-config>

Optional

Contains the federation configuration information that is used to synchronize clusters.

configurable-cache-factory-config

Used in: coherence.

Description

The configurable-cache-factory-config element contains the configuration information for constructing an instance of the com.tangosol.net.ConfigurableCacheFactory interface. The default implementation is the com.tangosol.net.ExtensibleConfigurableCacheFactory class.

Using a custom ConfigurableCacheFactory implementation is an advanced use case and is typically used to allow applications that are scoped by different class loaders to use separate cache configuration files (as is the case with JavaEE and OSGI).

The following example loads two configuration files which contain different cache definitions and use different ClassLoaders.

//load the first configuration and use a cache

ConfigurableCacheFactory  eccf= new
   ExtensibleConfigurableCacheFactory("example-config.xml", loader0);
NamedCache cache = eccf.ensureCache("dist-example", loader0);
cache.put(key, value);

//load the second cache configuration and use a cache

ConfigurableCacheFactory  eccf1= new
   ExtensibleConfigurableCacheFactory("example-config1.xml", loader1);
NamedCache cache1 = eccf1.ensureCache("dist-example1", loader1);
cache1.put(key, value);

Note:

This example requires each cache definition to use a different service name; otherwise, an exception is thrown indicating that the service was started by a factory with a different configuration descriptor.

Elements

Table A-13 describes the subelements of the configurable-cache-factory-config element.

Table A-13 configurable-cache-factory-config Subelements

Element Required/ Optional Description

<class-name>

Required

Specifies the name of a Java class that implements the com.tangosol.net.ConfigurableCacheFactory interface. The default value is com.tangosol.net.ExtensibleConfigurableCacheFactory.

The preconfigured system property override is coherence.cachefactory.

<init-params>

Optional

Contains initialization parameters for the cache configuration factory implementation. For the default cache configuration factory class, a single parameter is used as follows:

<init-param>
  <param-type>java.lang.String</param-type>
  <param-value>coherence-cache-config.xml</param-value>
</init-param>

Unless an absolute or relative path is specified, such as with ./path/to/config.xml, the application's classpath is used to find the specified descriptor.

The preconfigured system property override is coherence.cacheconfig.

custom-topology

Description

The custom-topology element is a free-form topology that consists of a group list. A group consist of participants with specific roles: sender, repeater, or receiver. Only sender and repeater participants can send or forward changes to other participants in the group.

Elements

Table A-14 describes the subelements of the custom-topology element.

Table A-14 custom-topology Subelements

Element Required/ Optional Description

<name>

Required

Specifies a user-defined name for the topology. The name is used to refer to this topology.

<groups>

Required

Specifies the configuration information for any number of group definitions.

federation-config

Used in: coherence.

Description

The federation-config element contains the federation configuration information that is used synchronize clusters. The configuration includes defining federation participants and defining a synchronization topology.

Elements

Table A-15 describes the subelements of the federation-config element.

Table A-15 federation-config Subelements

Element Required/ Optional Description

<participants>

Optional

Specifies any number of remote coherence clusters that are participating in the federation.

<topology-definitions>

Optional

Specifies the topology configuration information that is used to synchronize clusters.

filter

Used in: filters.

Description

Data transformation filters can be used by a service to apply a custom transformation on data being transferred between cluster nodes. This can be used for instance to compress network traffic. See the <filter-class> element for more information.

Implementation

Data transformation filters are implementations of the com.tangosol.util.WrapperStreamFactory interface.

Note:

Data transformation filters are not related to com.tangosol.util.Filter, which is part of the Coherence API for querying caches.

Elements

Table A-16 describes the subelements of each filter element.

Table A-16 filter Subelements

Element Required/ Optional Description

<filter-name>

Required

Specifies the canonical name of the filter. This name is unique within the cluster. For example: gzip.

<filter-class>

Required

Specifies the class name of the filter implementation. This class must have a zero-parameter public constructor and must implement the com.tangosol.util.WrapperStreamFactory interface.

<init-params>

Optional

Specifies initialization parameters for configuring filters. For example when using a com.tangosol.net.CompressionFilter the parameters are specified as follows:

<init-param>
  <param-name>strategy</param-name>
  <param-value>gzip</param-value>
</init-param>
<init-param>
  <param-name>level</param-name>
  <param-value>default</param-value>
</init-param>

filters

Used in cluster-config.

Description

The filters element contains the declarative data for each filter.

Elements

Table A-17 describes the subelements of the filters element.

Table A-17 filters Subelements

Element Required/ Optional Description

<filter>

Optional

The filter element contains the declarative data of a particular filter.

flashjournal-manager

Used in: journaling-config.

Description

The <flashjournal-manager> element contains the configuration for a flash journal resources manager, which manages I/O for temporary journal-based files to a solid state device.

Elements

Table A-18 describes the subelements of the flashjournal-manager element.

Table A-18 flashjournal-manager Subelements

Element Required/ Optional Description

<minimum-load-factor>

Optional

Specifies the factor of live data below which a journal file is eligible for compaction (garbage collection).

<maximum-value-size>

Optional

Specifies the maximum size, in bytes, of binary values that are to be stored in the flash journal. The value cannot exceed 64MB. The default value is 64MB.

Note:

When <maximum-file-size> / 2 < 64M, <maximum-value-size> is limited by <maximum-file-size> / 2.

<maximum-file-size>

Optional

Specifies the maximum file size of the underlying journal files. The value must be a power of two and a multiple of the block size. The value must be between 1MB and 4GB and must be large enough so that a file is capable of storing at least 2 values. The default value is 2GB.

Note:

  • <maximum-file-size> and <maximum-size> are mutually exclusive.
    • When <maximum-file-size> is specified, <maximum-size> = <maximum-file-size> * 512.
    • When <maximum-size> is specified, <maximum-file-size> = <maximum-size> / 512.
    • If <maximum-file-size> is smaller than 1M, it is set to 1M.
  • When <maximum-file-size> / 2 < 64M, <maximum-value-size> is limited by <maximum-file-size> / 2.

<collector-timeout>

Optional

Specifies the amount of time that the journal collector can remain unresponsive prior to considering it timed out. The minimum timeout is 30s. Legal values are strings representing time intervals. The Default value is 10m.

<maximum-size>

Optional

Specifies the maximum capacity for the journal as a memory size. A value of 0 disables flash storage and causes journaling to use only RAM storage and not overflow to flash storage.

The preconfigured system property override is coherence.flashjournal.size.

Note:

<maximum-file-size> and <maximum-size> are mutually exclusive.

  • When <maximum-file-size> is specified, <maximum-size> = <maximum-file-size> * 512.
  • When <maximum-size> is specified, <maximum-file-size> = <maximum-size> / 512.
  • If <maximum-file-size> is smaller than 1M, it is set to 1M.

<block-size>

Optional

Specifies the size of the write buffers in which writes to an underlying disk file occur. The size should match or be a multiple of the physical device's optimal block size and must be a power of two. The value must be between 4KB and 1MB. The default value is 256KB.

<maximum-pool-size>

Optional

Specifies the size, in bytes, for the buffer pool. The size does not limit the number of buffers that can be allocated or that can exist at any point in time. The size only determines the amount of buffers that are recycled. The pools size cannot exceed 1GB. The default value is 16MB.

<directory>

Optional

Specifies the directory where the journal files should be placed. The directory must exist and is not created at run time. If the directory does not exist or is not specified, the JVM/operating system default temporary directory is used. The suggested location is a local flash (SSD) drive.

Specifying a directory that is located on a drive which is shared by other applications or system operations increases the potential for unplanned space usage. Use a directory location on a non-shared disk partition to ensure a more predictable environment.

The preconfigured system property override is coherence.flashjournal.dir.

<async-limit>

Optional

Specifies the maximum size, in bytes, of the backlog. The backlog is the amount of data that has yet to be persisted. Client threads are blocked if the configured limit is exceeded and remain blocked until the backlog recedes below the limit. This helps prevent out-of-memory conditions. Note: The maximum amount of memory used by the backlog is at least twice the configured amount, since the data is in binary form and rendered to the write-behind buffers. The value must be between 4KB and 1GB. The default value is 16MB.

<tmp-purge-delay>

Optional

Specifies the amount of time to wait before a temporary file that is used by the Journaling subsystem is eligible for removal. The delay begins after the file is last used. The default value is 2 hours.

<high-journal-size>

Optional

Specifies the soft limit, in bytes, on the journal size or a percentage of the flash journal capacity. The soft limit allows the compaction (garbage collection) thread to tune itself to remove stale values and keep the journal within the soft limit. This is not a hard limit and the journal can still grow up to the maximum file count (512). The default value is 11GB.

The preconfigured system property override is coherence.flashjournal.highjournalsize.

<writer-timeout>

Optional

Specifies the amount of time that the flash journal writer can remain unresponsive prior to considering it timed out. The minimum timeout is 30s. Legal values are strings representing time intervals. The Default value is 8h.

If a write fails (after the writer-timeout values is reached), then the journal becomes read-only until the member is restarted. When the write backlog maximum is reached (as defined by the async-limit value), the journal responds to subsequent store requests with an exception either until the write is resolved or indefinitely as the writer-timeout is surpassed.

flow-control

Used in: packet-delivery.

Description

The flow-control element contains configuration information related to packet throttling and remote GC detection.

Elements

Table A-19 describes the subelements of the flow-control element.

Table A-19 flow-control Subelements

Element Required/ Optional Description

<enabled>

Optional

Specifies if flow control is enabled. Valid values are true or false. The default value is true

<pause-detection>

Optional

Defines the number of packets that are resent to an unresponsive cluster node after which the node is assumed to be paused.

<outstanding-packets>

Optional

Defines the number of unconfirmed packets that are sent to a cluster node before packets addressed to that node are deferred.

group

Used in: groups.

Description

The group element specifies a set of participants with a well-defined role. All the participants can receive data irrespective of their roles. The following roles are available:

  • sender – A sender participant only sends data that originated in its local cluster.

  • repeater – A repeater participant can send data that originated locally as well as data that it received from other participants.

  • receiver – A receiver participant never sends data.

The following example demonstrates a custom topology:

<custom-topology>
   <name>custom</name>
   <groups>
      <group>
         <sender>ClusterA</sender>
         <sender>ClusterB</sender>
      </group>
      <group>
         <repeater>ClusterA</repeater>
         <receiver>ClusterC</receiver>
      </group>
   </groups>
</custom-topology>

Elements

Table A-20 describes the subelements of the group element.

Table A-20 group Subelements

Element Required/ Optional Description

<sender>

Optional

Specifies a participant that acts as a sender. Multiple sender participants can be defined in a group.

<repeater>

Optional

Specifies a participant that acts as a repeater. Multiple repeater participants can be defined in a group.

<receiver>

Optional

Specifies a participant that acts as a receiver. Multiple receiver participants can be defined in a group.

groups

Used in: custom-topology.

Description

The groups element contains the configuration information for any number of group definitions.

Elements

Table A-21 describes the subelements of the groups element.

Table A-21 groups Subelements

Element Required/ Optional Description

<group>

Required

Specifies a groups of participants with well-defined roles in the topology. Any number of groups can be defined.

host-range

Used in: authorized-hosts.

Description

Specifies a range of unicast addresses of nodes which are allowed to join the cluster.

Elements

Table A-22 describes the subelements of each host-range element.

Table A-22 host-range Subelements

Element Required/ Optional Description

<from-address>

Required

Specifies the starting IP address for a range of host addresses. For example: 198.168.1.1.

<to-address>

Required

Specifies to-address element specifies the ending IP address (inclusive) for a range of hosts. For example: 198.168.2.255.

hub-spoke

Description

The hub-spoke element specifies a hub and spoke topology where one or more spoke participants only receive data. The hub participant sends data to all the spoke participants.

The following example demonstrates a hub and spoke topology:

<hub-spoke>
   <name>hub</name>
   <hub>ClusterA</hub>
   <spoke>ClusterB</spoke>
   <spoke>ClusterC</spoke>
</hub-spoke>

Elements

Table A-23 describes the subelements of the hub-spoke element.

Table A-23 hub-spoke Subelements

Element Required/ Optional Description

<name>

Required

Specifies a user-defined name for the topology. The name is used to refer to this topology.

<hub>

Required

Specifies the name of the hub participant in the topology.

<spoke>

Required

Specifies the name of a spoke participant in the topology. Multiple spoke participants can be defined.

<interceptor>

Optional

Specifies the name of custom participant that is implemented as an interceptor for federated change events. An interceptor participant is a receiver participant only.

identity-asserter

Used in: security-config.

Description

The <identity-asserter> element contains the configuration information for a class that implements the com.tangosol.net.security.IdentityAsserter interface. The class is called to validate an identity token to establish a user's identity and is used on a Coherence*Extend proxy server. The identity asserter is used with an identity transformer (used on a Coherence*Extend client) to ensure that only valid clients are allowed to connect to an extend proxy.

Elements

Table A-24 describes the subelements of the <identity-asserter> element.

Table A-24 identity-asserter Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies a class that implements com.tangosol.net.security.IdentityAsserter. This element cannot be used with the <class-factory-name> element.

<class-factory-name>

Optional

Specifies a factory class for creating asserter instances. The instances must implement com.tangosol.net.security.IdentityAsserter. This element cannot be used with 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 asserter implementation.

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 A-25 describes the subelements of the identity-manager element.

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

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

<password-provider>

Optional

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

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

identity-transformer

Used in: security-config.

Description

The <identity-transformer> element contains the configuration information for a class that implements the com.tangosol.net.security.IdentityTransformer interface. The class is called to transform a Subject (Principal in .NET) to a token that asserts identity and is used on a Coherence*Extend client. The identity transformer is used with an identity asserter (used on a Coherence*Extend proxy server) to ensure that only valid clients are allowed to connect to an extend proxy.

Elements

Table A-26 describes the subelements of the <identity-transformer> element.

Table A-26 identity-transformer Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies a class that implements com.tangosol.net.security.IdentityTransformer. This element cannot be used with the <class-factory-name> element.

<class-factory-name>

Optional

Specifies a factory class for creating asserter instances. The instances must implement com.tangosol.net.security.IdentityTransformer. This element cannot be used with 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 transformer implementation.

incoming-message-handler

Used in: cluster-config.

Description

The incoming-message-handler assembles packets into logical messages and dispatches them to the appropriate Coherence service for processing.

Elements

Table A-27 describes the subelements of the incoming-message-handler element.

Table A-27 incoming-message-handler Subelements

Element Required/ Optional Description

<maximum-time-variance>

Required

Specifies the maximum time variance between sending and receiving broadcast Messages when trying to determine the difference between a new cluster Member's system time and the cluster time. The smaller the variance, the more certain one can be that the cluster time is closer between multiple systems running in the cluster; however, the process of joining the cluster is extended until an exchange of Messages can occur within the specified variance. Normally, a value as small as 20 milliseconds is sufficient, but with heavily loaded clusters and multiple network hops a larger value may be necessary. The default value is 16.

<use-nack-packets>

Required

Specifies whether the packet receiver uses negative acknowledgments (packet requests) to pro-actively respond to known missing packets. See notification-queueing. Legal values are true or false. The default value is true.

<priority>

Required

Specifies a priority of the incoming message handler execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 7.

init-param

Used in: init-params.

Description

Defines an initialization parameter. Any number of init-param elements may be specified.

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 A-28 describes the subelements of the init-param element.

Table A-28 init-param Subelement

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. See Initialization Parameter Settings.

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

Elements

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

Table A-29 init-params Subelement

Element Required/ Optional Description

<init-param>

Optional

Defines an individual initialization parameter.

instance

Used in: service-failure-policy, scope-resolver, partition-assignment-strategy, custom-archiver, and persistence-environment.

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 A-30 describes the subelements of the instance element.

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

Specifies initialization parameters which are accessible by implementations that include a public constructor with a matching signature. Initialization parameters can be specified when using both the <class-name> element and the <class-factory-name> element.

interceptor

Used in: interceptors

Description

The interceptor element defines the configuration associated with an event interceptor that is responsible for processing federation change records. Interceptors implements the com.tangosol.net.events.EventInterceptor interface for FederatedChangeEvent types. See Using Live Events.

Note:

Interceptors that are defined within a participant configuration are applied to all federated cache services that use the participant. To restrict the interceptor to a specific federated cache service, define the interceptor within a federated-scheme in the cache configuration file.

Elements

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

Used in: participant

Description

The interceptors element contains any number of event interceptor definitions.

Elements

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

Table A-32 interceptors Subelements

Element Required/ Optional Description

<interceptor>

Optional

Specifies an event interceptor implementation.

journaling-config

Used in: cluster-config.

Description

The <journaling-config> element contains the configuration for the resource managers that are responsible for storing data in a binary format to flash and RAM memory.

Elements

Table A-30 describes the subelements of the journaling-config element.

Table A-33 journaling-config Subelements

Element Required/ Optional Description

<ramjournal-manager>

Required

Specifies the RAM Journal Resource Manager's configuration.

<flashjournal-manager>

Required

Specifies the Flash Journal Resource Manager's configuration.

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 A-34 describes the subelements of the key-store element.

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

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

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

license-config

Used in: coherence.

Description

The license-config element contains the details of the license that this member uses.

Elements

Table A-35 describes the subelements of the license-config element.

Table A-35 license-config Subelements

Element Required/ Optional Description

<edition-name>

Optional

Specifies the product edition that the member uses. Valid values are: GE (Grid Edition), EE (Enterprise Edition), SE (Standard Edition), RTC (Real-Time Client), DC (Data Client). The default value is GE.

Note: The edition switches no longer enforce license restrictions. Do not change the default setting (GE).

<license-mode>

Optional

Specifies whether the product is being used in a development or production mode. Valid values are prod (Production), and dev (Development). Note: This value cannot be overridden in tangosol-coherence-override.xml. It must be specified in tangosol-coherence.xml or (preferably) supplied as system property coherence.mode on the Java command line. The default value is dev.

logging-config

Used in: coherence.

Elements

The following table describes the subelements of the logging-config element.

Table A-36 logging-config Subelements

Element Required/ Optional Description

<destination>

Required

Specifies the output device used by the logging system. Legal values are:

  • stdout

  • stderr (default)

  • jdk

  • log4j

  • log4j2

  • slf4j

  • file name

If log4j is specified, the Log4j libraries must be in the classpath. In both cases, the appropriate logging configuration mechanism (system properties, property files, and so on) are necessary to configure the JDK/Log4j logging libraries.

The preconfigured system property override is coherence.log.

<logger-name>

Optional

Specifies a logger name within chosen logging system that logs Coherence related messages. This value is only used by the JDK and log4j logging systems. The default value is Coherence.

The preconfigured system property override is coherence.log.logger.

<severity-level>

Required

Specifies which logged messages are emitted to the log destination. The legal values are -1 to 9. No messages are emitted if -1 is specified. More log messages are emitted as the log level is increased.

The preconfigured system property override is coherence.log.level.

<message-format>

Required

Specifies how messages that have a logging level specified are formatted before passing them to the log destination. The format can include static text and any of the following replaceable parameters: {date}, {uptime}, {product}, {version}, {level}, {thread}, {member}, {location}, {role}, {text}, and {ecid}. The default value is:

{date}/{uptime} {product} {version} &lt;{level}&gt; (thread={thread}, member={member}): {text}

<character-limit>

Required

Specifies the maximum number of characters that the logger daemon processes from the message queue before discarding all remaining messages in the queue. All messages that are discarded are summarized by the logging system with a single log entry that details the number of messages that were discarded and their total size. Legal values are positive integers or 0. Zero implies no limit. The default value in production mode is 1048576 and 2147483647 in development mode.

The preconfigured system property override is coherence.log.limit.

management-config

Used in: coherence.

Elements

Table A-37 describes the subelements of the management-config element.

Table A-37 management-config Subelements

Element Optional/ Required Description

<managed-nodes>

Optional

Specifies whether a cluster node's JVM has an [in-process] MBean server and if so, whether this node allows management of other nodes' managed objects. Legal values are:

  • none – No MBean server is instantiated on this cluster node.

  • local-only – Manage only MBeans which are local to this cluster node (that is, within the same JVM).

  • remote-only – Manage MBeans on other remotely manageable cluster nodes. See <allowed-remote-management> subelement.

  • all – Manage both local and remotely manageable cluster nodes. See <allowed-remote-management> subelement.

  • dynamic – (default) Allow this node to automatically host an MBean server and manage all MBeans.

The preconfigured system property override is coherence.management.

<http-managed-nodes>

Optional

Specifies whether a cluster node's JVM has an [in-process] HTTP management server.

The HTTP management server uses the Management service to fulfill its requests and is therefore affected by the other management settings such as <managed-nodes>. For example, if <managed-nodes> is set to none, then the HTTP management server does not start. If <managed-nodes> is set to local-only, then the HTTP management server exposes attributes and operations that are limited to local MBeans.

Legal values are:

  • all – Instantiate an HTTP management server on this node.

  • inherit – Instantiate an HTTP management server on this cluster node if an MBean server will be instantiated on this node. See <managed-nodes> subelement.

  • none – (default) No HTTP management server is instantiated on this cluster node.

The preconfigured system property override is coherence.management.http.

<allow-remote-management>

Optional

Specifies whether this cluster node exposes its managed objects to remote MBean server(s). Legal values are: true or false. The default value is true.

The preconfigured system property override is coherence.management.remote.

<refresh-policy>

Optional

Specifies the method which is used to refresh remote management information. Legal values are: refresh-ahead, refresh-behind or refresh-expired. The default value is refresh-ahead.

The preconfigured system property override is coherence.management.refresh.policy

<refresh-expiry>

Optional

Specifies the time interval (in milliseconds) after which a remote MBean information is invalidated on the management node. Legal values are strings representing time intervals. The default value is 1s.

The preconfigured system property override is coherence.management.refresh.expiry

<refresh-timeout>

Optional

Specifies the duration which the management node waits for a response from a remote node when refreshing MBean information. This value must be less than the refresh-expiry interval. Legal values are strings representing time intervals. The default value is 250ms.

The preconfigured system property override is coherence.management.refresh.timeout

<read-only>

Optional

Specifies whether the managed objects exposed by this cluster node allow operations that modify run-time attributes. Legal values are: true or false. The default value is false.

The preconfigured system property override is coherence.management.readonly.

<default-domain-name>

Optional

Specifies the domain name of an existing MBean server that is used to register MBeans exposed by the Coherence management framework. This element is used only if a cluster member has management enabled and the MBean server is located in the same process as the cluster member. If a value is not specified, the first existing MBean server is used. The element should only be used to identify an existing MBean server.

This element is also used when implementing the MBeanServerFinder interface. See the <server-factory> element below.

<service-name>

Optional

Specifies the name of the Invocation Service used for remote management. This element is used only if allow-remote-management is set to true.

<server-factory>

Optional

Contains the configuration information for an MBeanServer factory that implements the com.tangosol.net.management.MBeanServerFinder interface, which is used to find an MBean server that is used by the Coherence JMX framework to register new or locate existing MBeans. If a domain name is provided in the <default-domain-name> element, then it is used when instantiating the class. The class name is entered using the <class-name> subelement and supports initialization parameters using the <init-params> element.

<mbeans>

Optional

Contains a list of MBeans to be registered when a node joins the cluster.

<mbean-filter>

Optional

Contains the configuration information of a filter class that is used to filter MBeans before they are registered.

<reporter>

Optional

Contains the Reporter's configuration.

<extended-mbean-name>

Optional

Specifies whether global MBean names that are identified with a nodeId attribute are extended to identify the corresponding member name (if specified). Legal values are: true or false. The default value is false and indicates that the member name is not included in the Global MBean name.

The preconfigured system property override is coherence.management.extendedmbeanname.

mbean

Used in: mbeans.

Description

The mbean element contains a list of elements to be instantiated and registered with the Coherence management framework.

Elements

Table A-38 describes the subelements of the mbean element.

Table A-38 Subelements of mbean

Element Required/ Optional Description

<mbean-class>

Optional

Specifies the full class name of the standard MBean to instantiate and register with the Coherence management framework. The MBean class must be in the classpath to correctly instantiate.

This element cannot be used with the <mbean-factory> element or the <mbean-query> element.

<mbean-factory>

Optional

Specifies the name of a class factory used to obtain MBeans to register with the Coherence management framework. The factory class must be in the classpath to correctly instantiate. This element is used with the <mbean-accessor> element.

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

<mbean-query>

Optional

Specifies a JMX ObjectName query pattern. The query pattern is executed against a local MBean server and the resulting objects are registered with the Coherence management framework. This allows for a single point of consolidation of MBeans for the grid. For example, the following query includes all the MBeans under the java.lang domain in the Coherence management infrastructure.

<mbean-query>java.lang:*</mbean-query>

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

<mbean-server-domain>

Optional

Specifies the name of a default domain for the source MBean server. This is used to locate the MBean server where the mbean-query should be executed.

<mbean-accessor>

Optional

Specifies the method name on the factory class (specified by the <mbean-factory> element) that is used to instantiate the MBean.

<mbean-name>

Required

Specifies the JMX ObjectName prefix for the MBean that is registered with the Coherence management framework. The prefix should be a comma-delimited Key=Value pair. The Coherence MBean naming convention stipulates that the name should begin with a type/value pair (for example, type=Platform).

<local-only>

Optional

Specifies whether the MBean is visible across the cluster. Valid values are true or false. If set to true, the MBean is registered only with a local MBean server and is not accessible by other cluster nodes. If set to false, the nodeId=... key attribute is added to its name and the MBean is visible from any of the managing nodes (nodes that set the <managed-nodes> element to values of all or remote-only). The default value is false.

<enabled>

Optional

Specifies whether the MBean should be instantiated and registered on this instance. Valid values are true or false. The default value is false.

<extend-lifecycle>

Optional

Specifies whether the MBean should extend beyond the node connection life cycle. Valid values are true or false. If true, the MBean maintains the statistics and values across connections (coincides with the JVM life cycle). If false, the MBean is destroyed and re-created when a node is disconnected from the grid. The default value is false.

mbeans

Used in: management-config.

Description

The mbeans element is the root element for defining custom mbeans and is the root element of a custom mbean configuration file. It contains a list of mbean elements to be instantiated and registered with the Coherence management framework.

Elements

Table A-39 describes the subelements of the mbeans element.

Table A-39 Subelement of mbeans

Element Required/ Optional Description

<mbean>

Required

Specifies the MBean type, implementation, and ObjectName that are instantiated and registered with the Coherence management framework.

mbean-filter

Description

The mbean-filter element is used to specify a filter that evaluates MBean names before they are registered in the MBean server. The com.tangosol.net.management.ObjectNameExcludeFilter class is the default filter and is used to exclude MBeans from being registered based on their JMX object name using standard regex patterns. The list is entered as a list of names separated by any white space characters. The following MBeans are excluded by the out-of-box configuration:

<management-config>
   <mbean-filter>
      <class-name>com.tangosol.net.management.ObjectNameExcludeFilter</class-name>
      <init-params>
         <init-param>
            <param-type>string</param-type>
            <param-value system-property="coherence.management.exclude">
                 .*type=Service,name=Management,.*
                 .*type=Platform,Domain=java.lang,subType=ClassLoading,.*
                 .*type=Platform,Domain=java.lang,subType=Compilation,.*
                 .*type=Platform,Domain=java.lang,subType=MemoryManager,.*
                 .*type=Platform,Domain=java.lang,subType=Threading,.*
            </param-value>
         </init-param>
      </init-params>
   </mbean-filter>
</management-config>

Elements

Table A-60 describes the subelements of the mbean-filter element.

Table A-40 mbean-filter Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the name of a filter class for filtering mbeans.

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

<class-factory-name>

Optional

Specifies a factory class for creating filter instances.

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

member-identity

Used in: cluster-config.

The member-identity element contains detailed identity information that is useful for defining the location and role of the cluster member.

Elements

Table A-41 describes the subelements of the member-identity element.

Table A-41 member-identity Subelements

Element Required/ Optional Description

<cluster-name>

Optional

The cluster-name element contains the name of the cluster. To join the cluster, all members must specify the same cluster name. A cluster name should always be specified for production systems to prevent accidental cluster discovery among applications.

The preconfigured system property override is coherence.cluster.

<site-name>

Optional

The site-name element contains the name of the geographic site that the member is hosted at. For WAN clustering, this value identifies the datacenter within which the member is located. The site name can be used as the basis for intelligent routing, load balancing, and disaster recovery planning (that is, the explicit backing up of data on separate geographic sites). The site name also helps determine where to back up data when using distributed caching and the default partition assignment strategy. Lastly, the name is useful for displaying management information (for example, JMX) and interpreting log entries.

The preconfigured system property override is coherence.site.

<rack-name>

Optional

The rack-name element contains the name of the location within a geographic site that the member is hosted at and is often a cage, rack, or bladeframe identifier. The rack name can be used as the basis for intelligent routing, load balancing, and disaster recovery planning (that is, the explicit backing up of data on separate bladeframes). The rack name also helps determine where to back up data when using distributed caching and the default partition assignment strategy. Lastly, the name is useful for displaying management information (for example, JMX) and interpreting log entries.

The preconfigured system property override is coherence.rack.

<machine-name>

Optional

The machine-name element contains the name of the physical server that the member is hosted on. This is often the same name as the server identifies itself as (for example, its HOSTNAME, or its name as it appears in a DNS entry). If provided, the name is used as the basis for creating a ID, which in turn is used to guarantee that data are backed up on different computers to prevent single points of failure (SPOFs). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided.

The preconfigured system property override is coherence.machine.

<process-name>

Optional

The process-name element contains the name of the process (JVM) that the member is hosted on. This name makes it possible to easily differentiate among multiple JVMs running on the same computer. The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. Often, a single member exists per JVM, and in that situation this name would be redundant.

The preconfigured system property override is coherence.process.

<member-name>

Optional

The member-name element contains the name of the member itself. This name makes it possible to easily differentiate among members, such as when multiple members run on the same computer (or even within the same JVM). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided.

The preconfigured system property override is coherence.member.

<role-name>

Optional

The role-name element contains the name of the member role. This name allows an application to organize members into specialized roles, such as cache servers and cache clients. The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided.

The preconfigured system property override is coherence.role.

<priority>

Optional

The priority element specifies a priority of the corresponding member. The priority is used as the basis for determining tie-breakers between members. If a condition occurs in which one of two members are ejected from the cluster, and in the rare case that it is not possible to objectively determine which of the two is at fault and should be ejected, then the member with the lower priority is ejected. Valid values are from 1 to 10 where 10 is the highest priority.

The preconfigured system property override is coherence.priority.

multicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Multicast listener. This element is used to specify the address and port that a cluster uses for cluster wide and point-to-multipoint communications. All nodes in a cluster must use the same multicast address and port. If you are having difficulties establishing a cluster when using multicast, see Performing a Multicast Connectivity Test in Administering Oracle Coherence.

Multicast-Free Clustering

By default, Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, then the Well Known Addresses feature can be used to eliminate the need for multicast traffic. See the well-known-addresses element.

Elements

Table A-42 describes the subelements of the multicast-listener element.

Table A-42 multicast-listener Subelements

Element Required /Optional Description

<interface>

Optional

Specifies the IP or sub-net of the local network interface (NIC) used for multicast traffic. The NIC is automatically selected based on whether multicast is used solely for member discovery or if mutlicast is used for member discovery and data transmission.

<address>

Required

Specifies the multicast IP address on which a multicast socket listens or publishes. Legal values are from 224.0.0.0 to 239.255.255.255. The default value depends on the release and build level and typically follows the convention of 224.{major version}.{minor version}.{service}.

The preconfigured system property override is coherence.clusteraddress.

<port>

Required

Specifies the port on which the multicast socket listens or publishes. The port value is also used for WKA configurations. Legal values are from 1 to 65535. Select a cluster port that is outside of an operating system's ephemeral port range to avoid other software being randomly assigned the same port. A value between 1024 and 8999 is recommended. The default value is 7574.

The preconfigured system property override is coherence.clusterport.

<time-to-live>

Required

Specifies the time-to-live setting for the multicast. This determines the maximum number of "hops" a packet may traverse, where a hop is measured as a traversal from one network segment to another by using a router. Legal values are from 0 to 255. The default value is 4.

The preconfigured system property override is coherence.ttl.

<packet-buffer>

Required

Specifies how many incoming packets the operating system is requested to buffer. The value may be expressed either in terms of packets or bytes.

<priority>

Required

Specifies a priority of the multicast listener execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 8.

<join-timeout-milliseconds>

Required

Specifies the number of milliseconds that a new member waits without finding any evidence of a cluster before starting its own cluster and electing itself as the senior cluster member. Legal values are from 1000 to 1000000. The default value is 3000.

<multicast-threshold-percent>

Required

Specifies the threshold percentage value used to determine whether a packet is sent by using unicast or multicast. It is a percentage value and is in the range of 1% to 100%. In a cluster of "n" nodes, a particular node sending a packet to a set of other (that is, not counting self) destination nodes of size "d" (in the range of 0 to n-1), the packet is sent multicast if and only if the following both hold true:

  1. The packet is being sent over the network to multiple nodes, that is, (d > 1).

  2. The number of nodes is greater than the threshold, that is, (d > (n-1) * (threshold/100)).

    Setting this value to 1 allows the implementation to use multicast for basically all multi-point traffic.

    Setting it to 100 forces the implementation to use unicast for all multi-point traffic except for explicit broadcast traffic (for example, cluster heartbeat and discovery) because the 100% threshold is never exceeded. With the setting of 25 the implementation sends the packet using unicast if it is destined for less than one-fourth of all nodes, and send it using multicast if it is destined for the one-fourth or more of all nodes.

Legal values are from 1 to 100. The default value is 25.

Note: This element is only used if the well-known-addresses element is empty.

name-service-addresses

Used in: participant

Description

The use of name-service-addresses within participant is deprecated. Use remote-addresses instead.

The name-service-addresses element contains the address (IP, or DNS name, and port) of one or more name service TCP/IP acceptors. A federation service 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.

For details on using the name-service-address element as a subelement of tcp-initiator, see name-service-addresses in the cache configuration reference.

Elements

Table A-43 describes the subelements of the name-service-addresses element.

Table A-43 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.

notification-queueing

Used in: packet-publisher.

Description

The notification-queueing element is used to specify the timing of notifications packets sent to other cluster nodes. Notification packets are used to acknowledge the receipt of packets which require confirmation.

Elements

The following table describes the subelements of the notification-queuing element.

Table A-44 notification-queuing Subelements

Element Required/ Optional Description

<ack-delay- milliseconds>

Required

Specifies the maximum number of milliseconds that the packet publisher delays before sending an ACK packet. The ACK packet may be transmitted earlier if number of batched acknowledgments fills the ACK packet. This value should be substantially lower then the remote node's packet-delivery resend timeout, to allow ample time for the ACK to be received and processed by the remote node before the resend timeout expires. The default value is 16.

<nack-delay- milliseconds>

Required

Specifies the number of milliseconds that the packet publisher delays before sending a NACK packet. The default value is 1.

outgoing-message-handler

Used in: cluster-config.

Description

The outgoing-message-handler element contains the outgoing message handler (also known as a dispatcher) related configuration information.

Elements

Table A-45 describes the subelements of the outgoing-message-handler element.

Table A-45 outgoing-message-handler Subelement

Element Required/ Optional Description

<use-filters>

Optional

Specifies a list of <filter-name> elements to be used by this handler. See the <filter> element for detailed information on defining a filter.

outstanding-packets

Used in: flow-control.

Description

Defines the number of unconfirmed packets that are sent to a cluster node before packets addressed to that node are deferred. This helps to prevent the sender from flooding the recipient's network buffers.

Elements

Table A-46 describes the subelements of the outstanding-packets element.

Table A-46 outstanding-packets Subelements

Element Required/ Optional Description

<maximum-packets>

Optional

The maximum number of unconfirmed packets that are sent to a cluster node before packets addressed to that node are deferred. It is recommended that this value not be set below 256. The default value is 4096.

<minimum-packets>

Optional

The lower bound on the range for the number of unconfirmed packets that are sent to a cluster node before packets addressed to that node are deferred. It is recommended that this value not be set below 16. The default value is 64.

packet-buffer

Description

Specifies the size (in packets or bytes) of the operating system buffer for datagram sockets.

Elements

Table A-47 describes the subelements of the packet-buffer element.

Table A-47 packet-buffer Subelements

Element Required/ Optional Description

<maximum-packets>

Optional

For unicast-listener, multicast-listener and packet-publisher: Specifies the number of packets of packet-size that the datagram socket are asked to size itself to buffer. See SO_SNDBUF and SO_RCVBUF in Java Platform, Standard Edition API Specification. Actual buffer sizes may be smaller if the underlying socket implementation cannot support more than a certain size. The default values are 32 for publishing, 64 for multicast listening, and 1428 for unicast listening.

The <maximum-packets> element cannot be specified if the <size> element is specified.

<size>

Optional

Specifies the requested size of the underlying socket buffer in bytes rather than the number of packets.

The <size> element cannot be specified if the <maximum-packets> element is specified.

packet-bundling

Used in: packet-delivery.

Description

The packet-bundling element contains configuration information related to the bundling of multiple small packets into a single larger packet to reduce the load on the network switching infrastructure.

Elements

Table A-48 describes the subelements of the packet-bundling element.

Table A-48 packet-bundling Subelements

Element Required/Optional Description

<maximum-deferral- time>

Optional

The maximum amount of time to defer a packet while waiting for additional packets to bundle. A value of zero results in the algorithm not waiting, and only bundling the readily accessible packets. A value greater than zero causes some transmission deferral while waiting for additional packets to become available. This value is typically set below 250 microseconds to avoid a detrimental throughput impact. If the units are not specified, nanoseconds are assumed. The default value is 1us (microsecond).

<aggression-factor>

Optional

Specifies the aggressiveness of the packet deferral algorithm. Where as the maximum-deferral-time element defines the upper limit on the deferral time, the aggression-factor influences the average deferral time. The higher the aggression value, the longer the Publisher may wait for additional packets. The factor may be expressed as a real number, and often times values between 0.0 and 1.0 allows for high packet utilization while keeping latency to a minimum. The default value is 0.

packet-delivery

Used in: packet-publisher.

Description

Specifies timing and transmission rate parameters related to packet delivery.

Elements

Table A-49 describes the subelements of the packet-delivery element.

Table A-49 packet-delivery Subelements

Element Required/ Optional Description

<resend-milliseconds>

Required

For packets which require confirmation, specifies the minimum amount of time in milliseconds to wait for a corresponding ACK packet, before resending a packet. The default value is 200.

<timeout-milliseconds>

Required

For packets which require confirmation, specifies the maximum amount of time, in milliseconds, that a packet is resent. After this timeout expires Coherence makes a determination if the recipient is to be considered terminated. This determination takes additional data into account, such as if other nodes are still able to communicate with the recipient. The default value is 300000. For production use, the recommended value is the greater of 300000 and two times the maximum expected full GC duration.

<heartbeat-milliseconds>

Required

Specifies the interval between heartbeats. Each member issues a unicast heartbeat, and the most senior member issues the cluster heartbeat, which is a broadcast message. The heartbeat is used by the tcp-ring-listener as part of fast death detection. The default value is 1000.

<flow-control>

Optional

Configures per-node packet throttling and remote GC detection.

<packet-bundling>

Optional

Configures how aggressively Coherence attempts to maximize packet utilization.

packet-publisher

Used in: cluster-config.

Description

Specifies configuration information for the Packet publisher, which manages network data transmission.

Reliable packet delivery

The Packet publisher is responsible for ensuring that transmitted packets reach the destination cluster node. The publisher maintains a set of packets which are waiting to be acknowledged, and if the ACK does not arrive by the packet-delivery resend timeout, the packet is retransmitted (see <packet-delivery> subelement). The recipient node delays the ACK, to batch a series of ACKs into a single response (see <notification-queuing> subelement).

Elements

Table A-50 describes the subelements of the packet-publisher element.

Table A-50 packet-publisher Subelements

Element Required/ Optional Description

<packet-size>

Optional

Specifies the packet sizes to use.

<packet-delivery>

Required

Specifies timing parameters related to reliable packet delivery.

<notification-queueing>

Required

Contains the notification queue related configuration info.

<traffic-jam>

Required

Specifies the maximum number of packets which can be enqueued on the publisher before client threads block.

<packet-buffer>

Required

Specifies how many outgoing packets the operating system is requested to buffer. The value may be expressed either in terms of packets of bytes.

<priority>

Required

Specifies a priority of the packet publisher execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 6.

<enabled>

Optional

Specifies if TCMP clustering is enabled. When using both Coherence*Extend and Coherence TCMP based clustering, this feature allows TCMP to be disabled to ensure that a node only connects by using the Extend protocol. Valid values are true and false. The default value is true.

The preconfigured system property override is coherence.tcmp.enabled.

packet-size

Used in: packet-publisher.

Description

The packet-size element specifies the maximum and preferred packet sizes. All cluster nodes must use identical maximum packet sizes.

Elements

Table A-51 describes the subelements of the packet-size element.

Table A-51 packet-size Subelement

Element Required/ Optional Description

<maximum-length>

Required

Specifies the packet size, in bytes, which all cluster members can safely support. This value must be the same for all members in the cluster. A low value can artificially limit the maximum size of the cluster. This value should be at least 512, and defaults to 64KB.

<preferred-length>

Required

Specifies the preferred size, in bytes, of the DatagramPacket objects that are sent and received on the unicast and multicast sockets.

This value can be larger or smaller than the <maximum-length> value, and need not be the same for all cluster members. The ideal value is one which fits within the network MTU, leaving enough space for either the UDP or TCP packet headers, which are 32, and 52 bytes respectively. The preferred length should be at least 512. The default value is based on the local nodes MTU.

packet-speaker

Used in: cluster-config.

Description

Specifies configuration information for the packet speaker which is used for network data transmission when packet publisher loads are high.

Note:

The packet speaker is not used for TCMP/TMB, which is the default protocol for data communication.

Elements

Table A-52 describes the subelements of the packet-speaker element.

Table A-52 packet-speaker Subelements

Element Required/ Optional Description

<enabled>

Optional

Specifies whether or not the packet-speaker thread is enabled. Valid values are true and false. The default value is false.

The preconfigured system property override is coherence.speaker.enabled.

<volume-threshold>

Optional

Specifies the packet load which must be present for the speaker to be activated.

<priority>

Required

Specifies a priority of the packet speaker execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 8.

participant

Used in: participants.

Description

The participant element specifies the remote coherence cluster that is participating in the federation. Any number of participants can be defined.

Elements

Table A-53 describes the subelements of the participant element.

Table A-53 participant Subelements

Element Required/ Optional Description

<name>

Required

Specifies the cluster name of the participant.

<initial-action>

Optional

Specifies the startup action for the remote participant. The action is taken by the local participant when it starts up. Valid values are:

  • start – (default) specifies that storage nodes start replicating as soon as there are entries available for replication.

  • pause – Specifies that replication is paused. All entries that are marked for replication are stored in the federation service internal journal cache until a start operation is performed using the FederationManagerMbean MBean.

  • stop – Specifies that entries are not marked for replication nor are they stored in the federation service internal journal cache.

<connect-timeout>

Optional

Specifies the timeout of a connection to a destination participant.

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 1m.

<connect-retry-timeout>

Optional

Specifies the total amount of time trying to connect to a destination participant before giving up.

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

<send-timeout>

Optional

Specifies the acknowledgement timeout for a federated replication message.

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 5m.

<max-bandwidth>

Optional

Specifies the maximum network bandwidth that can be utilized for sending out replication messages. The default value is unlimited. Legal values are decimal values with optional factor and unit descriptors.

Legal factor descriptor includes:

  • 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 one is assumed.

Legal unit descriptor includes:

  • bps (bits per second)

  • Bps (bytes per second)

If no unit is specified, a unit of bps is assumed.

<send-old-value>

Optional

Specifies whether the federation service should include the old values when replicating updated cache entries to remote participants. Legal values are true or false. The default value is true.

<batch-size>

Optional

Specifies the maximum number of journal entries that can be selected for replication. The batch size keeps the heap memory usage within limits when replicating. Legal values are integers representing the number of entries. The Default value is 50.

<geo-ip>

Optional

Specifies geographic metadata for the participant. The value is user-defined with no implicit structure and is used to define the participant (for example, latitude, longitude, country-code, and so on).

<participant-type>

Optional

Specifies the type of the participant. Valid values are:

  • cluster – a remote Coherence cluster.

  • interceptor – a participant that can intercept change records. An interceptor is a receiver participant only.

The default value if no value is specified is cluster.

<interceptors>

Optional

Specifies any number of event interceptors for federation change records.

<remote-addresses>

Optional

Specifies socket addresses for a cluster that is participating as part of a federation.

<name-service-addresses>

Optional

The use of name-service-addresses in participant is deprecated. Use remote-addresses instead.

Contains addresses of one or more name service TCP/IP acceptors for this cluster that is participating as part of a federation.

participants

Used in: federation-config.

Description

The participants element contains the declarative data for each federation participant.

Elements

Table A-53 describes the subelements of the participants element.

Table A-54 participants Subelements

Element Required/ Optional Description

<participant>

Optional

Specifies the remote coherence clusters that are participating in the federation.

password-provider

Description

Used in: password-providers, identity-manager, key-store.

The password-provider element contains the declarative data for a password provider, which must be an instance of the com.tangosol.net.PasswordProvider interface. Password providers allow you to plug in a mechanism for determining an appropriate password instead of entering a password in an SSL socket provider configuration as clear text.

The password-provider element can be used in-line and also supports the id attribute which allows multiple password providers to be defined within the <password-providers> element and referenced. For example:

<key-store>
   <url>file:trust.jks</url>
   <password-provider>
      <name>trustMgrPass</name>
   </password-provider>
   <type>JKS</type>
</key-store>

<password-providers>
   <password-provider id="trustMgrPass">
      <class-name>pacakge.MyPassswordProvider</class-name>
      <init-params>
         <init-param>
            <param-name>param_1</param-name>
            <param-value>private</param-value>
         </init-param>
      </init-params>
   </password-provider>
   <password-provider id="identityMgrPass">
      <class-name>pacakage.MyPasswordProvider</class-name>
      <init-params>
         <init-param>
            <param-name>param_1</param-name>
            <param-value>private</param-value>
         </init-param>
      </init-params>
   </password-provider>
</password-providers>

Elements

Table A-55 describes the subelements of the password-provider element.

Table A-55 password-provider Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the fully qualified name of a class that implements the com.tangosol.net.PasswordProvider 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 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

Specifies initialization parameters which are accessible by implementations that include a public constructor with a matching signature. Initialization parameters can be specified when using both the <class-name> element and the <class-factory-name> element.

password-providers

Used in: cluster-config.

Description

The password-providers element contains any number of password provider definitions.

Elements

Table A-56 describes the subelements of the password-providers element.

Table A-56 password-providers Subelements

Element Required/ Optional Description

<password-provider>

Optional

Specifies a password provider definition. The password provider must be a class that implements the PasswordProvider interface.

pause-detection

Used in: flow-control.

Description

Remote Pause detection allows Coherence to detect and react to a cluster node becoming unresponsive (likely due to a long GC). When a node is marked as paused, packets addressed to it are sent at a lower rate until the node resumes responding. This remote GC detection is used to avoid flooding a node while it is incapable of responding.

Elements

Table A-57 describes the subelements of the pause-detection element.

Table A-57 pause-detection Subelements

Element Required/ Optional Description

<maximum-packets>

Optional

The maximum number of packets that are resent to an unresponsive cluster node after which the node is assumed to be paused. Specifying a value of 0 disables pause detection. The default value is 16.

persistence-environment

Description

The persistent-environment element contains configuration information for a persistence environment implementation. The element supports the id attribute which allows multiple environment definitions to be created and referenced by a cache. For example:

<persistence-environments>
   <persistence-environment id="environment1">
      <persistence-mode>active</persistence-mode>
      <active-directory>/environment1/active</active-directory>
      <snapshot-directory>/environment1/snapshot</snapshot-directory>
      <trash-directory>/environment1/trash</trash-directory>
   </persistence-environment>
   <persistence-environment id="environment2">
      <persistence-mode>active</persistence-mode>
      <active-directory>/environment2/active</active-directory>
      <snapshot-directory>/environment2/snapshot</snapshot-directory>
      <trash-directory>/environment2/trash</trash-directory>
   </persistence-environment>
</persistence-environments>

Directory locations can be on a local disk or a shared disk. Local disk storage requires a list of storage-enabled hosts to be configured. See The address-provider Element for Persistence.

Elements

Table A-58 describes the subelements of the persistence-environment element.

Table A-58 persistence-environment Subelements

Element Required/ Optional Description

<instance>

Optional

Specifies a custom persistence environment implementation to be used instead of the default persistence environment.

<persistence-mode>

Optional

Specifies whether the persistence environment is used to continually persist cached data (active) or only when requested (on-demand). Legal values are: active and on-demand. The default value is on-demand.

<active-directory>

Optional

Specifies the path to a directory under which cached data is actively persisted by a persistent environment. The default value is USER_HOME/coherence/active.

<snapshot-directory>

Optional

Specifies the path to a directory under which copies of cached data are persisted by a persistent environment. The default value is USER_HOME/coherence/snapshots.

<trash-directory>

Optional

Specifies the path to a directory under which potentially corrupted persisted data is stored by a persistent environment. The default value is USER_HOME/coherence/trash.

persistence-environments

Used in: cluster-config.

Description

The persistence-environments element contains the declarative data for each persistence environment.

Elements

Table A-59 describes the subelements of the persistence-environments element.

Table A-59 persistence-environments Subelements

Element Required/ Optional Description

<persistence-environment>

Optional

Contains configuration information for each persistence environment implementation.

provider

Description

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

Elements

Table A-60 describes the subelements of the provider element.

Table A-60 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.

ramjournal-manager

Used in: journaling-config.

Description

The <ramjournal-manager> element contains the configuration for a RAM journal resources manager, which manages memory buffers for journal-based storage in-memory. A RAM journal resource manager uses a flash journal resource manager to store large objects and is also used as an overflow when the amount of total memory allocated to the RAM journal is reached. A RAM journal also uses a flash journal when the journal garbage collection is temporarily not able to keep up with demand. See flashjournal-manager.

Elements

Table A-61 describes the subelements of the ramjournal-manager element.

Table A-61 ramjournal-manager Subelements

Element Required/ Optional Description

<minimum-load-factor>

Optional

Specifies the factor of live data below which a journal file is eligible for compaction (garbage collection).

<maximum-value-size>

Optional

Specifies the maximum size, in bytes, of binary values that are to be stored in the RAM journal. The value cannot exceed 4MB. The default value is 64KB.

Binary values that exceed the maximum value size are automatically delegated to a flash journal.

<maximum-file-size>

Optional

Specifies the maximum file size of the underlying journal files. The value must be a power of two and a multiple of the block size. The value must be between 2MB and 2GB. The default value is 2MB. The maximum file size should not be changed.

<collector-timeout>

Optional

Specifies the amount of time that the journal collector can remain unresponsive prior to considering it timed out. The minimum timeout is 30s. Legal values are strings representing time intervals. The Default value is 10m.

<maximum-size>

Optional

Specifies the maximum amount of RAM that is used by the journal. The value can either be specified as a percentage of the maximum available heap or as a specific amount of memory. If the value contains a percentage sign (%), it is interpreted as a percentage of the maximum JVM heap (the JVM max heap is typically specified by the -Xmx argument on the java command line). If specified as a specific amount of memory, the value must be between 16MB and 64GB. The default value is 25%. That is, the RAM journal resource manager uses a maximum of 25% of the available JVM heap.A RAM journal is, by default, backed by a flash journal and all data in excess of the maximum RAM size is automatically delegated to the flash journal. See the maximum-size element for details on disabling flash journal overflow.

The preconfigured system property override is coherence.ramjournal.size.

<off-heap>

Optional

Specifies whether to use in the virtual machine's byte buffer or of-heap NIO buffers.

remote-addresses

Used in: participant.

Description

The remote-addresses element contains the addresses of clusters that are participating as part of a federation. The element can be used to specify both NameService service addresses by specifying the cluster port of the remote participant and direct connect addresses for environments which cannot use the NameService service for address lookup. Specifying the cluster port of the remote participant is recommended.

Elements

Table A-62 describes the subelements of the remote-addresses element.

Table A-62 remote-addresses Subelements

Element Required/ Optional Description

<socket-address>

Optional

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

<address-provider>

Optional

specifies either socket address information (IP, or DNS name, and port) or an implementation of the com.tangosol.net.AddressProvider interface.

reporter

Used in: management-config.

Description

The Reporter provides JMX reporting capabilities. The Reporter provides out-of-the-box reports and also supports the creation of custom reports. The reports help administrators and developers manage capacity and trouble shoot problems.

Elements

Table A-63 describes the subelements of the reporter element.

Table A-63 reporter Subelements

Element Required/ Optional Description

<configuration>

Required

Specifies the location for the report group deployment descriptor. The default file is reports/report-group.xml and is located in the coherence.jar library.

<autostart>

Required

Specifies whether the Reporter automatically starts when the node starts. Valid values are true and false. The default value is false.

<distributed>

Required

Specifies whether the reporter runs on multiple management nodes. Valid values are true and false. The default value is false.

<timezone>

Optional

Specifies the time zone to be used for timestamps that are displayed within a report. See java.util.TimeZone for supported time zone formats. The default, if no time zone is specified, is the local time zone.

<timeformat>

Optional

Specifies the time and date format to be used for timestamps that are displayed within a report. The value must be a pattern supported by the java.text.SimpleDateFormat class. The default value is EEE MMM dd HH:mm:ss zzz yyyy.

security-config

Used in: coherence.

Elements

Table A-64 describes the subelements of the security-config element.

Table A-64 security-config Subelements

Element Required/ Optional Description

<enabled>

Required

Specifies whether the access controller security feature is enabled. Legal values are true or false. The default value is false.

The preconfigured system property override is coherence.security.

<login-module-name>

Required

Specifies the name of the JAAS LoginModule that is used to authenticate the caller. This name should match a module in a configuration file is used by the JAAS (for example specified by using the -Djava.security.auth.login.config Java command line attribute). See Steps to Implement a LoginModule in Login Module Developer's Guide.

<access-controller>

Required

Contains the configuration information for the class that implements com.tangosol.net.security.AccessController interface, which is used by the security framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights.

<callback-handler>

Optional

Contains the configuration information for the class that implements javax.security.auth.callback.CallbackHandler interlace which is called if an attempt is made to access a protected clustered resource when there is no identity associated with the caller.

<identity-asserter>

Optional

Contains the configuration information for a class that implements the com.tangosol.net.security.IdentityAsserter interface which is called to validate an identity token to establish a user's identity. An identity asserter is used with an identity transformer to protect connections between Coherence*Extend clients and proxies.

<identity-transformer>

Optional

Contains the configuration information for the class that implements com.tangosol.net.security.IdentityTransformer interface which is called to transform a Subject (Principal for .NET) to a token that asserts identity. An identity transformer is used with an identity asserter to protect connections between Coherence*Extend clients and proxies.

<subject-scope>

Optional

Specifies whether the remote cache or service reference is shared by subject. Valid values are true or false. Setting the value to true means that remote references are not globally shared; each subject gets a different reference. The default value is false.

<authorizer>

Optional

Contains the configuration information for a class that implements the com.tangosol.net.security.Authorizer interface which represents an environment-specific facility for authorizing callers to perform actions described by the corresponding permission objects. Use the <instance> element to enter the class.

serializer

Used in: serializers.

Description

The serializer element contains a serializer class configuration. Serializer classes must implement com.tangosol.io.Serializer. A Java serializer and POF serializer are predefined:

<cluster-config>
   <serializers>
      <serializer id="java">
         <class-name>com.tangosol.io.DefaultSerializer</class-name>
      </serializer>
 
      <serializer id="pof">
         <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
        <init-params>
            <init-param>
               <param-type>String</param-type>
               <param-value>pof-config.xml</param-value>
            </init-param>
         </init-params>
      </serializer>
   </serializers>
</cluster-config>

Serializer definitions are referenced by individual cache scheme definitions (see serializer) and can be referenced by the default serializer for services that do not explicitly define a serializer (see defaults).

Additional serializers can be defined in an operational override file as required.

Elements

Table A-65 describes the subelements of the serializer element.

Table A-65 serializer Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies a class that implements com.tangosol.io.Serializer. This element cannot be used with the <class-factory-name> element.

<class-factory-name>

Optional

Specifies a factory class for creating custom serializer instances. The instances must implement com.tangosol.io.Serializer.

This element cannot be used with 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 serializer implementation.

serializers

Used in: cluster-config.

Description

The serializers element contains the declarative data for each serializer.

Elements

Table A-66 describes the subelements of the serializers element.

Table A-66 serializers Subelements

Element Required/ Optional Description

<serializer>

Optional

Specifies the declarative data of a particular serializer.

service

Used in: services.

Description

Specifies the configuration for Coherence services.

Service Components

The types of services which can be configured includes:

  • PartitionedService.PartitionedCache—A cache service which evenly partitions cache entries across the cluster nodes which run the service. This service is often referred to as the distributed cache service

  • ReplicatedCache—A cache service which maintains copies of all cache entries on all cluster nodes which run the service.

  • ReplicatedCache.Optimistic—A version of the ReplicatedCache which uses optimistic locking.

  • SimpleCache —A version of the ReplicatedCache which lacks concurrency control.

  • LocalCache—A cache service for caches where all cache entries reside in a single cluster node.

  • InvocationService—A service used for performing custom operations on remote cluster nodes.

  • ProxyService—A service that accepts connections from Coherence*Extend clients.

  • RemoteCache—A service that routes cache operations from Coherence*Extend clients to a cache on the cluster.

  • RemoteInvocation— A service that routes cache invocation tasks from Coherence*Extend clients to a cache on the cluster.

  • NameService—A service that is a specialized TCP acceptor that allows Coherence*Extend clients to connect to a proxy by specifying a proxy service name instead of a proxy service address.

  • RemoteNameService— A NameService implementation that allows a JVM to use a remote NameService without having to join the Cluster.

  • PartitionedService.PartitionedCache.FederatedCache – A specialized partitioned cache service that replicates cached data across clusters.

Elements

Table A-67 describes the subelements of the services element.

Table A-67 service Subelements

Element Required/ Optional Description

<service-type>

Required

Specifies the canonical name for a service, allowing the service to be referenced from the service-name element in cache configuration caching schemes. See caching-schemes .

<service-component>

Required

Specifies either the fully qualified class name of the service or the relocatable component name relative to the base Service component. Legal values are:

  • PartitionedService.PartitionedCache (DistributedCache)

  • ReplicatedCache

  • ReplicatedCache.Optimistic

  • SimpleCache

  • LocalCache

  • InvocationService

  • ProxyService

  • RemoteCache

  • RemoteInvocation

  • NameService

<use-filters>

Optional

Contains the list of filter names to be used by this service. For example, specify use-filter as follows:

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

The example activates gzip compression for the network messages used by this service, which can help substantially with WAN and low-bandwidth networks.

<init-params>

Optional

Specifies the initialization parameters that are specific to each service. Each parameter is described below.

Initialization Parameter Settings

The <init-param> element in the Coherence operational configuration deployment descriptor defines initialization parameters for a service. The parameters that appear under init-param are different, depending on the service.

The tables in this section describes the specific <param-name>/<param-value> pairs that can be configured for each service. The Parameter Name column refers to the value of the <param-name> element and Parameter Value Description column refers to the possible values for the corresponding <param-value> element.

The following sections describe the parameters that can be configured for each of the services:

DistributedCache Service Parameters

A DistributedCache service supports the parameters listed in Table A-68. These settings may also be specified for each service instance as part of the <distributed-scheme> element in the coherence-cache-config.xml descriptor.

Table A-68 DistributedCache Service Parameters

Parameter Name Parameter Value Description

lease-granularity

Specifies the lease ownership granularity. Legal values are:

  • thread (default)

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

partition-count

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. The default value is 257 partitions. See Define the Partition Count.

local-storage

Specifies whether this member of the DistributedCache service enables local storage.

Normally this value should be left unspecified within the configuration file, and instead set on a per-process basis using the coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptor. Legal values are true or false. The default value is true.

The preconfigured system property override is coherence.distributed.localstorage.

transfer-threshold

Specifies the threshold for the primary buckets distribution in kilobytes. When a new node joins the distributed 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 rebalanced 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 0.5MB.

The preconfigured system property override is coherence.distributed.transfer.

backup-count

Specifies the number of members of the partitioned cache service that hold the backup data for each unit of storage in the cache. The default value is 1.

The preconfigured system property override is coherence.distributed.backupcount.

thread-count

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. The default value is 0.

Set the value to 0 for scenarios with purely in-memory data (no read-through, write-through, or write-behind) and simple access (no entry processors, aggregators, and so on). For heavy compute scenarios (such as aggregators), the number of threads should be the number of available cores for that computer. For example, if you run 4 nodes on a 16 core box, then there should be roughly 4 threads in the pool. For I/O intensive scenarios (such as read through, write-through, and write-behind), the number of threads must be higher. In this case, increase the threads just to the point that the box is saturated.

The preconfigured system property override is coherence.distributed.threads.

key-associator

Specifies the name of a class that implements the com.tangosol.net.partition.KeyAssociator interface. This implementation must have a zero-parameter public constructor.

key-partitioning

Specifies the name of a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface. This implementation must have a zero-parameter public constructor.

partition-listener

Specifies the name of a class that implements the com.tangosol.net.partition.PartitionListener interface. This implementation must have a zero-parameter public constructor.

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered hung. Legal values are positive integers or zero (indicating no default timeout).

Note: a posted task that has not yet started is never considered hung. This attribute is applied only if the thread pool is used.

The preconfigured system property override is coherence.distributed.task.hung.

task-timeout

Specifies the timeout value in milliseconds for requests executing on the service worker threads. This attribute applies only if the thread pool is used and only applies to entry processor implementations that implement the PriorityTask interface. 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. Legal values are positive integers or zero. If zero is specified, the default service-guardian <timeout-milliseconds> value is used.

The preconfigured system property override is coherence.distributed.task.timeout.

request-timeout

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

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

The preconfigured system property override is coherence.distributed.request.timeout.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

backup-count-after- writebehind

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

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

Recommended value is 0.

guardian-timeout

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

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

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

partitioned-quorum-policy-scheme

Specifies quorum policy settings for the partitioned cache service. See partitioned-quorum-policy-scheme.

partition-assignment-strategy

Specifies the strategy that is used by a partitioned service to manage partition distribution.

  • simple – (default) 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.

The preconfigured system property override is coherence.distributed.assignmentstrategy.

compressor

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

  • none (default) – 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.

  • the fully qualified name of a class that implements the com.tangosol.io.DeltaCompressor interface.

The preconfigured system property override is coherence.distributed.compressor.

service-priority

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

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.

worker-priority

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 5.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.distributed.transport.reliable.

async-backup

Specifies whether the partitioned cache service should backup changes asynchronously while concurrently responding to the client. Legal values are true or false. The default value is false.

The preconfigured system property override is coherence.distributed.asyncbackup.

persistence

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

thread-count-max

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

The preconfigured system property override is coherence.distributed.threads.max.

thread-count-min

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

The preconfigured system property override is coherence.distributed.threads.min.

ReplicatedCache Service Parameters

A ReplicatedCache service supports the parameters listed in Table A-69. These settings may also be specified for each service instance as part of the replicated-scheme element in the coherence-cache-config.xml descriptor.

Table A-69 ReplicatedCache Service Parameters

Parameter Name Parameter Value Description

standard-lease- milliseconds

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 then packet-delivery/timeout-milliseconds value. Legal values are from positive long numbers or zero. The default value is 0.

lease-granularity

Specifies the lease ownership granularity. Available since release 2.3.Legal values are:

  • thread (default)

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

mobile-issues

Specifies whether lease issues should be transferred to the most recent lock holders. Legal values are true or false. The default value is false.

request-timeout

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

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

The preconfigured system property override is coherence.replicated.request.timeout.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

guardian-timeout

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

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 preconfigured system property override is coherence.replicated.guard.timeout.

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

service-priority

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

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.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.replicated.transport.reliable.

OptimisticCache Service Parameters

An OptimisiticCache service supports the parameters listed in Table A-70. These settings may also be specified for each service instance as part of the optimistic-scheme element in the coherence-cache-config.xml descriptor.

Table A-70 OptimisiticCache Service Parameters

Parameter Name Parameter Value Description

request-timeout

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

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

The preconfigured system property override is coherence.optimistic.request.timeout.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

guardian-timeout

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

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 preconfigured system property override is coherence.optimistic.guard.timeout.

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

service-priority

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

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.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.optimistic.transport.reliable.

Invocation Service Parameters

An Invocation service supports the parameters listed in Table A-71. These settings may also be specified for each service instance as part of the invocation-scheme element in the coherence-cache-config.xml descriptor.

Table A-71 Invocation Service Parameters

Parameter Name Parameter Value Description

thread-count

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

Set the value to 0 for scenarios with purely in-memory data (no read-through, write-through, or write-behind) and simple access (no entry processors, aggregators, and so on). For heavy compute scenarios (such as aggregators), the number of threads should be the number of available cores for that compute. For example, if you run 4 nodes on a 16 core box, then there should be roughly 4 threads in the pool. For I/O intensive scenarios (such as read through, write-through, and write-behind), the number of threads must be higher. In this case, increase the threads just to the point that the box is saturated.

The preconfigured system property override is coherence.invocation.threads.

task-hung-threshold

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 preconfigured system property override is coherence.invocation.task.hung.

task-timeout

Specifies the default task execution timeout value for requests that can time out (that is, polls and PriorityTask implementations), but do not explicitly specify an 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. Legal values are positive integers or zero (indicating no default timeout).

The preconfigured system property override is coherence.invocation.task.timeout.

request-timeout

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

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

The preconfigured system property override is coherence.invocation.request.timeout.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

guardian-timeout

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

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 preconfigured system property override is coherence.invocation.guard.timeout.

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

service-priority

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

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.

worker-priority

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 5.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.invocation.transport.reliable.

thread-count-max

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

The preconfigured system property override is coherence.invocation.threads.max.

thread-count-min

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

The preconfigured system property override is coherence.invocation.threads.min.

LocalCache Service Parameters

A LocalCache service supports the parameters listed in Table A-72.

Table A-72 LocalCache Service Parameters

Parameter Name Parameter Value Description

lock-enforce

Specifies whether locking is enforced for put, remove and clear operations. If the value is false, a client is responsible for calling lock and unlock explicitly.

The default value is false.

lock-wait

Specifies the number of milliseconds to continue trying to obtain a lock. This parameters is only used if locking enforcement is enabled. A value of -1 blocks the calling thread until the lock can be obtained.

The default value is 0.

Proxy Service Parameters

A Proxy service supports the parameters listed in Table A-73. These settings may also be specified for each service instance as part of the proxy-scheme element in the coherence-cache-config.xml descriptor.

Table A-73 Proxy Service Parameters

Parameter Name Parameter Value Description

acceptor-config

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

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

thread-count

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 for use by the proxy service. Legal values are positive integers or 0. The default value is 0, which indicates that dynamic thread pooling is enabled and that the number of threads automatically adjusts based on proxy service load. Specifying a positive value explicitly sets the number of threads in the pool.

Note: Proxy service threads perform operations on behalf of the calling application. Therefore, when explicitly setting the number of threads, set the value to as many threads as there are concurrent operations.

To disable the thread pool, set the thread-count-max and thread-count-min parameters to 0. All relevant tasks are performed on the proxy service thread when the thread pool is disabled.

The preconfigured system property override is coherence.proxy.threads.

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered hung. Legal values are positive integers or zero (indicating no default timeout).

Note: a posted task that has not yet started is never considered hung. This attribute is applied only if the thread pool is used

The preconfigured system property override is coherence.proxy.task.hung.

task-timeout

Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the com.tangosol.net.PriorityTask interface), but do not explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used. Legal values are positive integers or zero (indicating no default timeout).

The preconfigured system property override is coherence.proxy.task.timeout.

request-timeout

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

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

guardian-timeout

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

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 preconfigured system property override is coherence.proxy.guard.timeout.

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

proxy-quorum-policy-scheme

Specifies quorum policy settings for the Proxy service.

load-balancer

Specifies the default load balancing strategy that is used by a proxy service if a strategy is not explicitly configured as part of the proxy scheme. 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.

service-priority

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

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.

worker-priority

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 5.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.proxy.transport.reliable.

thread-count-max

Specifies the maximum number of daemon threads that are allowed in the dynamic thread pool. This parameter is only valid if a thread-count value is set to 0. Legal values are positive integers or 0. Setting a value for both this parameter and the thread-count-min parameter indicates that no daemon threads are created and that all client requests are handled by the proxy service thread. The default value is Integer.MAX_VALUE.

The preconfigured system property override is coherence.proxy.threads.max.

thread-count-min

Specifies the minimum number of daemon threads that are allowed (and initially created) in the dynamic thread pool. This parameter is only valid if a thread-count value is set to 0. Legal values are positive integers or 0. Setting a value for both this parameter and the thread-count-max parameter indicates that no daemon threads are created and that all client requests are handled by the proxy service thread. The default value is 1.

The preconfigured system property override is coherence.proxy.threads.min.

RemoteCache Service Parameters

A RemoteCache service supports the parameters listed in Table A-74. These settings may also be specified for each service instance as part of the remote-cache-scheme element in the coherence-cache-config.xml descriptor.

Table A-74 RemoteCache Service Parameters

Parameter Name Parameter Value Description

initiator-config

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

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

defer-key-association-check

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

RemoteInvocation Service Parameters

A RemoteInvocation service supports the parameters listed in Table A-75. These settings may also be specified for each service instance as part of the remote-invocation-scheme element in the coherence-cache-config.xml descriptor.

Table A-75 RemoteInvocation Service Parameters

Parameter Name Parameter Value Description

initiator-config

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

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

NameService Parameters

A NameService service supports the parameters listed in Table A-76.

Table A-76 NameService Parameters

Parameter Name Parameter Value Description

acceptor-config

Contains the configuration of a connection acceptor that is used discover proxy services that are available in the cluster for use by Coherence*Extend clients.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

RemoteNameService Parameters

A RemoteNameService service supports the parameters listed in Table A-77.

Table A-77 RemoteNameService Parameters

Parameter Name Parameter Value Description

initiator-config/tcp-initiator

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

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

FederatedCache Service Parameters

A FederatedCache service supports the parameters listed in Table A-78. These settings may also be specified for each service instance as part of the <federated-scheme> element in the coherence-cache-config.xml descriptor.

Table A-78 FederatedCache Service Parameters

Parameter Name Parameter Value Description

lease-granularity

Specifies the lease ownership granularity. Legal values are:

  • thread (default)

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

partition-count

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. The default value is 257 partitions. See Define the Partition Count.

local-storage

Specifies whether this member of the FederatedCache service enables local storage.

Normally this value should be left unspecified within the configuration file, and instead set on a per-process basis using the coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptor. Legal values are true or false. The default value is true.

The preconfigured system property override is coherence.distributed.localstorage.

transfer-threshold

Specifies the threshold for the primary buckets distribution in kilobytes. When a new node joins the distributed 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 rebalanced 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 0.5MB.

The preconfigured system property override is coherence.distributed.transfer.

backup-count

Specifies the number of members of the federated cache service that hold the backup data for each unit of storage in the cache. The default value is 1.

The preconfigured system property override is coherence.distributed.backupcount.

thread-count

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 federated 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. The default value is 0.

Set the value to 0 for scenarios with purely in-memory data (no read-through, write-through, or write-behind) and simple access (no entry processors, aggregators, and so on). For heavy compute scenarios (such as aggregators), the number of threads should be the number of available cores for that computer. For example, if you run 4 nodes on a 16 core box, then there should be roughly 4 threads in the pool. For I/O intensive scenarios (such as read through, write-through, and write-behind), the number of threads must be higher. In this case, increase the threads just to the point that the box is saturated.

The preconfigured system property override is coherence.distributed.threads.

key-associator

Specifies the name of a class that implements the com.tangosol.net.partition.KeyAssociator interface. This implementation must have a zero-parameter public constructor.

key-partitioning

Specifies the name of a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface. This implementation must have a zero-parameter public constructor.

partition-listener

Specifies the name of a class that implements the com.tangosol.net.partition.PartitionListener interface. This implementation must have a zero-parameter public constructor.

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered hung. Legal values are positive integers or zero (indicating no default timeout).

Note: a posted task that has not yet started is never considered hung. This attribute is applied only if the thread pool is used.

The preconfigured system property override is coherence.distributed.task.hung.

task-timeout

Specifies the timeout value in milliseconds for requests executing on the service worker threads. This attribute applies only if the thread pool is used and only applies to entry processor implementations that implement the PriorityTask interface. 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. Legal values are positive integers or zero. If zero is specified, the default service-guardian <timeout-milliseconds> value is used.

The preconfigured system property override is coherence.distributed.task.timeout.

request-timeout

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

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. Legal values are positive integers or zero (indicating no default timeout). The default value is 0.

The preconfigured system property override is coherence.distributed.request.timeout.

serializer

Specifies a serializer class for object serialization. Serializer classes must implement the com.tangosol.io.Serializer interface. The preferred method for specifying a serializer is to define it within the global serializer element and then configure it for a cache within the cache configuration file.

backup-count-after- writebehind

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

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

Recommended value is 0.

guardian-timeout

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

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

service-failure-policy

Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. See the service-guardian element to globally configure the service guardian for all services.

Legal values are:

  • exit-cluster – 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 – the class configuration information for a com.tangosol.net.ServiceFailurePolicy implementation.

member-listener

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 is used as an alternative to programmatically adding a MapListener on a service.

partitioned-quorum- policy-scheme

Specifies quorum policy settings for the federated cache service. See partitioned-quorum-policy-scheme.

partition-assignment- strategy

Specifies the strategy that is used by a federated service to manage partition distribution.

  • simple – (default) 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.

The preconfigured system property override is coherence.distributed.assignmentstrategy.

compressor

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

  • none (default) – 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.

  • the fully qualified name of a class that implements the com.tangosol.io.DeltaCompressor interface.

The preconfigured system property override is coherence.distributed.compressor.

service-priority

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

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.

worker-priority

Specifies the priority for the worker threads. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 5.

reliable-transport

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 shared transport instance that is configured in the <reliable-transport> subelement of the <unicast-listener> element.

The preconfigured system property override is coherence.distributed.transport.reliable.

async-backup

Specifies whether the federated cache service should backup changes asynchronously while concurrently responding to the client. Legal values are true or false. The default value is false.

The preconfigured system property override is coherence.distributed.asyncbackup.

persistence

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

thread-count-max

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

The preconfigured system property override is coherence.distributed.threads.max.

thread-count-min

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

The preconfigured system property override is coherence.distributed.threads.min.

service-guardian

Used in: cluster-config.

Description

Specifies the configuration of the service guardian, which detects and attempts to resolve service deadlocks.

Elements

Table A-79 describes the subelements of the service-guardian element.

Table A-79 service-guardian Subelements

Element Required/ Optional Description

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

<timeout-milliseconds>

Optional

The timeout value used to guard against deadlocked or unresponsive services. It is recommended that service-guardian/timeout-milliseconds be set equal to or greater than the packet-delivery/timeout-milliseconds value. The default value is 305000.

The preconfigured system property override is coherence.guard.timeout

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

services

Used in: cluster-config.

Description

The services element contains the declarative data for each service.

Elements

Table A-67 describes the subelements of the services element.

Table A-80 services Subelements

Element Required/ Optional Description

<service>

Optional

Specifies the declarative data of a particular service.

shutdown-listener

Used in: cluster-config.

Description

Specifies the action a cluster node should take upon receiving an external shutdown request. External shutdown includes the "kill" command on UNIX and Ctrl-C on Windows and UNIX.

Elements

Table A-81 describes the subelements of the shutdown-listener element.

Table A-81 shutdown-listener Subelements

Element Required/ Optional Description

<enabled>

Required

Specifies the type of action to take upon an external JVM shutdown. Legal values:

  • none – perform no explicit shutdown actions

  • force – (default) perform "hard-stop" the node by calling Cluster.stop()

  • graceful – perform a "normal" shutdown by calling Cluster.shutdown()

  • true – same as force

  • false – same as none

Note: For production use, the suggested value is none unless testing has verified that the behavior on external shutdown is exactly what is desired.

The preconfigured system property override is coherence.shutdownhook.

snapshot-archivers

Used in: cluster-config.

Description

The snapshot-archivers element contains the declarative data for each persistence snapshot archiver. Snapshot archivers are used to save persistence snapshots.

Elements

Table A-82 describes the subelements of the shutdown-listener element.

Table A-82 snapshot-archivers Subelements

Element Required/ Optional Description

<directory-archiver>

Optional

Contains the configuration information for the default directory-based snapshot archiver that uses a shared directory to store archived snapshots. The archive directory location and name must be the same across all members and accessible to all members. The directory-archiver element supports the id attribute which allows multiple directory archiver definitions to be created and referenced by a cache. Specify a shared directory within the <archive-directory> element. For example:

<directory-archiver id="archiver1">
   <archive-directory>/temp/mydirectory</archive-directory>
</directory-archiver>

<custom-archiver>

Optional

Contains the configuration information for a class that implements the SnapshotArchiver interface. The custom-archiver element supports the id attribute which allows multiple custom archiver definitions to be created and referenced by a cache. See instance.

socket-address

Description

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

Elements

Table A-83 describes the subelements of the socket-address element.

Table A-83 socket-address Subelements

Element Required/ Optional Description

<address>

Required

Specifies the IP address that a Socket listens or publish on. Enter either 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.

<port>

Required

Specifies the port that the Socket listens or publishes on. Legal values are from 1 to 65535. Use the default cluster port, 7574, unless a different cluster port has been defined.

socket-provider

Description

The <socket-provider> element contains the configuration information for a socket and channel factory. The following socket providers are supported and referenced using their defined id attribute name.

<socket-providers>
   <socket-provider id="system">
      <system/>
   </socket-provider>

   <socket-provider id="tcp">
      <tcp/>
   </socket-provider>

   <socket-provider id="ssl">
      <ssl>
         <identity-manager>
            <key-store>
               <url system-property="coherence.security.keystore">
                  file:keystore.jks</url>
               <password system-property="coherence.security.password"/>
            </key-store>
            <password system-property="coherence.security.password"/>
         </identity-manager>
         <trust-manager>
            <algorithm>PeerX509</algorithm>
            <key-store>
               <url system-property="coherence.security.keystore">
                  file:keystore.jks</url>
               <password system-property="coherence.security.password"/>
            </key-store>
         </trust-manager>
         <socket-provider>tcp</socket-provider>
      </ssl>
   </socket-provider>

   <socket-provider id="sdp">
      <sdp/>
   </socket-provider>
</socket-providers>

Alternate SSL definitions can be created to support more elaborate SSL configurations.

Elements

Table A-84 describes the subelements of the socket-provider element.

Table A-84 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. This is the default socket provider.

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

socket-providers

Used in cluster-config.

Description

The socket-providers element contains the declarative data for each socket provider implementation. Coherence supports the following socket providers: system, tcp, ssl, and sdp.

Elements

Table A-85 describes the subelements of the socket-providers element.

Table A-85 socket-providers Subelements

Element Required/ Optional Description

<socket-provider>

Optional

Specifies the configuration information for a socket and channel factory.

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. If SSL is configured for the unicast listener, the listener must be configured to use well known addresses.

Elements

Table A-86 describes the subelements of the ssl element.

Table A-86 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, use a <class-factory-name> subelement to 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, use a <class-factory-name> subelement to 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.

cipher-suites

Optional

Specifies a list of ciphers. Use the name element within the cipher-suites element to enter a cipher. Multiple name elements can be specified.

Use the usage attribute to specify whether the list of ciphers are allowed or disallowed. If the usage attribute value is black-list, then the specified ciphers are removed from the default enabled cipher list. If the usage attribute value is white-list, then the specified ciphers are the enabled ciphers. The default value if the usage attribute is not specified is white-list.

protocol-versions

Optional

Specifies a list of protocol versions. Use the name element within the protocol-versions element to enter a protocol version. Multiple name elements can be specified.

Use the usage attribute to specify whether the list of protocol versions are allowed or disallowed. If the usage attribute value is black-list, then the specified protocol versions are removed from the default enabled protocol list. If the usage attribute value is white-list, then the specified protocol versions are the enabled protocols. The default value if the usage attribute is not specified is white-list.

<socket-provider>

Optional

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

storage-authorizer

Description

The storage-authorizer element contains the declarative data for a storage access authorizer, which must be an instance of the com.tangosol.net.security.StorageAccessAuthorizer interface. Storage access authorizers provides server-side access control authorization. The storage-authorizer element supports the id attribute which allows multiple storage access authorizers to be defined and referenced by a cache. For example:

<storage-authorizers>
   <storage-authorizer id="auditing">
      <class-name>package.MyStorageAccessAuthorizer</class-name>
   </storage-authorizer>
   <storage-authorizer id="restricted-access">
      <class-name>package.AnotherStorageAccessAuthorizer</class-name>
   </storage-authorizer>
</storage-authorizers>

Elements

Table A-87 describes the subelements of the storage-authorizer element.

Table A-87 storage-authorizer Subelements

Element Required/ Optional Description

<class-name>

Optional

Specifies the fully qualified name of a class that implements the com.tangosol.net.security.StorageAccessAuthorizer 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 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

Specifies initialization parameters which are accessible by implementations that include a public constructor with a matching signature. Initialization parameters can be specified when using both the <class-name> element and the <class-factory-name> element.

storage-authorizers

Used in: cluster-config.

Description

The storage-authorizers element contains the declarative data for any number of storage access authorizers.

Elements

Table A-88 describes the subelements of the storage-authorizers element.

Table A-88 storage-authorizers Subelements

Element Required/ Optional Description

<storage-authorizer>

Optional

Specifies a storage access authorizer. The storage access authorizer must be a class that implements the StorageAccessAuthorizer interface.

tcp-ring-listener

Used in: cluster-config.

Description

The TCP-ring provides a means for fast death detection of another node within the cluster. When enabled, the cluster nodes use a single "ring" of TCP connections spanning the entire cluster. A cluster node can use the TCP connection to detect the death of another node within a heartbeat interval (the default value s one second; see the <heartbeat-milliseconds> subelement of packet-delivery). If disabled, the cluster node must rely on detecting that another node has stopped responding to packets for a considerately longer interval (see the <timeout-milliseconds> subelement of packet-delivery). When the death has been detected it is communicated to all other cluster nodes.

Elements

Table A-89 describes the subelements of the tcp-ring-listener element.

Table A-89 tcp-ring-listener Subelements

Element Required/ Optional Description

<enabled>

Optional

Specifies whether the tcp ring listener should be enabled to defect node failures faster. Valid values are true and false. The default value is true.

<ip-timeout>

Optional

Specifies the timeout to use for determining that a computer that is hosting cluster members has become unreachable. A number of connection attempts may be made before determining that the unreachable members should be removed. Legal values are strings representing time intervals. A timeout of 0 disables system-level monitoring and is not recommended. The default value is 5s.

The values of the <ip-timeout> and <ip-attempts> elements should be high enough to insulate against allowable temporary network outages.

This feature relies upon the java.net.InetAddress.isReachable mechanism, refer to the API documentation see for a description of how it identifies reachability.

<ip-attempts>

Optional

specifies the number of connection attempts to make before determining that a computer that is hosting cluster members has become unreachable, and that those cluster members should be removed.

The values of the <ip-timeout> and <ip-attempts> elements should be high enough to insulate against allowable temporary network outages. Legal values are positive integers. The default value is 3.

<listen-backlog>

Optional

Specifies the size of the TCP/IP server socket backlog queue. Valid values are positive integers. The default value is operating system dependent.

<priority>

Required

Specifies a priority of the tcp ring listener execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 6.

topology-definitions

Used in: federation-config.

Description

The topology-definitions element specifies the topology configuration information. The topology selected determines how data is synchronized between clusters.

Elements

Table A-90 describes the subelements of the topology-definitions element.

Table A-90 topology-definitions Subelements

Element Required/ Optional Description

<active-active>

Optional

Specifies the configuration information for an active-active topology.

<active-passive>

Optional

Specifies the configuration information for an active-passive topology.

<hub-spoke>

Optional

Specifies the configuration information for a hub-spoke topology.

<central-replication>

Optional

Specifies the configuration information for a central-replication topology.

<custom-topology>

Optional

Specifies the configuration for a custom topology.

traffic-jam

Used in: packet-publisher.

Description

The traffic-jam element is used to control the rate at which client threads enqueue packets for the packet publisher to transmit on the network. When the limit is exceeded any client thread is forced to pause until the number of outstanding packets drops below the specified limit. To limit the rate at which the Publisher transmits packets see the flow-control element.

Elements

Table A-91 describes the subelements of the traffic-jam element.

Table A-91 traffic-jam Subelements

Element Required/ Optional Description

<maximum-packets>

Required

Specifies the maximum number of pending packets that the Publisher tolerates before determining that it is clogged and must slow down client requests (requests from local non-system threads). Zero means no limit. This property prevents most unexpected out-of-memory conditions by limiting the size of the resend queue. The default value is 8192.

<pause-milliseconds>

Required

Number of milliseconds that the Publisher pauses a client thread that is trying to send a message when the Publisher is clogged. The Publisher does not allow the message to go through until the clog is gone, and repeatedly sleeps the thread for the duration specified by this property. The default value is 10.

trust-manager

Used in: ssl.

Description

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

A trust manager is responsible for managing the trust material that is used when making trust decisions and for deciding whether credentials presented by a peer should be accepted.

A valid trust-manager configuration contains at least one child element.

Elements

Table A-92 describes the elements of the trust-manager element.

Table A-92 trust-manager Subelements

Element Required/ Optional Description

<algorithm>

Optional

Specifies the algorithm used by the trust 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.

unicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Unicast listener. This element is used to specify the address and port to which a cluster node binds for point-to-point cluster communications.

Multicast-Free Clustering

By default Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, then the Well Known Addresses feature can be used to eliminate the need for multicast traffic. See well-known-addresses.

Elements

Table A-93 describes the subelements of the unicast-listener element.

Table A-93 unicast-listener Subelements

Element Required/ Optional Description

<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. The following socket providers are available: system (default), ssl, tcp, and sdp. Refer to the socket provider configuration using their defined id attribute name. For example:

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

The preconfigured system property override is coherence.socketprovider.

<reliable-transport>

Optional

Specifies the transport protocol that is used for reliable point-to-point communication. By default, all services use the configured protocol and use a shared transport instance. A service can also explicitly specify the transport protocol using a reliable-transport service parameter, which results in a service-specific transport instance. 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 preconfigured system property override is coherence.transport.reliable.

<well-known-addresses>

Optional

Contains a list of well-known addresses that are used by the cluster discovery protocol instead of using multicast broadcast to discover cluster members.

<machine-id>

Optional

Specifies an identifier that should uniquely identify each server machine. The default value is generated from the machine-name element or, lacking that, from the address of the default network interface. Instead of setting machine-id, set machine-name (as well as rack-name and site-name).

<discovery-address>

Optional

Specifies an IP address or DNS name. 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 default value is the wildcard address.

<address>

Required

Specifies the IP address on which a unicast socket listens or publishes. 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. The default value is unspecified and indicates that an address is automatically selected.

The preconfigured system property override is coherence.localhost.

<port>

Required

Specifies the port on which the unicast socket listens or publishes. A second port is automatically opened and defaults to the next port. 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.

The preconfigured system property override is coherence.localport.

<port-auto-adjust>

Required

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.

The preconfigured system property override is coherence.localport.adjust.

<packet-buffer>

Required

Specifies how many incoming packets the operating system is requested to buffer. The value may be expressed either in terms of packets of bytes.

<priority>

Required

Specifies a priority of the unicast listener execution thread. Legal values are from 1 to 10 where 10 is the highest priority. The default value is 8.

volume-threshold

Used in: packet-speaker.

Description

Specifies the minimum outgoing packet volume which must exist for the speaker daemon to be activated.

Performance Impact

Elements

Table A-94 describes the subelements of the packet-speaker element.

Table A-94 packet-speaker Subelements

Element Required/ Optional Description

<minimum-packets>

Required

Specifies the minimum number of packets which must be ready to be sent for the speaker daemon to be activated. A value of 0 forces the speaker to always be used, while a very high value causes it to never be used. If unspecified (the default), it matches the packet-buffer.

well-known-addresses

Used in: unicast-listener.

Note:

This is not a security-related feature, and does not limit the addresses which are allowed to join the cluster. See the authorized-hosts element for details on limiting cluster membership.

If you are having difficulties establishing a cluster when using multicast, see Performing a Multicast Connectivity Test in Administering Oracle Coherence.

Description

By default, Coherence uses a multicast protocol to discover other members when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, the Well Known Addresses (WKA) feature can be used to eliminate the need for multicast traffic. When in use, the cluster is configured with a relatively small list of members which are allowed to start the cluster and which are likely to remain available over the cluster lifetime. There is no requirement for all WKA machines to be simultaneously active at any point in time; however at least one WKA machine must be running for other members to join the cluster.

Example

The following example configures two well-known addresses from which joining members can discover or form the cluster.

<cluster-config>
   <unicast-listener>
      <well-known-addresses>
         <address id="1">192.168.0.100</address>
         <address id="2">192.168.0.101</address>
      </well-known-addresses>
   </unicast-listener>
</cluster-config>

Elements

Table A-95 describes the subelements of the well-known-addresses element.

Table A-95 well-known-addresses Subelements

Element Required/ Optional Description

<socket-address>

Optional

The use of the <socket-address> element within the <well-known-addresses> element is deprecated. Use the <address> element instead.

Specifies a list of WKA that are used by the cluster discovery protocol instead of using multicast broadcast. Additionally, all cluster communication is performed using unicast. If empty or unspecified, multicast communications is used.

The preconfigured system property overrides are coherence.wka and coherence.wka.port.

<address>

Optional

Specifies a list of WKA machine addresses (IP addresses or DNS names) that are used by the cluster discovery protocol instead of using multicast broadcast. 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 must be differentiated by including an id attribute that is set to a unique value. If a list of WKA machine addresses is specified, then a member must be started on one of the WKA machines. In addition, all cluster communication is performed using unicast. If the element is empty or unspecified, multicast communications is used.

The preconfigured system property override is coherence.wka.

<address-provider>

Optional

Contains the configuration for a com.tangosol.net.AddressProvider implementation that supplies the WKA machine list. The calling component attempts to obtain the full list upon member startup, the provider must return a terminating null address to indicate that all available addresses have been returned.

Operational Configuration Attribute Reference

The operational configuration attribute reference describes the attributes available in the operational deployment descriptor.

Table A-96 Operational Deployment Descriptor Attributes

Attribute Required/ Optional Description

xml-override

Optional

The xml-override attribute allows the content of an element to be fully or partially overridden with an XML document that is external to the base document. Legal value of this attribute is the name of the XML document an should be accessible using the ClassLoader.getResourceAsStream(String name) by the classes contained in coherence.jar library. In general, the name should be prefixed with '/' and located in the classpath.

The override XML document referred by this attribute does not have to exist. However, if it does exist then its root element must have the same name as the element it overrides. In cases where there are multiple elements with the same name (for example, <service>) the id attribute is used to identify the base element that is overridden and the override element itself. The elements of the override document that do not have a match in the base document are just appended to the base.

The following elements can be overridden by its own XML override file:

address-provider, authorized-hosts, cache-factory-builder-config, cluster-config, coherence, configurable-cache-factory-config, incoming-message-handler, logging-config, multicast-listener, outgoing-message-handler, security-config, serializer, service, service-failure-policy, shutdown-listener, tcp-ring-listener, unicast-listener, packet-speaker, packet-publisher, persistence-environment, and mbeans

id

Optional

The id attribute differentiates elements that can have multiple occurrences (for example, <service>). See Understanding the XML Override Feature.

system-property

Optional

This attribute is used to specify a system property name for any element. The system property is used to override the element value from the Java command line. This feature enables the same operational descriptor (and override file) to be used across all cluster nodes and customize each node using the system properties. See System Property Overrides.