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 D, "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>, this is where you may begin configuring your cluster and services.
Coherence Operational Configuration deployment descriptor should begin with the following DOCTYPE declaration:
Example H-1 Operational Configuration Deployment Descriptor DOCTYPE Declaration
<!DOCTYPE coherence PUBLIC "-//Oracle, Inc.//DTD Oracle Coherence 3.4//EN""http://www.tangosol.com/dtd/coherence_3_3.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 Coherence 3.2 and above use this feature 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 for the specific customizations.
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 for 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 provide per-node customizations as system properties. See Appendix L, "Command Line Overrides" for more information on this feature.
Table H-1 lists all non-terminal elements which may be used from within the operational configuration.
Table H-1 Non-Terminal Operational Configuration Elements
| Element | Used in: |
|---|---|
|
root element |
|
|
access-controller, callback-handler, configurable-cache-factory-config, filters, services |
|
Used in: security-config.
Table H-2 describes the subelements you can define within the access-controller element.
Table H-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 value based on the default |
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 H-3 describes the subelements you can define within the authorized-hosts element.
Table H-3 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 |
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: packet-publisher.
The burst-mode element is used to control the rate at which packets will transmitted on the network, by specifying the maximum number of packets to transmit without pausing. By default this feature is disabled and is typically only needed when flow-control is disabled, or when operating with heavy loads on a half-duplex network link. This setting only effects packets which are sent by the packet-speaker.
Table H-4 describes the subelements you can define within the burst-mode element.
Table H-4 burst-mode Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the maximum number of packets that the will be sent in a row without pausing. Zero indicates no limit. By setting this value relatively low, Coherence is forced to hold back when sending a large number of packets, which may reduce collisions in some instances or allow incoming traffic to be more quickly processed. Default value is 0. |
|
< |
Required |
Specifies the minimum number of milliseconds to delay between long bursts of packets. By increasing this value, Coherence is forced to hold back when sending a large number of packets, which may reduce collisions in some instances or allow incoming traffic to be more quickly processed. Default value is 10. |
Used in: security-config.
Table H-5 describes the elements you can define within the callback-handler element.
Table H-5 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 H-6 describes the subelements you can define within the cluster-config element.
Table H-6 cluster-config Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Specifies the hosts which are allowed to join the cluster. |
|
|
<filters> |
Optional |
Specifies data transformation filters, which can be used to perform custom transformations on data being transferred between cluster nodes. |
|
Required |
Specifies configuration information for the Incoming message handler, used for dispatching incoming cluster communications. |
|
|
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 Multicast listener, used for receiving point-to-multipoint network communications. |
|
|
Required |
Specifies configuration information for the Outgoing message handler, used for dispatching outgoing cluster communications. |
|
|
Required |
Specifies configuration information for the Packet publisher, used for managing network data transmission. |
|
|
Required |
Specifies configuration information for the Packet speaker, used for network data transmission. |
|
|
<services> |
Required |
Specifies the declarative data for all available Coherence services. |
|
Required |
Specifies the action to take upon receiving an external shutdown request. |
|
|
Required |
Specifies configuration information for the TCP Ring listener, used to death detection. |
|
|
Required |
Specifies the configuration information for the Unicast listener, used for receiving point-to-point network communications. |
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.
root element
The coherence element is the root element of the operational deployment descriptor tangosol-coherence.xml.
Table H-7 describes the elements you can define within the coherence element.
Table H-7 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. It controls where, from, and how the cache configuration settings are loaded. |
|
|
Required |
Contains the configuration information for the coherence Management Framework. See Chapter 22, "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.
Table H-8 describes the elements you can define within the configurable-cache-factory-config element.
Table H-8 configurable-cache-factory-config Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the name of a Java class that provides the cache configuration factory. Default value is |
|
Optional |
Contains one or more initialization parameter(s) for a cache configuration factory class which implements the
<init-param>
<param-type>java.lang.String</param-type>
<param-value system-property="tangosol.coherence.cacheconfig">
coherence-cache-config.xml
</param-value>
</init-param>
Preconfigured 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: 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 H-9 describes the elements you can define within each filters element.
| 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 8, "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.
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 H-10 describes the elements you can define within the flow-control subelement.
Table H-10 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 H-11 describes the elements you can define within each host-range element.
Table H-11 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: cluster-config.
The incoming-message-handler assembles UDP packets into logical messages and dispatches them to the appropriate Coherence service for processing.
Table H-12 describes the subelements you can define within the incoming-message-handler element.
Table H-12 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 H-13 describes the elements you can define within the init-param element.
Table H-13 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: filters, services, configurable-cache-factory-config, access-controller and callback-handler.
Defines a series of initialization parameters.
Table H-14 describes the elements you can define within the init-params element.
Table H-14 init-params Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
Optional |
Defines an individual initialization parameter. |
Used in: coherence.
Table H-15 describes the elements you can define within the license-config element.
Table H-15 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 H-16 logging-config Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
<destination> |
Required |
Specifies the output device used by the logging system. Legal values are:
If |
|
< |
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 is 4096. Preconfigured 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 on this attribute.
Used in: coherence.
Table H-17 describes the elements you can define within the management-config element.
Table H-17 management-config Subelements
| Element | Optional/Required | Description |
|---|---|---|
|
< |
Required |
Specifies the name of the JMX domain used to register MBeans exposed by the Coherence Management Framework. See Chapter 22, "How to Manage Coherence Using JMX" for more information. |
|
< |
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 MBeanServer(s). Legal values are: true or false. Default value is false. Preconfigured value is |
|
< |
Required |
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 |
|
< |
Required |
Specifies the name of the Invocation Service used for remote management. This element is used only if allow-remote-management is set to true. |
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 member-identity element contains detailed identity information that is useful for defining the location and role of the cluster member.
Table H-18 describes the elements you can define within the member-identity element.
Table H-18 member-identity Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
The |
|
< |
Optional |
The site-name element contains the name of the geographic site that the member is hosted at. For WAN clustering, this value identifies the datacenter within which the member is located, and can be used as the basis for intelligent routing, load balancing and disaster recovery planning (that is, the explicit backing up of data on separate geographic sites). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. Deployments that spread across more than one geographic site should specify a site-name value. Preconfigured value is |
|
< |
Optional |
The rack-name element contains the name of the location within a geographic site that the member is hosted at. This is often a cage, rack or bladeframe identifier, and can be used as the basis for intelligent routing, load balancing and disaster recovery planning (that is, the explicit backing up of data on separate bladeframes). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. Large scale deployments should always specify a rack-name value. Preconfigured value is |
|
< |
Optional |
The machine-name element contains the name of the physical server that the member is hosted on. This is often the same name as the server identifies itself as (for example, its |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
|
< |
Optional |
The |
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 16, "Performing a Multicast Connectivity Test."
Table H-19 describes the elements you can define within the multicast-listener element.
Table H-19 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 |
|
< |
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 value is |
|
Required |
Specifies how many incoming packets the operating system will be requested to buffer. |
|
|
< |
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 H-20 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: acceptor-config, initiator-config.
The outgoing-message-handler specifies the configuration info used to detect dropped client-to-cluster connections. For connection initiators and acceptors that use connectionless protocols (for example, JMS), this information is necessary to proactively detect and release resources allocated to dropped connections. Connection-oriented initiators and acceptors can also use this information as an additional mechanism to detect dropped connections.
Table H-21 describes the elements you can define within the outgoing-message-handler element.
Table H-21 outgoing-message-handler Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Optional |
Specifies the interval between ping requests. A ping request is used to ensure the integrity of a connection.The value of this element must be in the following format: [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]? where the first non-digits (from left to right) indicate the unit of time duration:
If the value does not contain a unit, a unit of milliseconds is assumed. A value of zero disables ping requests. The default value is zero. |
|
< |
Optional |
Specifies the maximum amount of time to wait for a response to a ping request before declaring the underlying connection unusable.The value of this element must be in the following format: [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]? where the first non-digits (from left to right) indicate the unit of time duration:
If the value does not contain a unit, a unit of milliseconds is assumed. The default value is the value of the request-timeout element. |
|
< |
Optional |
Specifies the maximum amount of time to wait for a response message before declaring the underlying connection unusable.The value of this element must be in the following format: [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]? where the first non-digits (from left to right) indicate the unit of time duration:
If the value does not contain a unit, a unit of milliseconds is assumed. The default value is an infinite timeout. |
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 H-22 describes the elements you can define within the outstanding-packets element.
Table H-22 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 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 http://forums.oracle.com/forums/forum.jspa?forumID=480&start=0 for details on configuring your operating system to allow larger buffers.
Table H-23 describes the elements you can define within the packet-buffer element.
Table H-23 packet-buffer Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
<maximum-packets> |
Required |
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 |
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 H-24 describes the elements you can define within the packet-bundling element.
Table H-24 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: incoming-message-handler, packet-publisher.
Specifies the number of packets which Coherence will internally maintain 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 H-25 describes the subelements you can define within the packet-pool element.
Table H-25 packet-pool Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
The maximum number of reusable packets to be used by the services responsible for publishing and receiving. The pools are initially small, and will grow on demand up to the specified limits. Defaults are 2048 for transmitting and receiving. |
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 H-26 describes the elements you can define within the packet-delivery element.
Table H-26 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 60000.Note: For production use, the recommended value is the greater of 60000 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: 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 H-27 describes the elements you can define within the packet-publisher element.
Table H-27 packet-publisher Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
<enabled> |
Required |
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 |
|
Required |
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 the publisher may transmit without pausing. |
|
|
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. |
|
|
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 H-28 describes the subelements you can define within the packet-size element.
Table H-28 packet-size Subelement
| Element | Required/Optional | Description |
|---|---|---|
|
< |
Required |
Specifies the maximum size, in bytes, of the UDP packets that will be sent and received on the unicast and multicast sockets. This value should be at least 512; recommended value is 1468 for 100Mb, and 1Gb Ethernet. This value must be identical on all cluster nodes. Note: Some network equipment cannot handle packets larger than 1472 bytes (IPv4) or 1468 bytes (IPv6), particularly under heavy load. If you encounter this situation on your network, this value should be set to 1472 or 1468 respectively. The recommended values is 32 bytes less then the network MTU setting. Default value is 1468. |
|
< |
Required |
Specifies the preferred size, in bytes, of UDP packets that will be sent and received on the unicast and multicast sockets. This value should be at least 512 and cannot be greater than the maximum-length value; it is recommended to set the value to the same as the maximum-length value. Default value is 1468. |
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 H-29 describes the subelements you can define within the packet-speaker element.
Table H-29 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 H-30 describes the subelements you can define within the pause-detection element.
Table H-30 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: coherence.
Table H-31 describes the subelements you can define within the security-config element.
Table H-31 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 |
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 concurrent 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 H-32 describes the subelements you can define for each services element.
Table H-32 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.
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 H-33 describes the elements you can define within the shutdown-listener element.
Table H-33 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 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: well-known-addresses, tcp-initiator.
Table H-34 describes the subelements you can define within the socket-address element.
Table H-34 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: 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 H-35 describes the subelements you can define within the tcp-ring-listener element.
Table H-35 tcp-ring-listener Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
<enabled> |
Required |
Specifies whether the tcp ring listener should be enabled to defect node failures faster. Legal values are |
|
< |
Required |
Specifies the maximum number of tcp ring listener exceptions that will be tolerated before a particular member is considered really gone and is removed from the cluster. This value is used only if the value of |
|
< |
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, and burst-mode elements.
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 H-36 describes the subelements you can define within the traffic-jam element.
Table H-36 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: 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 16, "Performing a Multicast Connectivity Test."
Table H-37 describes the subelements you can define within the unicast-listener element.
Table H-37 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. |
|
|
< |
Required |
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. Default value is |
|
< |
Required |
Specifies the port that the Socket will listen or publish on. Legal values are from 1 to 65535. Default value is 8088. Preconfigured 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. |
|
|
< |
Required |
Specifies a priority of the unicast listener execution thread. Legal values are from 1 to 10. Default value is |
|
< |
Optional |
Specifies whether the unicast listener will ignore socket exceptions that indicate that a Member is unreachable. Deprecated as of Coherence 3.2. |
|
< |
Optional |
Specifies the maximum number of unicast listener exceptions that will be tolerated before a particular member is considered really gone and is removed from the cluster. Deprecated as of Coherence 3.2. |
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 H-38 describes the elements you can define within the packet-speaker element.
Table H-38 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 Caching Edition. If you are having difficulties in establishing a cluster by using multicast, see Chapter 16, "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 well known node must be running for other nodes to be able to join.
Example H-2 illustrates a configuration for two well-known-addresses with the default port.
Example H-2 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 H-39 describes the subelements you can define within the well-known-addresses element.
Table H-39 well-known-addresses Subelements
| Element | Required/Optional | Description |
|---|---|---|
|
Required |
Specifies a list of "well known" addresses (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 values are |
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 H-40 lists the elements that can use id or xml-override, or both.
Table H-41 describes the functionality of the id and xml-override attributes.
Table H-41 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 |