Skip Headers
Oracle® Coherence Developer's Guide
Release 3.6.1

Part Number E15723-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

A Operational Configuration Elements

This section describes the elements that control the operational and runtime settings used by Oracle Coherence. These settings are used to create, configure and maintain Coherence clustering, communication, and data management services. This section also describes the deployment descriptor files in which these elements can appear.

Operational Configuration Deployment Descriptors

The elements that control the operational and runtime settings to create and configure clustering, communication, and data management services can be specified in either of two deployment descriptors.

The tangosol-coherence.xml descriptor is where you specify the operational and runtime elements that control clustering, communication, and data management services. The optional tangosol-coherence-override.xml override file is where you specify only the subset of the operational descriptor which you want to adjust. See "Operational Override File (tangosol-coherence-override.xml)" for more information.

For information on configuring caches see Appendix B, "Cache Configuration Elements."

Document Location

When deploying Coherence, it is important to make sure that the tangosol-coherence.xml descriptor is present and situated in the application classpath (like with any other resource, Coherence will use the first one it finds in the classpath). By default (as Oracle ships the software) tangosol-coherence.xml is packaged into in the coherence.jar.

Document Root

The root element of the operational descriptor is <coherence> and is where a cluster and services are configured.

Document Format

Coherence Operational Configuration deployment descriptor should begin with the following DOCTYPE declaration:

Example A-1 Operational Configuration Deployment Descriptor DOCTYPE Declaration

<!DOCTYPE coherence SYSTEM "coherence.dtd">

Note:

When deploying Coherence into environments where the default character set is EBCDIC rather than ASCII, please make sure that this descriptor file is in ASCII format and is deployed into its runtime environment in the binary format.

Operational Override File (tangosol-coherence-override.xml)

Though it is acceptable to supply an alternate definition of the default tangosol-coherence.xml file, the preferred approach to operational configuration is to specify an override file. The override file contains only the subset of the operational descriptor which you want to adjust. The default name for the override file is tangosol-coherence-override.xml, and the first instance found in the classpath will be used. The format of the override file is the same as for the operational descriptor, except that all elements are optional, any missing element will simply be loaded from the operational descriptor.

Multiple levels of override files may also be configured, allowing for additional fine tuning between similar deployment environments such as staging and production. For example, this feature is used to provide alternate configurations, such as the logging verbosity, based on the deployment type (evaluation, development, production). For more information on logging verbosity, see the <severity-level> subelement in "logging-config". See also the tangosol-coherence-override-eval.xml, tangosol-coherence-override-dev.xml, and tangosol-coherence-override-prod.xml files, within coherence.jar.

Note:

It is recommended that you supply an override file rather then a custom operational descriptor, thus specifying only the settings you want to adjust.

Command Line Override

Oracle Coherence provides a very powerful command line override feature which allows any element defined in this descriptor to be overridden from the Java command line if it has a system-property attribute defined in the descriptor. This feature enables you to use the same operational descriptor (and override file) across all cluster nodes and customize each node using the system properties. See Appendix C, "Command Line Overrides" for more information on this feature.


Element Index

Table A-1 lists all non-terminal elements which may be used from within the operational configuration.

Table A-1 Non-Terminal Operational Configuration Elements

Element Used in:

access-controller

security-config

address-provider

well-known-addresses

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

filters

cluster-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, filters, services

instance

socket-provider, service-failure-policy

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

incoming-message-handler, packet-publisher

packet-publisher

cluster-config

packet-size

packet-publisher

packet-speaker

cluster-config

pause-detection

flow-control

provider

ssl, identity-manager, trust-manager

reporter

management-config

security-config

coherence

serializers

cluster-config

service-guardian

cluster-config

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.

Table A-2 describes the subelements you can define within 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 will be used by the security framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights. See Chapter 30, "Securing Coherence" for more information. 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>

Preconfigured 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 preconfigured overrides, see Appendix C, "Command Line Overrides." For more information on the elements you can define within the init-param element, see "init-param".



address-provider

Used in: well-known-addresses

Description

Contains the configuration information for an address factory that implements the com.tangosol.net.AddressProvider interface.

Elements

Table A-3 describes the subelements you can define within 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 together with the <class-factory-name> element.

<class-factory-name>

Optional

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

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

<method-name>

Optional

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

<init-params>

Optional

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



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-4 describes the subelements you can define within the authorized-hosts element.

Table A-4 authorized-hosts Subelements

Element Required/Optional Description

<host-address>

Optional

Specifies an IP address or hostname. If any are specified, only hosts with specified host-addresses or within the specified host-ranges will be 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 will be 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 will be passed the java.net.InetAddress of the client. Implementations should return true to allow the new member to join the cluster.


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


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 will use 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-5 describes the elements you can define within the cache-factory-builder-config element.

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

Element Required/Optional Description

<class-name>

Required

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

<init-params>

Optional

Contains initialization parameters for the cache factory builder implementation.



callback-handler

Used in: security-config.

Table A-6 describes the elements you can define within the callback-handler element.

Table A-6 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-7 describes the subelements you can define within the cluster-config element.

Table A-7 cluster-config Subelements

Element Required/Optional Description

<member-identity>

Optional

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

<unicast-listener>

Required

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

<multicast-listener>

Required

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

<tcp-ring-listener>

Required

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

<shutdown-listener>

Required

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

<service-guardian>

Required

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

<packet-speaker>

Required

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

<packet-publisher>

Required

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

<incoming-message-handler>

Required

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

<outgoing-message-handler>

Required

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

<authorized-hosts>

Optional

Specifies the hosts which are allowed to join the cluster.

<services>

Required

Specifies the declarative data for all available Coherence services.

<filters>

Optional

Specifies data transformation filters, which can be used to 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.

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


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 "Element Attributes" for more information on this attribute.


cluster-quorum-policy

Used in: <cluster-config>

Description

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

Element

Table A-8 describes the subelements you can define within the cluster-quorum-policy element.

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

Element Required/Optional Description

<timeout-survivor-quorum>

Optional

Specifies the minimum number of cluster members that must remain in order to terminate one or more cluster members due to a detected network timeout, irrespective of the root cause. 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>

The value must be a non-negative integer.

<class-name>

Optional

Specifies a class that provides custom quorum policies. This element cannot be used together 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 together with the <timeout-survivor-quorum> or <class-name> elements.

This element is used together 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-9 describes the elements you can define within the coherence element.

Table A-9 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 Chapter 34, "How to Manage Coherence Using JMX" 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.


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 "Element Attributes" for more information on this attribute


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.DefaultConfigurableCacheFactory 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). Typically, the DefaultConfigurableCacheFactory class is extended for such use cases.

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  dccf= new
   DefaultConfigurableCacheFactory("example-config.xml", loader0);
NamedCache cache = dccf.ensureCache("dist-example", loader0);
cache.put(key, value);

//load the second cache configuration and use a cache

ConfigurableCacheFactory  dccf1= new
   DefaultConfigurableCacheFactory("example-config1.xml", loader1);
NamedCache cache1 = dccf1.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-10 describes the elements you can define within the configurable-cache-factory-config element.

Table A-10 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. Default value is com.tangosol.net.DefaultConfigurableCacheFactory.

<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 will be used to find the specified descriptor. Preconfigured is tangosol.coherence.cacheconfig. See Appendix C, "Command Line Overrides" for more information on overrides.


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 "Element Attributes" for more information on this attribute.


filters

Used in: cluster-config.

Description

Data transformation filters can be used by services to apply a custom transformation on data being transferred between cluster nodes. This can be used for instance to compress or encrypt Coherence 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-11 describes the elements you can define within each filters element.

Table A-11 filters 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. The content override attribute 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.

<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 which implement the com.tangosol.run.xml.XmlConfigurable interface. 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, refer to Chapter 9, "Using Network Filters."


The content override attributes id and 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 "Element Attributes" for more information on these attributes.

Compression Filter Parameters

The compression filters (com.tangosol.net.CompressionFilter), supports the parameters described in Table A-12 (see java.util.zip.Deflater for details).

Table A-12 Compression Filter Parameters

Parameter Name Value Description

buffer-length

Specifies compression buffer length in bytes.

Legal values are positive integers or zero.

Default value is 0.

level

Specifies the compression level. Legal values are:

  • default

  • compression

  • speed

  • none

Default value is default.

strategy

Specifies the compressions strategy. Legal values are:

  • gzip

  • huffman-only

  • filtered

  • default

Default value is gzip.



flow-control

Used in: packet-delivery.

Description

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

Remote GC Detection

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

Packet Throttling

Flow control allows Coherence to dynamically adjust the rate at which packets are transmitted to a given cluster node based on point to point transmission statistics.

Elements

Table A-13 describes the elements you can define within the flow-control subelement.

Table A-13 flow-control Subelements

Element Required/Optional Description

<enabled>

Optional

Specifies if flow control is enabled. Default is true

<pause-detection>

Optional

Defines the number of packets that will be resent to an unresponsive cluster node before assuming that the node is paused.

<outstanding-packets>

Optional

Defines the number of unconfirmed packets that will be sent to a cluster node before packets addressed to that node will be 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-14 describes the elements you can define within each host-range element.

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


The content override attribute id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document. See "Element Attributes" for more information on this attribute.


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 in order to establish a user's identity and is used on a Coherence*Extend proxy server. The identity asserter is used together 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-15 describes the elements you can define within the <identity-asserter> element.

Table A-15 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 together 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 together with the <class-name> element.

This element can be used together with the <method-name> element.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which will perform 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 is unable to present authentication credentials.

Elements

Table A-16 describes the elements you can define within the identity-manager element.

Table A-16 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 together 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-17 describes the elements you can define within the <identity-transformer> element.

Table A-17 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 together 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 together with the <class-name> element.

This element can be used together with the <method-name> element.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which will perform 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-18 describes the subelements you can define within the incoming-message-handler element.

Table A-18 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 will be closer between multiple systems running in the cluster; however, the process of joining the cluster will be 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 it is possible that a larger value would be necessary. Default value is 16.

<use-nack-packets>

Required

Specifies whether the packet receiver will use 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. Default value is true.

<priority>

Required

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

<packet-pool>

Required

Specifies how many incoming packets Coherence will buffer before blocking.


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 "Element Attributes" for more information on this attribute.


init-param

Used in: init-params.

Description

Defines an individual initialization parameter.

Elements

Table A-19 describes the elements you can define within the init-param element.

Table A-19 init-param Subelement

Element Required/Optional Description

<param-name>

Optional

Specifies the name of the parameter passed to the class. The param-type or param-name must be specified. For example: thread-count. For more information on the pre-defined parameter values available for the specific elements, refer to Initialization Parameter Settings.

<param-type>

Optional

Specifies the data type of the parameter passed to the class. The param-type or param-name must be specified. For example: int

<param-value>

Required

Specifies the value passed in the parameter. For example: 8. For more information on the pre-defined parameter values available for the specific elements, refer to Initialization Parameter Settings.


The content override attribute id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document. See "Element Attributes" for more information no this attribute.


init-params

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

Description

Defines a series of initialization parameters.

Elements

Table A-20 describes the elements you can define within the init-params element.

Table A-20 init-params Subelement

Element Required/Optional Description

<init-param>

Optional

Defines an individual initialization parameter.



instance

Used in: socket-provider, service-failure-policy

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-21 describes the elements you can define within the instance element.

Table A-21 instance Subelements

Element Required/Optional Description

<class-name>

Optional

Specifies the fully qualified name of an implementation class.

This element cannot be used together 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 together with the <class-name> element and is used together with the <method-name> element.

<method-name>

Optional

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

<init-params>

Optional

Contains class initialization parameters for the implementation class.



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-22 describes the elements you can define within the key-store element.

Table A-22 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-23 describes the elements you can define within the license-config element.

Table A-23 license-config Subelements

Element Required/Optional Description

<edition-name>

Optional

Specifies the product edition that the member will use. This allows multiple product editions to be used within the same cluster, with each member specifying the edition that it will be using. Valid values are: GE (Grid Edition), EE (Enterprise Edition), SE (Standard Edition), RTC (Real-Time Client), DC (Data Client). Default value is GE.

<license-mode>

Optional

Specifies whether the product is being used in an 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. Default value is dev.



logging-config

Used in: coherence.

Elements

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

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

  • a file name

If jdk is specified as the destination, Coherence must be run using JDK 1.5 or later. 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. Preconfigured override is tangosol.coherence.log. See Appendix C, "Command Line Overrides" for more information.

<logger-name>

Optional

Specifies a logger name within chosen logging system that should be used to log Coherence related messages. This value is only used by the JDK and log4j logging systems.

Default value is Coherence.

Preconfigured override is tangosol.coherence.log.logger. See Appendix C, "Command Line Overrides" for more information.

<severity-level>

Required

Specifies which logged messages will be output to the log destination. Legal values are:

  • 0—only output without a logging severity level specified will be logged

  • 1—all the above plus errors

  • 2—all the above plus warnings

  • 3—all the above plus informational messages

  • 4-9—all the above plus internal debugging messages (the higher the number, the more the messages)

  • -1—no messages

Default value is 3. Preconfigured override is tangosol.coherence.log.level. See Appendix C, "Command Line Overrides" for more information.

<message-format>

Required

Specifies how messages that have a logging level specified will be formatted before passing them to the log destination. The value of the message-format element is static text with the following replaceable parameters:

  • {date}—the date/time format (to a millisecond) at which the message was logged

  • {version}—the Oracle Coherence exact version and build details

  • {level}—the logging severity level of the message

  • {thread}—the thread name that logged the message

  • {member}—the cluster member id (if the cluster is currently running)

  • {location}—the fully qualified cluster member id: cluster-name, site-name, rack-name, machine-name, process-name and member-name (if the cluster is currently running)

  • {role}—the specified role of the cluster member

  • {text}—the text of the message

Default value is:

{date} Oracle Coherence {version} <{level}> (thread={thread}, member={member}): {text}

<character-limit>

Required

Specifies the maximum number of characters that the logger daemon will process from the message queue before discarding all remaining messages in the queue. Note that the message that caused the total number of characters to exceed the maximum will NOT be truncated, and all messages that are discarded will be summarized by the logging system with a single log entry detailing the number of messages that were discarded and their total size. The truncation of the logging is only temporary, since when the queue is processed (emptied), the logger is reset so that subsequent messages will be logged.

The purpose of this setting is to avoid a situation where logging can itself prevent recovery from a failing condition. For example, with tight timings, logging can actually change the timings, causing more failures and probably more logging, which becomes a vicious cycle. A limit on the logging being done at any one point in time is a "pressure valve" that prevents such a vicious cycle from occurring. Note that logging occurs on a dedicated low-priority thread to even further reduce its impact on the critical portions of the system.

Legal values are positive integers or zero. Zero implies no limit.

Default value in production mode is 4096 and 2147483647 in development mode. Preconfigured override is tangosol.coherence.log.limit. For more information, see Appendix C, "Command Line Overrides"


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 "Element Attributes" for more information on this attribute.


management-config

Used in: coherence.

Elements

Table A-25 describes the elements you can define within the management-config element.

Table A-25 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—No MBean server is instantiated.

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

  • remote-only—Manage MBeans on other remotely manageable cluster nodes. See <allowed-remote-management> subelement. Requires Coherence Enterprise Edition or higher

  • all—Manage both local and remotely manageable cluster nodes. See <allowed-remote-management> subelement. Requires Coherence Enterprise Edition or higher.

Default value is none. Preconfigured override is tangosol.coherence.management. See Appendix C, "Command Line Overrides" for more information.

<allow-remote-management>

Required

Specifies whether this cluster node exposes its managed objects to remote MBean server(s). Legal values are: true or false. Default value is true. Preconfigured override is tangosol.coherence.management.remote. See Appendix C, "Command Line Overrides" for more information.

<refresh-policy>

Optional

Specifies the method which is used to refresh remote management information.

Legal values are: refresh-ahead, refresh-behind or refresh-expired.

Default value is refresh-ahead.

Preconfigured override is tangosol.coherence.management.refresh.policy

<refresh-expiry>

Optional

Specifies the time interval (in milliseconds) after which a remote MBean information will be invalidated on the management node.

Legal values are strings representing time intervals.

Default value is 1s.

Preconfigured override is tangosol.coherence.management.refresh.expiry

<refresh-timeout>

Optional

Specifies the duration which the management node will wait 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.

Default value is 250ms.

Preconfigured 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. Default value is false. Preconfigured override is tangosol.coherence.management.readonly. See Appendix C, "Command Line Overrides"

<default-domain-name>

Optional

Specifies the default domain name for the MBean server that is used to register MBeans exposed by the Coherence management framework. This value is only used by the cluster nodes that have an in-process MBean server and allow management of local or other node's managed objects. If this value is not specified, the first existing MBean server is used.

This element is also used when implementing the MBeanServerFinder interface. See the <service-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.

<service-factory>

Optional

Contains the configuration information for the MBeanServer factory that implements the com.tangosol.net.management.MBeanServerFinder interface, which is used to find an MBean server that should be used by the Coherence JMX framework to register new or locate existing MBeans. 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.


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 "Element Attributes" for more information..


mbean

Used in: mbeans

Description

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

Elements

Table A-26 describes the subelements you can define within the mbean element.

Table A-26 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 together 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 together with the <mbean-accessor> element.

This element cannot be used together 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 together with the <mbean-class> element or the <mbean-factory> element.

<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 as it will be registered with the Coherence management framework. The prefix should be a comma-separated 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 or not 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 MBeanServer and is not accessible by other cluster nodes. If set to false, the nodeId=... key attribute is added to its name and the MBean will be visible from any of the managing nodes (nodes that set the <managed-nodes> element to values of all or remote-only).

Default value is false.

<enabled>

Optional

Specifies whether or not the MBean should be instantiated and registered on this instance. Valid values are true or false.

Default value is false.

<extend-lifecycle>

Optional

Specifies whether or not 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.

Default value is false.



mbeans

Used in: management-config

Description

The mbeans element is the root element for defining custom mbeans and is typically 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-27 describes the elements you can define within the mbeans element.

Table A-27 Subelement of mbeans

Element Required/Optional Description

<mbean>

Required

Specifies the MBean type, implementation, and ObjectName that will be 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:

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

Elements

Table A-43 describes the subelements you can define within the mbean-filter element.

Table A-28 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 together with the <class-factory-name> element.

<class-factory-name>

Optional

Specifies a factory class for creating filter instances.

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

This element can be used together with the <method-name> element.

<method-name>

Optional

Specifies the name of a static factory method on the factory class which will perform 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-29 describes the elements you can define within the member-identity element.

Table A-29 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. It is strongly suggested that cluster-name be specified for production systems, thus preventing accidental cluster discovery among applications. Preconfigured override is tangosol.coherence.cluster. See Appendix C, "Command Line Overrides" for more information.

<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, and 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 name is also useful for displaying management information (for example, JMX) and interpreting log entries. This element is not currently used to make decisions about data backup location. Preconfigured override is tangosol.coherence.site. See Appendix C, "Command Line Overrides" for more information.

<rack-name>

Optional

The rack-name element contains the name of the location within a geographic site that the member is hosted at. This is often a cage, rack or bladeframe identifier, and 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 name is also useful for displaying management information (for example, JMX) and interpreting log entries. This element is not currently used to make decisions about data backup location. Preconfigured override is tangosol.coherence.rack. See Appendix C, "Command Line Overrides" for more information.

<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 machine-name is used as the basis for creating a machine-id, which in turn is used to guarantee that data are backed up on different physical machines 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. Preconfigured override is tangosol.coherence.machine. See Appendix C, "Command Line Overrides" for more information.

<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 machine. 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 will exist per JVM, and in that situation this name would be redundant. Preconfigured override is tangosol.coherence.process. See Appendix C, "Command Line Overrides" for more information.

<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 machine (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. Preconfigured override is tangosol.coherence.member. see Appendix C, "Command Line Overrides" for more information.

<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. Preconfigured override is tangosol.coherence.role. See Appendix C, "Command Line Overrides" for more information.

<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 will be 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 will be ejected. Valid values are from 1 to 10. Preconfigured override is tangosol.coherence.priority. See Appendix C, "Command Line Overrides" for more information.



message-pool

Used in: outgoing-message-handler

Description

The <message-pool> element is used to control how many message buffers are pooled for message transmission. Pooling message buffers relieves the pressure on the JVM garbage collector by pooling the memory resources needed for messaging.

The message pool is comprised of any number of segments of a specified size. For example, a pool with 4 segments and a segment size of 10MB can hold, at most, 40 MB of space for serialization. The number of segments and the segment size are defined using the <segment> and <segment-size> elements, respectively.

Each pool segment stores message buffers of a specific size. The smallest size buffer is defined by the <min-buffer-size> element. The next buffer size for the next segment is then calculated using bitwise left shift using the <growth-factor> value ('min-buffer-size' << growth-factor). A left shift by n is equivalent to multiplying by 2n; where n is the growth factor value. For a growth factor of 2, multiply the minimum buffer size by 4. For a growth factory of 3, multiply the minimum buffer size by 8, and so on.

For example, the default pool values that are shown in Table A-30 results in a message pool were: the first pool segment contains message buffers of 1KB; the second pool segment contains message buffers of 4KB; the third pool segment contains message buffers of 16KB; and the fourth pool segment contains message buffers of 64KB. Using the same default values but increasing the growth factor to 3, results in buffer sizes of 1KB, 8KB, 64KB, and 512KB.

Space that is claimed for network buffers (in and out) and serialization buffers is periodically reclaimed when the capacity is higher than the actual usage.

Elements

Table A-30 describes the elements you can define within the message-pool element.

Table A-30 message-pool Subelements

Element Required/Optional Description

<segments>

Optional

Specifies the number of segments used by the message pool to store buffers. Each segment stores buffers of a specific size. The buffer size difference between segments is calculated using the <growth-factor> element value.

Default value is 4.

<segment-size>

Optional

Specifies the maximum size of a single pool segment. The maximum size of the entire pool is the total number of segments times the maximum size of a segment.

Default value is 16MB.

<min-buffer-size>

Optional

Specifies the smallest available buffer size to be stored in a segment. This value must be a multiple of 1024. Therefore, the smallest possible buffer is 1024 bytes.

Default value is 1KB.

<growth-factor>

Optional

Specifies the rate of growth (as bitwise left shift) between successive segments.

Default value is 2.



multicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Multicast listener. This element is used to specify the address (see <address> subelement) and port (see <port> subelement) that a cluster will use 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.

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. If you are having difficulties in establishing a cluster by using multicast, see Chapter 43, "Performing a Multicast Connectivity Test."

Elements

Table A-31 describes the elements you can define within the multicast-listener element.

Table A-31 multicast-listener Subelements

Element Required /Optional Description

<address>

Required

Specifies the multicast IP address that a Socket will listen or publish on. Legal values are from 224.0.0.0 to 239.255.255.255. Default value depends on the release and build level and typically follows the convention of {build}.{major version}.{minor version}.{patch}. For example, for Coherence Release 2.2 build 255 it is 225.2.2.0. Preconfigured is tangosol.coherence.clusteraddress. See Appendix C, "Command Line Overrides" for more information.

<port>

Required

Specifies the port that the Socket will listen or publish on. Legal values are from 1 to 65535. Default value depends on the release and build level and typically follows the convention of {version}+{{{build}. For example, for Coherence Release 2.2 build 255 it is 22255. Preconfigured override is tangosol.coherence.clusterport. See Appendix C, "Command Line Overrides" for more information.

<interface>

Optional

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

WARNING: With rare exception, use of this particular option is strongly discouraged, as it can lead to a condition known as "partial failure." Partial failure occurs when some portion of the cluster communication is working and other cluster communication has failed. Partial failure can occur when using this option, because the interface (and thus network) used for multicast traffic can be different from the interface (and thus network) used for unicast (UDP/IP) and TCP-ring (TCP/IP) traffic. If one interface (or network) fails, some communication can continue to succeed, while other communication fails, which may cause failover to take longer to occur. Since clustering handles node (and thus interface) failure, it is preferable to have all communication fail together, and thus the use of this option is strongly discouraged.

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

Default value is 4. Preconfigured override is tangosol.coherence.ttl. See Appendix C, "Command Line Overrides" for more information.

<packet-buffer>

Required

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

<priority>

Required

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

<join-timeout-milliseconds>

Required

Specifies the number of milliseconds that a new member will wait without finding any evidence of a cluster before starting its own cluster and electing itself as the senior cluster member. Legal values are from 1 to 1000000.

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

<multicast-threshold-percent>

Required

Specifies the threshold percentage value used to determine whether a packet will be 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 will be sent multicast if and only if the following both hold true:

  1. The packet is being sent over the network to more than one other node, 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 will allow the implementation to use multicast for basically all multi-point traffic.

    Setting it to 100 will force 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 will never be exceeded. With the setting of 25 the implementation will send 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.

Note: This element is only used if the well-known-addresses element is empty. Legal values are from 1 to 100. Default value is 25.


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 "Element Attributes" for more information on this attribute.


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.

Batched Acknowledgments

Rather then sending an individual ACK for each received packet which requires confirmation, Coherence will batch a series of acknowledgments for a given sender into a single ACK. The <ack-delay-milliseconds> specifies the maximum amount of time that an acknowledgment will be delayed before an ACK notification is sent. By batching the acknowledgments Coherence avoids wasting network bandwidth with many small ACK packets.

Negative Acknowledgments

When enabled cluster nodes will use packet ordering to perform early packet loss detection (see the <use-nack-packets> subelement of <incoming-message-handler>). This allows Coherence to identify a packet as likely being lost and retransmit it well before the packets scheduled (see the <resend-milliseconds> subelement of <packet-delivery>).

Elements

The following table describes the elements you can define within the notification-queuing element.

Table A-32 notification-queuing Subelements

Element Required/Optional Description

<ack-delay- milliseconds>

Required

Specifies the maximum number of milliseconds that the packet publisher will delay 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. Default value is 16.

<nack-delay- milliseconds>

Required

Specifies the number of milliseconds that the packet publisher will delay before sending a NACK packet. 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-33 describes the elements you can define within the outgoing-message-handler element.

Table A-33 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 <filters> element for detailed information on defining a filter.

<message-pool>

Optional

Specifies the size of the message buffer pool.



outstanding-packets

Used in: flow-control.

Description

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

Auto Tuning

The value may be specified as either an explicit number by using the maximum-packets element, or as a range by using both the maximum-packets and minimum-packets elements. When a range is specified, this setting will be dynamically adjusted based on network statistics.

Elements

Table A-34 describes the elements you can define within the outstanding-packets element.

Table A-34 outstanding-packets Subelements

Element Required/Optional Description

<maximum-packets>

Optional

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

<minimum-packets>

Optional

The lower bound on the range for the number of unconfirmed packets that will be sent to a cluster node before packets addressed to that node will be deferred. It is recommended that this value not be set below 16. Default 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.

Performance Impact

Large inbound buffers help insulate the Coherence network layer from JVM pauses caused by the Java Garbage Collector. While the JVM is paused, Coherence is unable to dequeue packets from any inbound socket. If the pause is long enough to cause the packet buffer to overflow, the packet reception will be delayed as the originating node will need to detect the packet loss and retransmit the packet(s).

It's just a hint

The operating system will only treat the specified value as a hint, and is not required to allocate the specified amount. In the event that less space is allocated then requested Coherence will issue a warning and continue to operate with the constrained buffer, which may degrade performance. See Chapter 45, "Performance Tuning," for details on configuring your operating system to allow larger buffers.

Latency Versus Throughput

When setting this for transmit (that is, within <packet-publisher>), higher values may allow for increased throughput, while lower values may allow for decreased latency. If you make any changes to this value, it is recommended that you evaluate how it effects performance in all of these dimensions.

Elements

Table A-35 describes the elements you can define within the packet-buffer element.

Table A-35 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 will be 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. Defaults 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.

Default Configuration

The default packet-bundling settings are minimally aggressive allowing for bundling to occur without adding a measurable delay. The benefits of more aggressive bundling will be based on the network infrastructure and the application object's typical data sizes and access patterns.

Elements

Table A-36 describes the elements you can define within the packet-bundling element.

Table A-36 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 will result in the algorithm not waiting, and only bundling the readily accessible packets. A value greater than zero will cause 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.

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 will be allow for high packet utilization while keeping latency to a minimum.

Default value is zero.



packet-delivery

Used in: packet-publisher.

Description

Specifies timing and transmission rate parameters related to packet delivery.

Death Detection

The <timeout-milliseconds> and <heartbeat-milliseconds> subelements are used in detecting the death of other cluster nodes.

Elements

Table A-37 describes the elements you can define within the packet-delivery element.

Table A-37 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. Default value is 200.

<timeout-milliseconds>

Required

For packets which require confirmation, specifies the maximum amount of time, in milliseconds, that a packet will be resent. After this timeout expires Coherence will make a determination if the recipient is to be considered "dead". This determination takes additional data into account, such as if other nodes are still able to communicate with the recipient. 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. Default value is 1000.

<flow-control>

Optional

Configures per-node packet throttling and remote GC detection.

<packet-bundling>

Optional

Configures how aggressively Coherence will attempt to maximize packet utilization.



packet-pool

Used in: incoming-message-handler, packet-publisher.

Description

A pool of packets that Coherence internally maintains for use in transmitting and receiving UDP packets. Unlike the packet-buffer, these buffers are managed by Coherence rather then the operating system, and allocated on the JVM's heap.

Performance Impact

The packet pools are used as a reusable buffer between Coherence network services. For packet transmission, this defines the maximum number of packets which can be queued on the packet-speaker before the packet-publisher must block. For packet reception, this defines the number of packets which can be queued on the incoming-message-handler before the unicast-listener, and multicast-listener must block.

Elements

Table A-38 describes the subelements you can define within the packet-pool element.

Table A-38 packet-pool Subelements

Element Required/Optional Description

<size>

Required

Specifies the maximum size of the pool of reusable packets to be utilized by the services responsible for publishing and receiving described in bytes. The pools are initially empty, and will grow on demand up to the specified limits.

The default value is 16MB for both transmitting and receiving.



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 will be retransmitted (see <packet-delivery> subelement). The recipient node will delay the ACK, to batch a series of ACKs into a single response (see <notification-queuing> subelement).

Throttling

The rate at which the publisher will accept and transmit packet may be controlled by using the traffic-jam and flow-control settings. Throttling may be necessary when dealing with slow networks, or small packet-buffer.

Elements

Table A-39 describes the elements you can define within the packet-publisher element.

Table A-39 packet-publisher Subelements

Element Required/Optional Description

<enabled>

Optional

Specifies if TCMP clustering is enabled. For Coherence editions which support 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. Default value is true. Preconfigured override is tangosol.coherence.tcmp.enabled. See Appendix C, "Command Line Overrides" for more information.

<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 will be requested to buffer. The value may be expressed either in terms of packets of bytes.

<packet-pool>

Required

Specifies how many outgoing packets Coherence will buffer before blocking.

<priority>

Required

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


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 "Element Attributes" for more information.


packet-size

Used in: packet-publisher.

Description

The packet-size element specifies the maximum and preferred UDP packet sizes (see the <maximum-length> and <preferred-length> subelements). All cluster nodes must use identical maximum packet sizes. For optimal network utilization this value should be 32 bytes less then the network MTU.

Note:

When specifying a UDP packet size larger then 1024 bytes on Microsoft Windows a registry setting must be adjusted to allow for optimal transmission rates. See "Datagram size (Microsoft Windows)" for details.

Elements

Table A-40 describes the subelements you can define within the packet-size element.

Table A-40 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 artifically 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 will be sent and received on the unicast and multicast sockets.

This value can be larger or smaller then the <maximum-length> value, and need not be the same for all cluster members. The ideal value is one which will fit within the network MTU, leaving enough space for either the UDP or TCP packet headers, which are 32, and 52 bytes respectively.

This value should be at least 512, and defaults to a value based on the local nodes MTU. An MTU of 1500 is assumed if the MTU cannot be obtained.



packet-speaker

Used in: cluster-config.

Description

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

Offloaded Transmission

The Packet speaker is responsible for sending packets on the network. The speaker is used when the packet-publisher detects that a network send operation is likely to block. This allows the Packet publisher to avoid blocking on IO and continue to prepare outgoing packets. The Publisher will dynamically choose whether to use the speaker as the packet load changes.

Elements

Table A-41 describes the subelements you can define within the packet-speaker element.

Table A-41 packet-speaker Subelements

Element Required/Optional Description

<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. Default value is 8.


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 "Element Attributes" for more information on this attribute.


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 will be 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-42 describes the subelements you can define within the pause-detection element.

Table A-42 pause-detection Subelements

Element Required/Optional Description

<maximum-packets>

Optional

The maximum number of packets that will be resent to an unresponsive cluster node before assuming that the node is paused. Specifying a value of 0 will disable pause detection. Default 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-43 describes the subelements you can define within the provider element.

Table A-43 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 together 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 together with the <name> element or the <class-name> element.

This element can be used together with the <method-name> element.

<method-name>

Optional

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

<init-params>

Optional

Contains class initialization parameters for the provider implementation.

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



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-44 describes the subelements you can define within the reporter element.

Table A-44 reporter Subelements

Element Required/Optional Description

<configuration>

Required

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

<autostart>

Required

Specifies whether or not the Reporter automatically starts when the node starts. Valid values are true and false.

Default value is false.

<distributed>

Required

Specifies whether or not the reporter runs on multiple management nodes. Valid values are true and false.

Default value is false.



security-config

Used in: coherence.

Elements

Table A-45 describes the subelements you can define within the security-config element.

Table A-45 security-config Subelements

Element Required/Optional Description

<enabled>

Required

Specifies whether the security features are enabled. All other configuration elements in the security-config group will be verified for validity and used if and only if the value of this element is true. Legal values are true or false. Default value is false. Preconfigured override is tangosol.coherence.security. See Appendix C, "Command Line Overrides" for more information.

<login-module-name>

Required

Specifies the name of the JAAS LoginModule that should be used to authenticate the caller. This name should match a module in a configuration file will be used by the JAAS (for example specified by using the -Djava.security.auth.login.config Java command line attribute). For details please refer to the Sun Login Module Developer's Guide.

<access-controller>

Required

Contains the configuration information for the class that implements com.tangosol.net.security.AccessController interface, which will be 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 will be 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 in order to establish a user's identity. An identity asserter is used together 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 together with an identity asserter to protect connections between Coherence*Extend clients and proxies.

<subject-scope>

Optional

Specifies whether or not 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 will get a different reference.

Default value is false.


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 "Element Attributes" for more information.


serializers

Used in: cluster-config

Description

The serializers element contains any number of serializer class configurations. Serializer classes must implement com.tangosol.io.Serializer. Each serializer class is defined within a serializer subelement. The operational configuration file contains a default Java and POF serializer class configuration:

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

Serializers that are defined in the operational configuration can be 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-46 describes the subelements you can define within the serializer element.

Table A-46 serializer Subelements

Element Required/Optional Description

<class-name>

Optional

Specifies a class that implements com.tangosol.io.Serializer. This element cannot be used together 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 together with the <class-name> element. This element can be used together with the <method-name> element.

<method-name>

Optional

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

<init-params>

Optional

Contains class initialization parameters for the serializer implementation.



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-47 describes the subelements you can define within the service-guardian element.

Table A-47 service-guardian Subelements

Element Required/Optional Description

<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. A timeout of 0 will disable service guardians.

Default value is 305000.

Preconfigured override is tangosol.coherence.guard.timeout

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

Default value is exit-cluster.


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 "Element Attributes" for more information.


services

Used in: cluster-config.

Description

Specifies the configuration for Coherence services.

Service Components

The types of services which can be configured includes:

Elements

Table A-48 describes the subelements you can define for each services element.

Table A-48 services 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:

  • ReplicatedCache

  • ReplicatedCache.Optimistic

  • DistributedCache

  • SimpleCache

  • LocalCache

  • InvocationService

<use-filters>

Optional

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

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

will activate 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-component. For more service specific parameter information see:


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

Initialization Parameter Settings

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

The following sections describe the parameters that can be configured for these services and filters:

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

For example, the sample entry in Table A-49 means that the init-params element may look like the configuration in Example A-2 or Example A-3.

Table A-49 Sample Table Entry

Parameter Value Value Description

local-storage

Specifies whether this member of the DistributedCache service enables the local storage. Legal values are true or false. Default value is true. Preconfigured override is tangosol.coherence.distributed.localstorage. See Appendix C, "Command Line Overrides" for more information.


Example A-2 Sample init-param Configuration

...
<init-params>
  <init-param>
    <param-name>local-storage</param-name>
    <param-value>false</param-value>
  </init-param>
</init-params>
...

or as follows:

Example A-3 Another Sample init-param Configuration

...
<init-params>
  <init-param>
    <param-name>local-storage</param-name>
    <param-value>true</param-value>
  </init-param>
</init-params>
...
DistributedCache Service Parameters

DistributedCache <services> elements support the parameters described in Table A-50. These settings may also be specified as part of the <distributed-scheme> element in the coherence-cache-config.xml descriptor.

Table A-50 DistributedCache Service Parameters

Parameter Name Value, Description

backup-count

Specifies the number of members of the DistributedCache service that hold the backup data for each unit of storage in the cache. Value of 0 means that in the case of abnormal termination, some portion of the data in the cache will be lost. Value of N means that if up to N cluster nodes terminate immediately, the cache data will be preserved. To maintain the distributed cache of size M, the total memory usage in the cluster does not depend on the number of cluster nodes and will be in the order of M*(N+1).

Recommended values are 0, 1 or 2.

Default value is 1.

backup-storage/class-name

Only applicable with the custom type. Specifies a class name for the custom storage implementation. If the class implements com.tangosol.run.xml.XmlConfigurable interface then upon construction the setConfig method is called passing the entire backup-storage element.

backup-storage/directory

Only applicable with the file-mapped type. Specifies the path name for the directory that the disk persistence manager (com.tangosol.util.nio.MappedBufferManager) will use as "root" to store files in. If not specified or specifies a non-existent directory, a temporary file in the default location is used.

Default value is the default temporary directory designated by the Java runtime.

backup-storage/initial-size

Only applicable with the off-heap and file-mapped types.Specifies the initial buffer size in bytes.The value of this element must be in the following format: [\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]? where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed.

Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes).

Default value is 1MB.

backup-storage/maximum-size

Only applicable with the off-heap and file-mapped types.Specifies the maximum buffer size in bytes.The value of this element must be in the following format: [\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]? where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed.

Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes).

Default value is 1024MB.

backup-storage/scheme-name

Only applicable with the scheme type. Specifies a scheme name for the ConfigurableCacheFactory.

backup-storage/type

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

Default value is on-heap.

Preconfigured override is tangosol.coherence.distributed.backup. See Appendix C, "Command Line Overrides" for more information.

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.

lease-granularity

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

  • thread

  • member

A value of thread means that locks are held by a thread that obtained them and can only be released by that thread. A value of member means that locks are held by a cluster node and any thread running on the cluster node that obtained the lock can release it.

Default value is thread.

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. Default value is true.

Preconfigured override is tangosol.coherence.distributed.localstorage. See Appendix C, "Command Line Overrides" for more information.

partition-count

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

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

The following are good defaults based on service storage sizes:

service storage       partition-count
_______________       ______________
   100M                    257
     1G                    509
    10G                   2039
    50G                   4093
   100G                   8191

A list of first 1,000 primes can be found at:

http://primes.utm.edu/lists/

Valid values are positive integers. The default value is 257.

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.

request-timeout

Specifies the maximum amount of time a client will wait for a response before abandoning the original request. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes the following:

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

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

Legal values are positive integers or zero (indicating no default timeout).

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 don't 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).

thread-count

Specifies the number of daemon threads used by the distributed cache service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero.

Default value is 0. Preconfigured override is tangosol.coherence.distributed.threads. See Appendix C, "Command Line Overrides" for more information.

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

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 will make the distribution process take longer, but will reduce network bandwidth utilization during this activity.

Legal values are integers greater then zero.

Default value is 512 (0.5MB). Preconfigured override is tangosol.coherence.distributed.transfer. See Appendix C, "Command Line Overrides" for more information.



ReplicatedCache Service Parameters

ReplicatedCache services elements support the parameters described in Table A-51. These settings may also be specified as part of the replicated-scheme element in the coherence-cache-config.xml descriptor.

Table A-51 ReplicatedCache Service Parameters

Parameter Name Value Description

lease-granularity

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

  • thread

  • member

A value of thread means that locks are held by a thread that obtained them and can only be released by that thread. A value of member means that locks are held by a cluster node and any thread running on the cluster node that obtained the lock can release it.

Default value is thread.

mobile-issues

Specifies whether lease issues should be transferred to the most recent lock holders.

Legal values are true or false.

Default value is false.

standard-lease- milliseconds

Specifies the duration of the standard lease in milliseconds. When a lease has aged past this number of milliseconds, the lock will automatically be 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.

Default value is 0.



InvocationService Parameters

InvocationService services elements support the following parameters listed in Table A-52. These settings may also be specified as part of the invocation-scheme element in the coherence-cache-config.xml descriptor.

Table A-52 InvocationService Parameters

Parameter Name Value, Description

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 don't 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

Legal values are positive integers or zero (indicating no default timeout).

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

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 don't 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).

thread-count

Specifies the number of daemon threads to be used by the invocation service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero. Preconfigured override is tangosol.coherence.invocation.threads. See Appendix C, "Command Line Overrides" for more information.

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 compute. For example, if you run 4 nodes on a 16 core box, then there should be roughly 4 threads in the pool. For IO 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.



ProxyService Parameters

ProxyService services elements support the parameters described in Table A-53. These settings may also be specified as part of the proxy-scheme element in the coherence-cache-config.xml descriptor.

Table A-53 ProxyService Parameters

Parameter Name Value Description

thread-count

Specifies the number of daemon threads to be used by the proxy service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero.

Default value is 0.

Proxy service threads perform operations on behalf of the calling application. Therefore, set the value to as many threads as there are concurrent operations that are occurring.

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

Legal values are positive integers or zero (indicating no default timeout).

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 don't 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).




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-54 describes the elements you can define within the shutdown-listener element.

Table A-54 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—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. Default value is force. Preconfigured override is tangosol.coherence.shutdownhook. See Appendix C, "Command Line Overrides" for more information.


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 "Element Attributes" for more information.


socket-address

Used in: well-known-addresses.

Elements

Table A-55 describes the subelements you can define within the socket-address element.

Table A-55 socket-address Subelements

Element Required/Optional Description

<address>

Required

Specifies the IP address that a Socket will listen or publish on.

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

<port>

Required

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



socket-provider

Used in: socket-providers, unicast-listener.

Description

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

Socket providers that are defined within the <socket-providers> element can be referenced by a unicast listener configuration (see "unicast-listener"), individual cache scheme definitions (see "socket-provider") and by the default socket provider for services that do not explicitly define a socket provider (see "defaults").

Out-of-box, the following pre-defined socket provider configurations are included. Additional socket providers can be defined in an operational override file as required.

Elements

Table A-56 describes the subelements you can define within the socket-provider element.

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

<tcp>

Optional

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

<ssl>

Optional

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

<instance>

Optional

Contains the class configuration information for a com.tangosol.net.SocketProvider implementation.



socket-providers

Used in cluster-config

Description

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

Elements

Table A-57 describes the subelements you can define within the socket-providers element.

Table A-57 socket-providers Subelements

Element Required/Optional Description

<socket-provider>

Optional

Specifies the configuration information for a socket and channel factory that implements the com.tangosol.net.SocketProvider interface.



ssl

Used in: socket-provider.

Description

The <ssl> element contains the configuration information for a socket provider that produces socket and channel implementations which utilize SSL. If SSL is configured for the unicast listener, the listener must be configured to use well known addresses.

Elements

Table A-58 describes the elements you can define within the ssl element.

Table A-58 ssl Subelements

Element Required/Optional Description

<protocol>

Optional

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

<provider>

Optional

Specifies the configuration for a security provider instance.

<executor>

Optional

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

A <class-name> subelement is used to provide the name of a class that implements the Executor interface. As an alternative, a <class-factory-name> subelement can be used 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 will perform 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 hostname and the server's identification hostname mismatch, the verification mechanism will call back to this instance to determine if the connection should be allowed.

A <class-name> subelement is used to provide the name of a class that implements the HostnameVerifier interface. As an alternative, a <class-factory-name> subelement can be used 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 will perform object instantiation. Either approach can specify initialization parameters using the <init-params> element.



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 form a single "ring" of TCP connections spanning the entire cluster. A cluster node is able to use the TCP connection to detect the death of another node within a heartbeat interval (default is 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-59 describes the subelements you can define within the tcp-ring-listener element.

Table A-59 tcp-ring-listener Subelements

Element Required/Optional Description

<enabled>

Optional

Specifies whether the tcp ring listener should be enabled to defect node failures faster. Legal values are true and false. Default value is true. Preconfigured override is tangosol.coherence.tcpring. see Appendix C, "Command Line Overrides" for more information.

<ip-timeout>

Optional

Specifies the timeout to use for determining that a machine hosting cluster members has become unreachable. A number of connection attempts may be made before determining that the unreachable 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.

This feature relies upon the java.net.InetAddress.isReachable mechanism, see http://java.sun.com/j2se/1.5.0/docs/api/java/net/InetAddress.html#isReachable(int) for a description of how it will identify reachability.

Legal values are strings representing time intervals. A timeout of 0 disables machine-level monitoring and is not recommended.

The default value is 5s.

<ip-attempts>

Optional

specifies the number of connection attempts to make before determining that a machine 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.

Default value is O/S dependent.

<priority>

Required

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


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 "Element Attributes" for more information on this attribute.


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

Tuning

Specifying a limit which is to low, or a pause which is to long may result in the publisher transmitting all pending packets, and being left without packets to send. An ideal value will ensure that the publisher is never left without work to do, but at the same time prevent the queue from growing uncontrollably. It is therefore recommended that the pause remain quite short (10ms or under), and that the limit on the number of packets be kept high (that is, greater than 5000). As of Coherence 3.2 a warning will be periodically logged if this condition is detected.

Traffic Jam and Flow Control

When flow-control is enabled the traffic-jam operates in a point-to-point mode, only blocking a send if the recipient has too many packets outstanding. It is recommended that the traffic-jam/maximum-packets value be greater than the value (see the <maximum-packets> subelement of outstanding-packets). When flow-control is disabled, the traffic-jam will take all outstanding packets into account.

Elements

Table A-60 describes the subelements you can define within the traffic-jam element.

Table A-60 traffic-jam Subelements

Element Required/Optional Description

<maximum-packets>

Required

Specifies the maximum number of pending packets that the Publisher will tolerate 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. Default value is 8192.

<pause-milliseconds>

Required

Number of milliseconds that the Publisher will pause a client thread that is trying to send a message when the Publisher is clogged. The Publisher will not allow the message to go through until the clog is gone, and will repeatedly sleep the thread for the duration specified by this property. 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 will contain at least one child element.

Elements

Table A-61 describes the elements you can define within the trust-manager element.

Table A-61 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 will bind to, to listen for point-to-point cluster communications.

Automatic Address Settings

By default Coherence will attempt to obtain the IP to bind to using the java.net.InetAddress.getLocalHost() call. On machines with multiple IPs or NICs you may need to explicitly specify the address (see the <address> subelement). Additionally if the specified port is already in use, Coherence will by default auto increment the port number until the binding succeeds (see the <port> and <auto> subelements).

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. If you are having difficulties in establishing a cluster by using multicast, see Chapter 43, "Performing a Multicast Connectivity Test."

Elements

Table A-62 describes the subelements you can define within the unicast-listener element.

Table A-62 unicast-listener Subelements

Element Required/Optional Description

<well-known-addresses>

Optional

Contains a list of "well known" addresses (WKA) that are used by the cluster discovery protocol in place of multicast broadcast.

<machine-id>

Optional

Specifies an identifier that should uniquely identify each server machine. If not specified, a default value is generated from the address of the default network interface. The machine id for each machine in the cluster can be used by cluster services to plan for failover by making sure that each member is backed up by a member running on a different machine.

<address>

Required

Specifies the IP address that a Socket will listen or publish on. Note: The localhost setting may not work on systems that define localhost as the loopback address; in that case, specify the machine name or the specific IP address. Also, the multicast listener, by default, binds to the same interface as defined by this address.

Default value is localhost. Preconfigured override is tangosol.coherence.localhost. See Appendix C, "Command Line Overrides" for more information.

<port>

Required

Specifies the ports that the Socket will listen or publish on. A second port is automatically opened and defaults to the next available port. Legal values are from 1 to 65535. Default value is 8088 for the first port and 8089 (if available) for the second port. Preconfigured override is tangosol.coherence.localport. See Appendix C, "Command Line Overrides" for more information.

<port-auto-adjust>

Required

Specifies whether the unicast port will be automatically incremented if the specified port cannot be bound to because it is already in use. Legal values are true or false. Default value is true. Preconfigured override is tangosol.coherence.localport.adjust. See Appendix C, "Command Line Overrides" for more information.

<packet-buffer>

Required

Specifies how many incoming packets the operating system will be 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. Default value is 8.

<socket-provider>

Optional

Specifies the configuration information for a socket and channel factory that implements the com.tangosol.net.SocketProvider interface. The socket provider is used for TCMP communication. This element may also be used to refer to a socket provider configuration that is already defined within the <socket-providers> element. For example:

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

Preconfigured override is tangosol.coherence.cluster.socketprovider. See Appendix C, "Command Line Overrides" for more information.


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 "Element Attributes" for more information on this attribute.


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

When the packet load is relatively low it may be more efficient for the speaker's operations to be performed on the publisher's thread. When the packet load is high using the speaker allows the publisher to continue preparing packets while the speaker transmits them on the network.

Elements

Table A-63 describes the elements you can define within the packet-speaker element.

Table A-63 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 will force the speaker to always be used, while a very high value will cause it to never be used. If unspecified, it will be set to match the packet-buffer, this is the default.



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.

Use of the Well Known Addresses (WKA) feature is not supported by Standard Edition. If you are having difficulties in establishing a cluster by using multicast, see Chapter 43, "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

Example A-4 illustrates a configuration for two well-known-addresses with the default port.

Example A-4 Configuration for Two Well-Known-Addresses

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

Elements

Table A-64 describes the subelements you can define within the well-known-addresses element.

Table A-64 well-known-addresses Subelements

Element Required/Optional Description

<socket-address>

Optional

Specifies a list of WKA that are used by the cluster discovery protocol in place of multicast broadcast. If one or more WKA is specified, for a member to join the cluster it will either have to be a WKA or there will have to be at least one WKA member running. Additionally, all cluster communication will be performed using unicast. If empty or unspecified multicast communications will be used. Preconfigured overrides are tangosol.coherence.wka and tangosol.coherence.wka.port. See Appendix C, "Command Line Overrides" for more information.

<address-provider>

Optional

Contains the configuration for a com.tangosol.util.AddressProvider implementation that supplies the WKAs. The calling component will attempt 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.


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 "Element Attributes" for more information about this attribute.


Element Attributes

The optional id and xml-override attributes can be used to override the contents of an element. These attributes can appear, either individually or together, within the following elements:

Table A-65 lists the elements that can use id or xml-override, or both.

Table A-66 describes the functionality of the id and xml-override attributes.

Table A-66 id and xml-override Attribute Descriptions

Attribute Required/Optional Description

xml-override

Optional

Allows the content of this element to be fully or partially overridden with XML documents that are external to the base document. Legal value of this attribute is the resource name of such an override document that should be accessible using the ClassLoader.getResourceAsStream(String name) by the classes contained in coherence.jar library. In general that means that resource 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, <services>) the id attribute should be used to identify the base element that will be 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.

id

Optional

Used in conjunction with the xml-override attribute in cases where there are multiple elements with the same name (for example, <services>) to identify the base element that will be 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.