Fusion Middleware Documentation
Advanced Search


Developing Applications with Oracle Coherence
Close Window

Table of Contents

Show All | Collapse

A Operational Configuration Elements

This appendix provides a detailed reference of the operational deployment descriptor elements and briefly describes the deployment descriptor files in which these elements can appear.

This appendix includes the following sections:

A.1 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 as described in "Operational Override File" below.

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.2/coherence-operational-config.xsd

The <cohrence> element is the root element of the operational descriptor and includes an XSD and Coherence namespace reference and the location of the coherence-operational-config.xsd file. 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">

Notes:

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

A.2 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 "Attribute Reference" for details on using the xml-override attribute.


Element Reference

Table A-1 lists all non-terminal operational configuration elements.

Table A-1 Non-Terminal Operational Configuration Elements

Element Used in

access-controller

security-config

address-provider

well-known-addresses, address-providers

address-providers

cluster-config

authorized-hosts

cluster-config

cache-factory-builder-config

coherence

callback-handler

security-config

cluster-config

coherence

cluster-quorum-policy

cluster-config

coherence

root element

configurable-cache-factory-config

coherence

filter

filters

filter

cluster-config

flashjournal-manager

journaling-config

flow-control

packet-delivery

host-range

authorized-hosts

identity-asserter

security-config

identity-manager

ssl

identity-transformer

security-config

incoming-message-handler

cluster-config

init-param

init-params

init-params

access-controller, address-provider, callback-handler, configurable-cache-factory-config, filter, service

instance

socket-provider, service-failure-policy

journaling-config

cluster-config

key-store

identity-manager, trust-manager

license-config

coherence

logging-config

coherence

management-config

coherence

mbean

mbeans

mbeans

management-config

mbean-filter

management-config

member-identity

cluster-config

multicast-listener

cluster-config

notification-queueing

packet-publisher

outgoing-message-handler

cluster-config

outstanding-packets

flow-control

packet-buffer

multicast-listener, packet-publisher, unicast-listener

packet-bundling

packet-delivery

packet-delivery

packet-publisher

packet-publisher

cluster-config

packet-size

packet-publisher

packet-speaker

cluster-config

pause-detection

flow-control

provider

ssl, identity-manager, trust-manager

ramjournal-manager

journaling-config

reporter

management-config

security-config

coherence

serializer

serializers

serializers

cluster-config

service-guardian

cluster-config

service

services

services

cluster-config

shutdown-listener

cluster-config

socket-address

well-known-addresses

socket-provider

socket-providers, unicast-listener

socket-providers

cluster-config

ssl

socket-provider

tcp-ring-listener

cluster-config

traffic-jam

packet-publisher

trust-manager

ssl

unicast-listener

cluster-config

volume-threshold

packet-speaker

well-known-addresses

unicast-listener



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-2 describes the subelements of the access-controller element.

Table A-2 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 Securing Oracle Coherence for more information on using an access controller. 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="tangosol.coherence.security.keystore"></param-value>
  </init-param>
  <init-param id="2">
    <param-type>java.io.File</param-type>
    <param-value system-property="tangosol.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 tangosol.coherence.security.keystore and tangosol.coherence.security.permissions. For more information on the subelements of the init-param element, see "init-param".



address-provider

Used in: well-known-addresses, address-providers

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.

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. For details on WKA, 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>

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. The tcp-acceptor, remote-addresses, and name-service-addresses elements in the cache configuration file reference address provider definitions using the specified id attribute value. For details on the tcp-acceptor element, see "tcp-acceptor". For details on the remote-addresses element, see "remote-addresses". For details on the name-service-addresses element, see "name-service-addresses". 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>

Elements

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

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

Used in: cluster-config

Description

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

Elements

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

Table A-4 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-5 describes the subelements of the authorized-hosts element.

Table A-5 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-6 describes the subelements of the cache-factory-builder-config element.

Table A-6 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 Java API Reference for Oracle Coherence for details on the ScopeResolver interface.

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-7 describes the subelements of the callback-handler element.

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



cluster-config

Used in: <coherence>

Description

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

Elements

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

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

<filter>

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.

<address-providers>

Optional

Specifies any number of address provider definitions that can be referenced by a proxy service's TCP/IP acceptor.

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



cluster-quorum-policy

Used in: <cluster-config>

Description

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

Element

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

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

Element Required/
Optional
Description

<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 the <timeout-survivor-quorum> or the <class-factory-name> element.

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

<class-factory-name>

Optional

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

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-10 describes the subelements of the coherence element.

Table A-10 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 Managing Oracle Coherence for more information.

<security-config>

Optional

Contains the configuration information for the Coherence Security Framework.

<license-config>

Optional

Contains the edition and operational mode configuration.



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-11 describes the subelements of the configurable-cache-factory-config element.

Table A-11 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 tangosol.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 tangosol.coherence.cacheconfig.



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-12 describes the subelements of each filter element.

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

For more information on the parameter values for the standard filters, refer to "Using Network Filters".



filters

Used in cluster-config.

Description

The filters element contains the declarative data for each filter.

Elements

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

Table A-13 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-14 describes the subelements of the flashjournal-manager element.

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

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

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

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

<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 -Dtangosol.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-15 describes the subelements of the flow-control element.

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



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-16 describes the subelements of each host-range element.

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



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-17 describes the subelements of the <identity-asserter> element.

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

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

Required

Specifies the private key password.



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-19 describes the subelements of the <identity-transformer> element.

Table A-19 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 UDP packets into logical messages and dispatches them to the appropriate Coherence service for processing.

Elements

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

Table A-20 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" for additional details and configuration. 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.

Elements

Table A-21 describes the subelements of the init-param element.

Table A-21 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" for information on the pre-defined parameters that are available for specific services.

<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

Used in: address-provider, filter, service, configurable-cache-factory-config, access-controller, and callback-handler.

Description

Defines a series of initialization parameters.

Elements

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

Table A-22 init-params Subelement

Element Required/
Optional
Description

<init-param>

Optional

Defines an individual initialization parameter.



instance

Used in: service-failure-policy, scope-resolver, and partition-assignment-strategy

Description

The <instance> element contains the configuration of an implementation class or class factory that is used to plug in custom functionality.

Elements

Table A-23 describes the subelements of the instance element.

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



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-23 describes the subelements of the journaling-config element.

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

Used in: identity-manager, trust-manager.

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

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

<type>

Optional

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



license-config

Used in: coherence.

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

Table A-26 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 tangosol.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-27 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

  • 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 tangosol.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 tangosol.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 tangosol.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 tangosol.coherence.log.limit.



management-config

Used in: coherence.

Elements

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

Table A-28 management-config Subelements

Element Optional/
Required
Description

<managed-nodes>

Required

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

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

<allow-remote-management>

Required

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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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-29 describes the subelements of the mbean element.

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

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

Used in management-config.

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="tangosol.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-44 describes the subelements of the mbean-filter element.

Table A-31 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-32 describes the subelements of the member-identity element.

Table A-32 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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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 tangosol.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, whereas distinct clusters on the same network should use different multicast addresses. If you are having difficulties establishing a cluster when using multicast, see Administering Oracle Coherence for instructions on performing a multicast connectivity test.

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, the well-known-addresses feature may be used to eliminate the need for multicast traffic.

Elements

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

Table A-33 multicast-listener Subelements

Element Required
/Optional
Description

<interface>

Optional

Specifies the IP address that a multicast socket is bound to. By default, the interface (NIC) of the unicast-listener IP address is used for the multicast socket; this option allows a different interface to be specified for multicast. Setting this address to 0.0.0.0 allows the operating system to use the unicast routing table to select the interface automatically.

<address>

Required

Specifies the multicast IP address that a Socket listens or publishes on. 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 {build}.{major version}.{minor version}.{patch}.

The preconfigured system property override is tangosol.coherence.clusteraddress.

<port>

Required

Specifies the port that the Socket listens or publishes on. Legal values are from 1 to 65535. The default value depends on the release and build level and typically follows the convention of {version}+{{{build}.

The preconfigured system property override is tangosol.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 tangosol.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.

Note: For production use, the recommended value is 30000.

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



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

Table A-35 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-36 describes the subelements of the outstanding-packets element.

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

Used in: unicast-listener, multicast-listener, packet-publisher.

Description

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

Elements

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

Table A-37 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. 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-38 describes the subelements of the packet-bundling element.

Table A-38 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-39 describes the subelements of the packet-delivery element.

Table A-39 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-40 describes the subelements of the packet-publisher element.

Table A-40 packet-publisher Subelements

Element Required/
Optional
Description

<packet-size>

Optional

Specifies the UDP 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 tangosol.coherence.tcmp.enabled.



packet-size

Used in: packet-publisher.

Description

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

Elements

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

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

Elements

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

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

The preconfigured system property override is tangosol.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.



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-43 describes the subelements of the pause-detection element.

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



provider

Used in: ssl, identity-manager, trust-manager.

Description

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

Elements

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

Table A-44 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 always 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" for details on configuring a flash journal resource manager.

Elements

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

Table A-45 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 always backed up by a flash journal and all data in excess of the maximum RAM size is automatically delegated to the flash journal.

<off-heap>

Optional

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



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-46 describes the subelements of the reporter element.

Table A-46 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-47 describes the subelements of the security-config element.

Table A-47 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 tangosol.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). For details, refer to the Oracle 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-48 describes the subelements of the serializer element.

Table A-48 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-49 describes the subelements of the serializers element.

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

Elements

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

Table A-50 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" for more information.

<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 following sections describe the parameters that can be configured for each of the services:

The tables in each 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.

DistributedCache Service Parameters

A DistributedCache service supports the parameters listed in Table A-51. 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-51 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 "Changing the Number of Partitions" for additional details.

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 tangosol.coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptor. Legal values are true or false. The default value is true.

The preconfigured system property override is tangosol.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 tangosol.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 tangosol.coherence.distributed.backupcount.

thread-count

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 tangosol.coherence.distributed.threads.

key-associator/
class-name

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/
class-name

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/
class-name

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 thread-count value is positive).

The preconfigured system property override is tangosol.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 (the thread-count value is positive) 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 tangosol.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 tangosol.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 tangosol.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/
class-name

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.

  • legacy – (deprecated) The legacy assignment strategy indicates that partition distribution is managed individually on each cluster member.

  • simple – (default) The simple assignment strategy attempts to balance partition distribution while ensuring machine-safety and is more deterministic and efficient than the legacy strategy.

  • 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 tangosol.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 tangosol.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 name of the transport used by this service for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The imb transport is enabled by default on Oracle Exalogic systems for all distributed cache services. The imb transport is automatically used as long as TCMP has not been configured with SSL. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

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

async-backup

Specifies whether the partitioned (distributed) 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 tangosol.coherence.distributed.asyncbackup.



ReplicatedCache Service Parameters

A ReplicatedCache service supports the parameters listed in Table A-52. 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-52 ReplicatedCache Service Parameters

Parameter Name 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 tangosol.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 tangosol.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/
class-name

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 name of the transport used by this service for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The default value is the value specified in the <reliable-transport> subelement of the <unicast-listener> element. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

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



OptimisticCache Service Parameters

An OptimisiticCache service supports the parameters listed in Table A-53. 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-53 OptimisiticCache Service Parameters

Parameter Name 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 an infinite timeout 0.

The preconfigured system property override is tangosol.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 tangosol.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/
class-name

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 name of the transport used by this service for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The default value is the value specified in the <reliable-transport> subelement of the <unicast-listener> element. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

The preconfigured system property override is tangosol.coherence.optimisitic.transport.reliable.



Invocation Service Parameters

An Invocation service supports the parameters listed in Table A-54. 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-54 Invocation Service Parameters

Parameter Name Value, Description

thread-count

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.

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 tangosol.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 thread-count value is positive).

The preconfigured system property override is tangosol.coherence.invocation.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 (the thread-count value is positive). Legal values are positive integers or zero (indicating no default timeout).

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

request-timeout

Specifies the default timeout value in milliseconds for requests that can time out (for example, implement the com.tangosol.net.PriorityTask interface), but do not explicitly specify the request timeout value. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes the following:

  • 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 an infinite timeout 0.

The preconfigured system property override is tangosol.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 tangosol.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/
class-name

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 name of the transport used by this service for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The default value is the value specified in the <reliable-transport> subelement of the <unicast-listener> element. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

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



LocalCache Service Parameters

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

Table A-55 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-56. 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-56 Proxy Service Parameters

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

Specifies the exact number of daemon threads for use by the proxy service. Legal values are positive integers or 0. Note: Specifying a value disables dynamic thread pooling. The value 0 indicates that all relevant tasks are performed on the service thread. The default value is no value and indicates that dynamic thread pooling is enabled and the number of threads automatically adjusts based on proxy service load. Use the thread-count-max and thread-count-min parameters to tune dynamic thread pool behavior.

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 that are occurring.

The preconfigured system property override is tangosol.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 thread-count value is positive).

The preconfigured system property override is tangosol.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 (the thread-count value is positive). Legal values are positive integers or zero (indicating no default timeout).

The preconfigured system property override is tangosol.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 tangosol.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/
class-name

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 name of the transport used by this service for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The default value is the value specified in the <reliable-transport> subelement of the <unicast-listener> element. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

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

thread-count-max

Specifies the maximum number of daemon threads that are allowed in the thread pool. This parameter is only valid if a thread-count value is not set. Legal values are positive integers or 0. A value of 0 indicates that no daemon threads are created and all client requests are handled by the proxy service thread. The default value is 8 times the number of cores.

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

thread-count-min

Specifies the minimum number of daemon threads that are allowed (and initially created) in the thread pool. This parameter is only valid if a thread-count value is not set. Legal values are positive integers. The default value is 2 times the number of cores.

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



RemoteCache Service Parameters

A RemoteCache service supports the parameters listed in Table A-57. 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-57 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-58. 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-58 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-59.

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




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-60 describes the subelements of the service-guardian element.

Table A-60 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 tangosol.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 "Attribute Reference" for more information.


services

Used in: cluster-config

Description

The services element contains the declarative data for each service.

Elements

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

Table A-61 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-62 describes the subelements of the shutdown-listener element.

Table A-62 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 tangosol.coherence.shutdownhook.



socket-address

Used in: well-known-addresses, address-provider

Description

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

Elements

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

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

Note: The localhost setting may not work on systems that define localhost as the loopback address; in that case, specify the computer name or the specific IP address.

<port>

Required

Specifies the port that the Socket listens or publish on. Legal values are from 1 to 65535.

Note: When setting up a WKA member, the port value must match the port value that is specified for the unicast listener port. See the <unicast-listener> element.



socket-provider

Used in: socket-providers, unicast-listener, ssl.

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="tangosol.coherence.security.keystore">
                  file:keystore.jks</url>
               <password system-property="tangosol.coherence.security.password"/>
            </key-store>
            <password system-property="tangosol.coherence.security.password"/>
         </identity-manager>
         <trust-manager>
            <algorithm>PeerX509</algorithm>
            <key-store>
               <url system-property="tangosol.coherence.security.keystore">
                  file:keystore.jks</url>
               <password system-property="tangosol.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-64 describes the subelements of the socket-provider element.

Table A-64 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-65 describes the subelements of the socket-providers element.

Table A-65 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-66 describes the subelements of the ssl element.

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

<socket-provider>

Optional

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



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 UDP 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-67 describes the subelements of the tcp-ring-listener element.

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



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-68 describes the subelements of the traffic-jam element.

Table A-68 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-69 describes the elements of the trust-manager element.

Table A-69 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 that a cluster node binds to, to listen 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, the well-known-addresses feature may be used to eliminate the need for multicast traffic.

Elements

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

Table A-70 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 tangosol.coherence.socketprovider.

<reliable-transport>

Optional

Specifies the name of the transport used by TCMP for reliable point-to-point communication. Valid values are: datagram, tmb (TCP Message Bus), sdmb (SDP Message Bus), and imb (InfiniBand Message Bus). The imb and sdmb transports are only available for Oracle Exalogic systems. The default value is datagram. Note: Setting a value other than datagram results in the majority of cluster data being transported outside of the protection of SSL. Specifically, only cluster join operations are protected when enabling SSL for TCMP.

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

<well-known-addresses>

Optional

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

<address>

Required

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

Note: The localhost setting may not work on systems that define localhost as the loopback address; in that case, specify the computer name or the specific IP address. Also, the multicast listener, by default, binds to the same interface as defined by this address. The default value is localhost.

The preconfigured system property override is tangosol.coherence.localhost.

<port>

Required

Specifies the ports that the Socket listens or publishes on. A second port is automatically opened and defaults to the next available port. Legal values are from 1 to 65535. The default value is 8088 for the first port and 8089 (if available) for the second port.

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

<port-auto-adjust>

Required

Specifies whether the unicast port is automatically incremented if the specified port cannot be bound to because it is in use. Legal values are true or false. The default value is true.

The preconfigured system property override is tangosol.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-71 describes the subelements of the packet-speaker element.

Table A-71 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 Administering Oracle Coherence for instructions on performing a multicast connectivity test.

Description

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, the Well Known Addresses feature may be used to eliminate the need for multicast traffic. When in use the cluster is configured with a relatively small list of nodes 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 nodes to be simultaneously active at any point in time. This list is used by all other nodes to find their way into the cluster without the use of multicast, thus at least one node that is configured as a well-known node must be running for other nodes to be able to join.

Example

The following example configures two well-known-addresses with the default port.

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

Elements

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

Table A-72 well-known-addresses Subelements

Element Required/
Optional
Description

<socket-address>

Optional

Specifies a list of WKA that are used by the cluster discovery protocol instead of using multicast broadcast. If one or more WKA is specified, for a member to join the cluster it either has to be a WKA or there has to be at least one WKA member running. Additionally, all cluster communication is performed using unicast. If empty or unspecified, multicast communications is used.

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

<address-provider>

Optional

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



Attribute Reference

Table A-73 describes the attributes available in the operational deployment descriptor.

Table A-73 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, 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 Appendix C, "System Property Overrides," for more information on this feature.