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.
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."
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.
The root element of the operational descriptor is <coherence> and is where a cluster and services are configured.
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.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.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.
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: |
|---|---|
|
root element |
|
|
access-controller, address-provider, callback-handler, configurable-cache-factory-config, filters, services |
|
|
socket-provider, service-failure-policy |
|
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 |
|---|---|---|
|
< |
Required |
Specifies the name of a Java class that implements |
|
< |
Optional |
Contains one or more initialization parameter(s) for a class that implements the
<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 |
Used in: well-known-addresses
Contains the configuration information for an address factory that implements the com.tangosol.net.AddressProvider interface.
Table A-3 describes the subelements you can define within the address-provider element.
Table A-3 address-provider Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
Specifies the fully qualified name of a class that implements the This element cannot be used together with the |
|
< |
Optional |
Specifies the fully qualified name of a factory class for creating address provider instances. The instances must implement the This element cannot be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Specifies initialization parameters which are accessible by implementations which support the |
Used in: cluster-config.
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.
Table A-4 describes the subelements you can define within the authorized-hosts element.
Table A-4 authorized-hosts Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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 |
|
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 |
|
|
|
Optional |
Specifies class configuration information for a |
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".
Used in: coherence
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");
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 |
|---|---|---|
|
|
Required |
Specifies the name of a Java class that implements the |
|
Optional |
Contains initialization parameters for the cache factory builder implementation. |
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 |
|---|---|---|
|
< |
Required |
Specifies the name of a Java class that provides the implementation for the |
|
Optional |
Contains one or more initialization parameter(s) for a |
Used in: <coherence>
Contains the cluster configuration information, including communication and service parameters.
Table A-7 describes the subelements you can define within the cluster-config element.
Table A-7 cluster-config Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Specifies detailed identity information that is useful for defining the location and role of the cluster member. |
|
|
Required |
Specifies the configuration information for the Unicast listener, used for receiving point-to-point network communications. |
|
|
Required |
Specifies the configuration information for the Multicast listener, used for receiving point-to-multipoint network communications. |
|
|
Required |
Specifies configuration information for the TCP Ring listener, used to death detection. |
|
|
Required |
Specifies the action to take upon receiving an external shutdown request. |
|
|
Required |
Specifies the configuration information for the service guardians, used for detecting and resolving service deadlock. |
|
|
Required |
Specifies configuration information for the Packet speaker, used for network data transmission. |
|
|
Required |
Specifies configuration information for the Packet publisher, used for managing network data transmission. |
|
|
Required |
Specifies configuration information for the Incoming message handler, used for dispatching incoming cluster communications. |
|
|
Required |
Specifies configuration information for the Outgoing message handler, used for dispatching outgoing cluster communications. |
|
|
Optional |
Specifies the hosts which are allowed to join the cluster. |
|
|
|
Required |
Specifies the declarative data for all available Coherence services. |
|
|
Optional |
Specifies data transformation filters, which can be used to perform custom transformations on data being transferred between cluster nodes. |
|
Optional |
Specifies any number of serializer class configurations that implement |
|
|
Required |
Contains socket provider definitions. |
|
|
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.
Used in: <cluster-config>
The cluster-quorum-policy element contains quorum policy settings for the Cluster service.
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 |
|---|---|---|
|
|
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 <timeout-survivor-quorum role="Server">50 </timeout-survivor-quorum> The value must be a non-negative integer. |
|
|
Optional |
Specifies a class that provides custom quorum policies. This element cannot be used together with the The class must implement the |
|
|
Optional |
Specifies a factory class for creating custom action policy instances. This element cannot be used together with the This element is used together with the |
root element
The coherence element is the root element of the operational deployment descriptor tangosol-coherence.xml.
Table A-9 describes the elements you can define within the coherence element.
Table A-9 coherence Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Required |
Contains the cluster configuration information. This element is where most communication and service parameters are defined. |
|
|
Required |
Contains the configuration information for the logging facility. |
|
|
Required |
Contains configuration information for the configurable cache factory, which controls from where and how the cache configuration settings are loaded. |
|
|
Required |
Contains the configuration information for a cache factory builder, which allows building and managing multiple cache factory configurations across multiple class loaders. |
|
|
Required |
Contains the configuration information for the coherence Management Framework. See Chapter 34, "How to Manage Coherence Using JMX" for more information. |
|
|
Optional |
Contains the configuration information for the Coherence Security Framework. |
|
|
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
Used in: coherence
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.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 |
|---|---|---|
|
< |
Required |
Specifies the name of a Java class that implements the |
|
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 . |
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.
Used in: cluster-config.
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.
Data transformation filters are implementations of the com.tangosol.util.WrapperStreamFactory interface.
Note:
Data transformation filters are not related tocom.tangosol.util.Filter, which is part of the Coherence API for querying caches.Table A-11 describes the elements you can define within each filters element.
Table A-11 filters Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the canonical name of the filter. This name is unique within the cluster. For example: |
|
< |
Required |
Specifies the class name of the filter implementation. This class must have a zero-parameter public constructor and must implement the |
|
Optional |
Specifies initialization parameters, for configuring filters which implement the <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.
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 |
|---|---|
|
|
Specifies compression buffer length in bytes. Legal values are positive integers or zero. Default value is 0. |
|
|
Specifies the compression level. Legal values are:
Default value is default. |
|
|
Specifies the compressions strategy. Legal values are:
Default value is gzip. |
Used in: packet-delivery.
The flow-control element contains configuration information related to packet throttling and 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.
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.
Table A-13 describes the elements you can define within the flow-control subelement.
Table A-13 flow-control Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
Specifies if flow control is enabled. Default is true |
|
Optional |
Defines the number of packets that will be resent to an unresponsive cluster node before assuming that the node is paused. |
|
|
Optional |
Defines the number of unconfirmed packets that will be sent to a cluster node before packets addressed to that node will be deferred. |
Used in: authorized-hosts.
Specifies a range of unicast addresses of nodes which are allowed to join the cluster.
Table A-14 describes the elements you can define within each host-range element.
Table A-14 host-range Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the starting IP address for a range of host addresses. For example: 198.168.1.1. |
|
< |
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.
Used in: security-config
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.
Table A-15 describes the elements you can define within the <identity-asserter> element.
Table A-15 identity-asserter Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies a class that implements |
|
|
Optional |
Specifies a factory class for creating asserter instances. The instances must implement This element can be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the asserter implementation. |
Used in: ssl.
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.
Table A-16 describes the elements you can define within the identity-manager element.
Table A-16 identity-manager Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the algorithm used by the identity manager. The default value is |
|
|
Optional |
Specifies the configuration for a security provider instance. |
|
Optional |
Specifies the configuration for a key store implementation. |
|
|
|
Required |
Specifies the private key password. |
Used in: security-config
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.
Table A-17 describes the elements you can define within the <identity-transformer> element.
Table A-17 identity-transformer Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies a class that implements |
|
|
Optional |
Specifies a factory class for creating asserter instances. The instances must implement This element can be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the transformer implementation. |
Used in: cluster-config.
The incoming-message-handler assembles UDP packets into logical messages and dispatches them to the appropriate Coherence service for processing.
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 |
|---|---|---|
|
< |
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. |
|
< |
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 |
|
< |
Required |
Specifies a priority of the incoming message handler execution thread. Legal values are from 1 to 10. Default value is 7. |
|
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.
Used in: init-params.
Defines an individual initialization parameter.
Table A-19 describes the elements you can define within the init-param element.
Table A-19 init-param Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
Specifies the name of the parameter passed to the class. The |
|
< |
Optional |
Specifies the data type of the parameter passed to the class. The |
|
< |
Required |
Specifies the value passed in the parameter. For example: |
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.
Used in: address-provider, filters, services, configurable-cache-factory-config, access-controller, and callback-handler.
Defines a series of initialization parameters.
Table A-20 describes the elements you can define within the init-params element.
Table A-20 init-params Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Defines an individual initialization parameter. |
Used in: socket-provider, service-failure-policy
The <instance> element contains the configuration of an implementation class or class factory that is used to plug in custom functionality.
Table A-21 describes the elements you can define within the instance element.
Table A-21 instance Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the fully qualified name of an implementation class. This element cannot be used together with the |
|
|
Optional |
Specifies the fully qualified name of a factory class for creating implementation class instances. This element cannot be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the implementation class. |
Used in: identity-manager, trust-manager.
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.
Table A-22 describes the elements you can define within the key-store element.
Table A-22 key-store Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Required |
Specifies the Uniform Resource Locator (URL) to a key store. |
|
|
Optional |
Specifies the password for the key store. |
|
|
Optional |
Specifies the type of a |
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 |
|---|---|---|
|
< |
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: |
|
< |
Optional |
Specifies whether the product is being used in an development or production mode. Valid values are |
Used in: coherence.
The following table describes the elements you can define within the logging-config element.
Table A-24 logging-config Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the output device used by the logging system. Legal values are:
If |
|
< |
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 Preconfigured override is |
|
< |
Required |
Specifies which logged messages will be output to the log destination. Legal values are:
Default value is |
|
< |
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:
Default value is:
{date} Oracle Coherence {version} <{level}> (thread={thread}, member={member}): {text}
|
|
< |
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 |
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.
Used in: coherence.
Table A-25 describes the elements you can define within the management-config element.
Table A-25 management-config Subelements
| Element | Optional/Required | Description |
|---|---|---|
|
< |
Required |
Specifies whether a cluster node's JVM has an
Default value is |
|
< |
Required |
Specifies whether this cluster node exposes its managed objects to remote MBean server(s). Legal values are: |
|
|
Optional |
Specifies the method which is used to refresh remote management information. Legal values are: Default value is Preconfigured override is |
|
|
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 Preconfigured override is |
|
|
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 Preconfigured override is |
|
< |
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 |
|
< |
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 |
|
< |
Optional |
Specifies the name of the Invocation Service used for remote management. This element is used only if |
|
|
Optional |
Contains the configuration information for the |
|
|
Optional |
Contains a list of MBeans to be registered when a node joins the cluster. |
|
Optional |
Contains the configuration information of a filter class that is used to filter MBeans before they are registered. |
|
|
|
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..
Used in: mbeans
The mbean element contains a list of elements to be instantiated and registered with the Coherence Management infrastructure.
Table A-26 describes the subelements you can define within the mbean element.
Table A-26 Subelements of mbean
| Element | Required/Optional | Description |
|---|---|---|
|
|
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 |
|
|
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 This element cannot be used together with the |
|
|
Optional |
Specifies a JMX <mbean-query>java.lang:*</mbean-query> This element cannot be used together with the |
|
|
Optional |
Specifies the method name on the factory class (specified by the |
|
|
Required |
Specifies the JMX |
|
|
Optional |
Specifies whether or not the MBean is visible across the cluster. Valid values are Default value is |
|
|
Optional |
Specifies whether or not the MBean should be instantiated and registered on this instance. Valid values are Default value is |
|
|
Optional |
Specifies whether or not the MBean should extend beyond the node connection life cycle. Valid values are Default value is |
Used in: management-config
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.
Table A-27 describes the elements you can define within the mbeans element.
Table A-27 Subelement of mbeans
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the MBean type, implementation, and |
Used in management-config.
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>
Table A-43 describes the subelements you can define within the mbean-filter element.
Table A-28 mbean-filter Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the name of a filter class for filtering mbeans. This element cannot be used together with the |
|
|
Optional |
Specifies a factory class for creating filter instances. This element cannot be used together with the This element can be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the filter implementation. |
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.
Table A-29 describes the elements you can define within the member-identity element.
Table A-29 member-identity Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
Used in: outgoing-message-handler
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.
Table A-30 describes the elements you can define within the message-pool element.
Table A-30 message-pool Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
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 Default value is |
|
|
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 |
|
|
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 |
|
|
Optional |
Specifies the rate of growth (as bitwise left shift) between successive segments. Default value is |
Used in: cluster-config.
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.
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."
Table A-31 describes the elements you can define within the multicast-listener element.
Table A-31 multicast-listener Subelements
| Element | Required /Optional | Description |
|---|---|---|
|
< |
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 |
|
< |
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 |
|
|
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 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. |
|
< |
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 |
|
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. |
|
|
< |
Required |
Specifies a priority of the multicast listener execution thread. Legal values are from 1 to 10. Default value is 8. |
|
< |
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. |
|
< |
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:
Note: This element is only used if the |
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.
Used in: packet-publisher.
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.
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.
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>).
The following table describes the elements you can define within the notification-queuing element.
Table A-32 notification-queuing Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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 |
|
< |
Required |
Specifies the number of milliseconds that the packet publisher will delay before sending a NACK packet. Default value is 1. |
Used in: cluster-config
The outgoing-message-handler element contains the outgoing message handler (also known as a dispatcher) related configuration information.
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 |
|---|---|---|
|
< |
Optional |
Specifies a list of |
|
Optional |
Specifies the size of the message buffer pool. |
Used in: flow-control.
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.
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.
Table A-34 describes the elements you can define within the outstanding-packets element.
Table A-34 outstanding-packets Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
|
< |
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. |
Used in: unicast-listener, multicast-listener, packet-publisher.
Specifies the size (in packets or bytes) of the operating system buffer for datagram sockets.
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).
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.
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.
Table A-35 describes the elements you can define within the packet-buffer element.
Table A-35 packet-buffer Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
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 The |
|
|
Optional |
Specifies the requested size of the underlying socket buffer in bytes rather than the number of packets. The |
Used in: packet-delivery.
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.
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.
Table A-36 describes the elements you can define within the packet-bundling element.
Table A-36 packet-bundling Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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). |
|
< |
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. |
Used in: packet-publisher.
Specifies timing and transmission rate parameters related to packet delivery.
The <timeout-milliseconds> and <heartbeat-milliseconds> subelements are used in detecting the death of other cluster nodes.
Table A-37 describes the elements you can define within the packet-delivery element.
Table A-37 packet-delivery Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
|
< |
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. |
|
< |
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 |
|
Optional |
Configures per-node packet throttling and remote GC detection. |
|
|
Optional |
Configures how aggressively Coherence will attempt to maximize packet utilization. |
Used in: incoming-message-handler, packet-publisher.
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.
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.
Table A-38 describes the subelements you can define within the packet-pool element.
Table A-38 packet-pool Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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 |
Used in: cluster-config.
Specifies configuration information for the Packet publisher, which manages network data transmission.
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).
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.
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 |
|
Optional |
Specifies the UDP packet sizes to use. |
|
|
Required |
Specifies timing parameters related to reliable packet delivery. |
|
|
Required |
Contains the notification queue related configuration info. |
|
|
Required |
Specifies the maximum number of packets which can be enqueued on the publisher before client threads block. |
|
|
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. |
|
|
Required |
Specifies how many outgoing packets Coherence will buffer before blocking. |
|
|
< |
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.
Used in: packet-publisher.
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.Table A-40 describes the subelements you can define within the packet-size element.
Table A-40 packet-size Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
|
< |
Required |
Specifies the preferred size, in bytes, of the This value can be larger or smaller then the 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. |
Used in: cluster-config.
Specifies configuration information for the Packet speaker, used for network data 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.
Table A-41 describes the subelements you can define within the packet-speaker element.
Table A-41 packet-speaker Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Specifies the packet load which must be present for the speaker to be activated. |
|
|
< |
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.
Used in: flow-control.
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.
Table A-42 describes the subelements you can define within the pause-detection element.
Table A-42 pause-detection Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
Used in: ssl, identity-manager, trust-manager.
The provider element contains the configuration information for a security provider that extends the java.security.Provider class.
Table A-43 describes the subelements you can define within the provider element.
Table A-43 provider Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the name of a security provider that extends the The class name can be entered using either this element or by using the |
|
|
Optional |
Specifies the name of a security provider that extends the This element cannot be used together with the |
|
|
Optional |
Specifies a factory class for creating This element cannot be used together with the This element can be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the provider implementation. This element cannot be used together with the |
Used in: management-config.
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.
Table A-44 describes the subelements you can define within the reporter element.
Table A-44 reporter Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Required |
Specifies the location for the Reporter Batch XML. The default file is |
|
|
Required |
Specifies whether or not the Reporter automatically starts when the node starts. Valid values are Default value is |
|
|
Required |
Specifies whether or not the reporter runs on multiple management nodes. Valid values are Default value is |
Used in: coherence.
Table A-45 describes the subelements you can define within the security-config element.
Table A-45 security-config Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies whether the security features are enabled. All other configuration elements in the |
|
< |
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 |
|
Required |
Contains the configuration information for the class that implements |
|
|
Optional |
Contains the configuration information for the class that implements |
|
|
Optional |
Contains the configuration information for a class that implements the |
|
|
Optional |
Contains the configuration information for the class that implements |
|
|
<subject-scope> |
Optional |
Specifies whether or not the remote cache or service reference is shared by subject. Valid values are Default value is |
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.
Used in: cluster-config
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.
Table A-46 describes the subelements you can define within the serializer element.
Table A-46 serializer Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies a class that implements |
|
|
Optional |
Specifies a factory class for creating custom serializer instances. The instances must implement This element cannot be used together with the |
|
< |
Optional |
Specifies the name of a static factory method on the factory class which will perform object instantiation. |
|
Optional |
Contains class initialization parameters for the serializer implementation. |
Used in: cluster-config
Specifies the configuration of the service guardian, which detects and attempts to resolve service deadlocks.
Table A-47 describes the subelements you can define within the service-guardian element.
Table A-47 service-guardian Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
The timeout value used to guard against deadlocked or unresponsive services. It is recommended that Default value is Preconfigured override is |
|
|
Optional |
Specifies the action to take when an abnormally behaving service thread cannot be terminated gracefully by the service guardian. Legal values are:
Default value is |
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.
Used in: cluster-config.
Specifies the configuration for Coherence services.
The types of services which can be configured includes:
ReplicatedCache—A cache service which maintains copies of all cache entries on all cluster nodes which run the service.
ReplicatedCache.Optimistic—A version of the ReplicatedCache which uses optimistic locking.
DistributedCache—A cache service which evenly partitions cache entries across the cluster nodes which run the service.
SimpleCache —A version of the ReplicatedCache which lacks concurrency control.
LocalCache—A cache service for caches where all cache entries reside in a single cluster node.
InvocationService—A service used for performing custom operations on remote cluster nodes.
Table A-48 describes the subelements you can define for each services element.
Table A-48 services Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the canonical name for a service, allowing the service to be referenced from the |
|
< |
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:
|
|
< |
Optional |
Contains the list of <use-filters> <filter-name>gzip</filter-name> </use-filters> will activate |
|
Optional |
Specifies the initialization parameters that are specific to each |
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.
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.
| Parameter Value | Value Description |
|---|---|
|
|
Specifies whether this member of the |
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 <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 |
|---|---|
|
|
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. |
|
|
Only applicable with the custom type. Specifies a class name for the custom storage implementation. If the class implements |
|
|
Only applicable with the file-mapped type. Specifies the path name for the directory that the disk persistence manager ( Default value is the default temporary directory designated by the Java runtime. |
|
|
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:
If the value does not contain a factor, a factor of Legal values are positive integers between Default value is |
|
|
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:
If the value does not contain a factor, a factor of Legal values are positive integers between Default value is |
|
|
Only applicable with the scheme type. Specifies a scheme name for the |
|
|
Specifies the type of the storage used to hold the backup data. Legal values are:
Default value is Preconfigured override is |
|
|
Specifies the name of a class that implements the |
|
|
Specifies the name of a class that implements the |
|
|
Specifies the lease ownership granularity. Available since release 2.3.Legal values are:
A value of Default value is |
|
|
Specifies whether this member of the Normally this value should be left unspecified within the configuration file, and instead set on a per-process basis using the Legal values are Preconfigured override is |
|
|
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 ( 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: Valid values are positive integers. The default value is |
|
|
Specifies the name of a class that implements the |
|
|
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 value of this element must be in the following format:
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. |
|
|
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 Legal values are positive integers or zero (indicating no default timeout). |
|
|
Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the Legal values are positive integers or zero (indicating no default timeout). |
|
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 Set the value to |
|
|
|
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 |
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 |
|---|---|
|
|
Specifies the lease ownership granularity. Available since release 2.3.Legal values are:
A value of Default value is |
|
|
Specifies whether lease issues should be transferred to the most recent lock holders. Legal values are Default value is |
|
|
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 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 |
|---|---|
|
|
Specifies the default timeout value in milliseconds for requests that can time-out (for example, implement the
Legal values are positive integers or zero (indicating no default timeout). |
|
|
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 |
|
|
Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the Legal values are positive integers or zero (indicating no default timeout). |
|
|
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 Default value is 0. Set the value to |
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 |
|---|---|
|
|
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. |
|
|
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 Legal values are positive integers or zero (indicating no default timeout). |
|
|
Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the Legal values are positive integers or zero (indicating no default timeout). |
Used in: cluster-config.
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.
Table A-54 describes the elements you can define within the shutdown-listener element.
Table A-54 shutdown-listener Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the type of action to take upon an external JVM shutdown. Legal values:
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 |
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.
Used in: well-known-addresses.
Table A-55 describes the subelements you can define within the socket-address element.
Table A-55 socket-address Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
|
< |
Required |
Specifies the port that the Socket will listen or publish on. Legal values are from 1 to 65535. |
Used in: socket-providers, unicast-listener.
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.
system (default)– The system socket provider returns socket instances based upon the JVM's default socket implementations.
tcp – The TCP socket provider is a socket provider which, whenever possible, produces TCP-based sockets. This socket provider creates instances of DatagramSocket which are backed by TCP. When coupled with well-known-address, this allows Coherence TCMP to function entirely over TCP without the need UDP.
Note:
if this socket provider is used without well-known-addresses, TCP is used for all unicast communications; while, multicast is utilized for group based communications.ssl – The ssl socket provider is a socket provider which only produces SSL protected sockets. Just as with the TCP socket provider, this includes a SSL/TCP based DatagramSocket. Unlike the TCP socket-provider, multicast sockets are not supported, and thus well-known-addresses must be enabled for TCMP to function with this provider.
This basic configuration allows for easy configuration of two-way SSL connections, based on peer trust where every trusted peer resides within a single JKS keystore. More elaborate configuration can be defined with alternate identity and trust managers to allow for CA based trust validation.
Table A-56 describes the subelements you can define within the socket-provider element.
Table A-56 socket-provider Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies a socket provider that produces instances of the JVM's default socket and channel implementations. |
|
|
Optional |
Specifies a socket provider that produces TCP-based sockets and channel implementations. |
|
|
Optional |
Specifies a socket provider that produces socket and channel implementations which utilize SSL. |
|
|
Optional |
Contains the class configuration information for a |
Used in cluster-config
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.
Table A-57 describes the subelements you can define within the socket-providers element.
Table A-57 socket-providers Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Specifies the configuration information for a socket and channel factory that implements the |
Used in: socket-provider.
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.
Table A-58 describes the elements you can define within the ssl element.
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the name of the protocol used by the socket and channel implementations produced by the SSL socket provider. The default value is |
|
|
Optional |
Specifies the configuration for a security provider instance. |
|
|
Optional |
Specifies the configuration information for an implementation of the A |
|
Optional |
Specifies the configuration information for initializing an identity manager instance. |
|
|
Optional |
Specifies the configuration information for initializing a trust manager instance. |
|
|
|
Optional |
Specifies the configuration information for an implementation of the A |
Used in: cluster-config.
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.
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 |
|
< |
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 This feature relies upon the Legal values are strings representing time intervals. A timeout of The default value is |
|
|
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 The default value is |
|
|
Optional |
Specifies the size of the TCP/IP server socket backlog queue. Valid values are positive integers. Default value is O/S dependent. |
|
< |
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.
Used in: packet-publisher.
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.
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.
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.
Table A-60 describes the subelements you can define within the traffic-jam element.
Table A-60 traffic-jam Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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. |
|
< |
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. |
Used in: ssl.
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.
Table A-61 describes the elements you can define within the trust-manager element.
Table A-61 trust-manager Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
|
Optional |
Specifies the algorithm used by the trust manager. The default value is |
|
|
Optional |
Specifies the configuration for a security provider instance. |
|
Optional |
Specifies the configuration for a key store implementation. |
Used in: cluster-config.
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.
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).
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."
Table A-62 describes the subelements you can define within the unicast-listener element.
Table A-62 unicast-listener Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Contains a list of "well known" addresses (WKA) that are used by the cluster discovery protocol in place of multicast broadcast. |
|
|
< |
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. |
|
< |
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 |
|
< |
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 |
|
< |
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 |
|
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. |
|
|
< |
Required |
Specifies a priority of the unicast listener execution thread. Legal values are from 1 to 10. Default value is |
|
Optional |
Specifies the configuration information for a socket and channel factory that implements the <socket-provider>ssl</socket-provider> Preconfigured override is |
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.
Used in: packet-speaker
Specifies the minimum outgoing packet volume which must exist for the speaker daemon to be activated.
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.
Table A-63 describes the elements you can define within the packet-speaker element.
Table A-63 packet-speaker Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
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 |
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".
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 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>
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 |
|---|---|---|
|
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 |
|
|
Optional |
Contains the configuration for a |
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.
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 |
|---|---|---|
|
|
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 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, < |
|
|
Optional |
Used in conjunction with the |