Skip Headers
Oracle® Coherence Developer's Guide for Oracle Coherence
Release 3.4

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

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

H Operational Configuration Elements

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

H.1 Operational Configuration Deployment Descriptors

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

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

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

H.1.1 Document Location

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

H.1.2 Document Root

The root element of the operational descriptor is <coherence>, this is where you may begin configuring your cluster and services.

H.1.3 Document Format

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.

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

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

Multiple levels of override files may also be configured, allowing for additional fine tuning between similar deployment environments such as staging and production. For example 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.

H.1.5 Command Line Override

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.


Element Index

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


access-controller

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

<class-name>

Required

Specifies the name of a Java class that implements com.tangosol.net.security.AccessController interface, which will be used by the security framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights. See Chapter 7, "Security Framework" for more information. Default value is com.tangosol.net.security.DefaultController.

<init-params>

Optional

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

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

Preconfigured value based on the default AccessController implementation and the default parameters as specified above are tangosol.coherence.security.keystore and tangosol.coherence.security.permissions. For more information on preconfigured overrides, see Appendix L, "Command Line Overrides." For more information on the elements you can define within the init-param element, see "init-param".



authorized-hosts

Used in: cluster-config.

Description

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

Elements

Table H-3 describes the subelements you can define within the authorized-hosts element.

Table H-3 authorized-hosts Subelements

Element Required/Optional Description

<host-address>

Optional

Specifies an IP address or hostname. If any are specified, only hosts with specified host-addresses or within the specified host-ranges will be allowed to join the cluster. The content override attributes id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.

<host-range>

Optional

Specifies a range of IP addresses. If any are specified, only hosts with specified host-addresses or within the specified host-ranges will be allowed to join the cluster. The content override attributes id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.


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


burst-mode

Used in: packet-publisher.

Description

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.

Elements

Table H-4 describes the subelements you can define within the burst-mode element.

Table H-4 burst-mode Subelements

Element Required/Optional Description

<maximum-packets>

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.

<pause-milliseconds>

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.



callback-handler

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

<class-name>

Required

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

<init-params>

Optional

Contains one or more initialization parameter(s) for a CallbackHandler implementation. For more information on the elements you can define within the init-param element, refer to "init-param".



cluster-config

Used in: <coherence>

Description

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

Elements

Table H-6 describes the subelements you can define within the cluster-config element.

Table H-6 cluster-config Subelement

Element Required/Optional Description

<authorized-hosts>

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.

<incoming-message-handler>

Required

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

<member-identity>

Optional

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

<multicast-listener>

Required

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

<outgoing-message-handler>

Required

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

<packet-publisher>

Required

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

<packet-speaker>

Required

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

<services>

Required

Specifies the declarative data for all available Coherence services.

<shutdown-listener>

Required

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

<tcp-ring-listener>

Required

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

<unicast-listener>

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.


coherence

root element

Description

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

Elements

Table H-7 describes the elements you can define within the coherence element.

Table H-7 coherence Subelements

Element Required/Optional Description

<cluster-config>

Required

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

<logging-config>

Required

Contains the configuration information for the logging facility.

<configurable-cache-factory-config>

Required

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

<management-config>

Required

Contains the configuration information for the coherence Management Framework. See Chapter 22, "How to Manage Coherence Using JMX" for more information.

<security-config>

Optional

Contains the configuration information for the Coherence Security Framework.

<license-config>

Optional

Contains the edition and operational mode configuration.


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


configurable-cache-factory-config

Used in: coherence.

Elements

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

<class-name>

Required

Specifies the name of a Java class that provides the cache configuration factory. Default value is com.tangosol.net.DefaultConfigurableCacheFactory.

<init-params>

Optional

Contains one or more initialization parameter(s) for a cache configuration factory class which implements the com.tangosol.run.xml.XmlConfigurable interface.For the default cache configuration factory class (DefaultConfigurableCacheFactory) the parameters are specified as follows:

<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 tangosol.coherence.cacheconfig. Unless an absolute or relative path is specified, such as with ./path/to/config.xml, the application's classpath will be used to find the specified descriptor. See Appendix L, "Command Line Overrides" for more information on overrides.


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


filters

Used in: cluster-config.

Description

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

Implementation

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

Note:

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

Elements

Table H-9 describes the elements you can define within each filters element.

Table H-9 filters Subelements

Element Required/Optional Description

<filter-name>

Required

Specifies the canonical name of the filter. This name is unique within the cluster. For example: gzip. The content override attribute id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.

<filter-class>

Required

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

<init-params>

Optional

Specifies initialization parameters, for configuring filters which implement the com.tangosol.run.xml.XmlConfigurable interface.For example when using a com.tangosol.net.CompressionFilter the parameters are specified as follows:

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

For more information on the parameter values for the standard filters refer to, refer to Chapter 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.


flow-control

Used in: packet-delivery.

Description

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

Remote GC Detection

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

Packet Throttling

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

Elements

Table H-10 describes the elements you can define within the flow-control subelement.

Table H-10 flow-control Subelements

Element Required/Optional Description

<enabled>

Optional

Specifies if flow control is enabled. Default is true

<pause-detection>

Optional

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

<outstanding-packets>

Optional

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



host-range

Used in: authorized-hosts.

Description

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

Elements

Table H-11 describes the elements you can define within each host-range element.

Table H-11 host-range Subelements

Element Required/Optional Description

<from-address>

Required

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

<to-address>

Required

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


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


incoming-message-handler

Used in: cluster-config.

Description

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

Elements

Table 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

<maximum-time- variance>

Required

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

<use-nack-packets>

Required

Specifies whether the packet receiver will use negative acknowledgments (packet requests) to pro-actively respond to known missing packets. See "notification-queueing" for additional details and configuration. Legal values are true or false. Default value is true.

<priority>

Required

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

<packet-pool>

Required

Specifies how many incoming packets Coherence will buffer before blocking.


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


init-param

Used in: init-params.

Description

Defines an individual initialization parameter.

Elements

Table H-13 describes the elements you can define within the init-param element.

Table H-13 init-param Subelement

Element Required/Optional Description

<param-name>

Optional

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

<param-type>

Optional

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

<param-value>

Required

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


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


init-params

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

Description

Defines a series of initialization parameters.

Elements

Table H-14 describes the elements you can define within the init-params element.

Table H-14 init-params Subelement

Element Required/Optional Description

<init-param>

Optional

Defines an individual initialization parameter.



license-config

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

<edition-name>

Optional

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

<license-mode>

Optional

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



logging-config

Used in: coherence.

Elements

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

Table H-16 logging-config Subelements

Element Required/Optional Description

<destination>

Required

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

  • stdout

  • stderr (default)

  • jdk

  • log4 j

  • a file name

If jdk is specified as the destination, Coherence must be run using JDK 1.4 or later; likewise, if log4j is specified, the Log4j libraries must be in the classpath. In both cases, the appropriate logging configuration mechanism (system properties, property files, and so on) are necessary to configure the JDK/Log4j logging libraries. Preconfigured value is tangosol.coherence.log. See Appendix L, "Command Line Overrides" for more information.

<severity-level>

Required

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

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

  • 1—all the above plus errors

  • 2—all the above plus warnings

  • 3—all the above plus informational messages

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

  • -1—no messages

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

<message-format>

Required

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

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

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

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

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

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

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

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

  • {text}—the text of the message

Default value is:

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

<character-limit>

Required

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

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

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

Default value is 4096. Preconfigured value is tangosol.coherence.log.limit. For more information, see Appendix L, "Command Line Overrides."


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


management-config

Used in: coherence.

Elements

Table H-17 describes the elements you can define within the management-config element.

Table H-17 management-config Subelements

Element Optional/Required Description

<default-domain-name>

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.

<managed-nodes>

Required

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

  • none—No MBeanServer is instantiated.

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

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

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

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

<allow-remote-management>

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 tangosol.coherence.management.remote. See Appendix L, "Command Line Overrides" for more information.

<read-only>

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

<service-name>

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


member-identity

Used in: cluster-config.

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

Elements

Table H-18 describes the elements you can define within the member-identity element.

Table H-18 member-identity Subelements

Element Required/Optional Description

<cluster-name>

Optional

The cluster-name element contains the name of the cluster. To join the cluster all members must specify the same cluster name. It is strongly suggested that cluster-name be specified for production systems, thus preventing accidental cluster discovery among applications. Preconfigured value is tangosol.coherence.cluster. See Appendix L, "Command Line Overrides" for more information.

<site-name>

Optional

The site-name element contains the name of the geographic site that the member is hosted at. For WAN clustering, this value identifies the datacenter within which the member is located, and can be used as the basis for intelligent routing, load balancing and disaster recovery planning (that is, the explicit backing up of data on separate geographic sites). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. 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 tangosol.coherence.site. See Appendix L, "Command Line Overrides" for more information.

<rack-name>

Optional

The rack-name element contains the name of the location within a geographic site that the member is hosted at. This is often a cage, rack or bladeframe identifier, and can be used as the basis for intelligent routing, load balancing and disaster recovery planning (that is, the explicit backing up of data on separate bladeframes). The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. Large scale deployments should always specify a rack-name value. Preconfigured value is tangosol.coherence.rack. See Appendix L, "Command Line Overrides" for more information.

<machine-name>

Optional

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

<process-name>

Optional

The process-name element contains the name of the process (JVM) that the member is hosted on. This name makes it possible to easily differentiate among multiple JVMs running on the same machine. The name is also useful for displaying management information (for example, JMX) and interpreting log entries. It is optional to provide a value for this element. Often, a single member will exist per JVM, and in that situation this name would be redundant. Preconfigured value is tangosol.coherence.process. See Appendix L, "Command Line Overrides" for more information.

<member-name>

Optional

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

<role-name>

Optional

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

<priority>

Optional

The priority element specifies a priority of the corresponding member. The priority is used as the basis for determining tie-breakers between members. If a condition occurs in which one of two members will be ejected from the cluster, and in the rare case that it is not possible to objectively determine which of the two is at fault and should be ejected, then the member with the lower priority will be ejected. Valid values are from 1 to 10. Preconfigured value is tangosol.coherence.priority. See Appendix L, "Command Line Overrides" for more information.



multicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Multicast listener. This element is used to specify the address (see <address> subelement) and port (see <port> subelement) that a cluster will use for cluster wide and point-to-multipoint communications. All nodes in a cluster must use the same multicast address and port, whereas distinct clusters on the same network should use different multicast addresses.

Multicast-Free Clustering

By default, Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, the well-known-addresses feature may be used to eliminate the need for multicast traffic. If you are having difficulties in establishing a cluster by using multicast, see Chapter 16, "Performing a Multicast Connectivity Test."

Elements

Table H-19 describes the elements you can define within the multicast-listener element.

Table H-19 multicast-listener Subelements

Element Required /Optional Description

<address>

Required

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

<port>

Required

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

<time-to-live>

Required

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

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

<packet-buffer>

Required

Specifies how many incoming packets the operating system will be requested to buffer.

<priority>

Required

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

<join-timeout-milliseconds>

Required

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

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

<multicast-threshold-percent>

Required

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

  1. The packet is being sent over the network to more than one other node, that is, (d > 1).

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

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

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

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


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


notification-queueing

Used in: packet-publisher.

Description

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

Batched Acknowledgments

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

Negative Acknowledgments

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

Elements

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

Table H-20 notification-queuing Subelements

Element Required/Optional Description

<ack-delay- milliseconds>

Required

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

<nack-delay- milliseconds>

Required

Specifies the number of milliseconds that the packet publisher will delay before sending a NACK packet. Default value is 1.



outgoing-message-handler

Used in: acceptor-config, initiator-config.

Description

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.

Elements

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

<heartbeat-interval>

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:

  • MS or ms (milliseconds)

  • S or s (seconds)

  • M or m (minutes)

  • H or h (hours)

  • D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. A value of zero disables ping requests. The default value is zero.

<heartbeat-timeout>

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:

  • MS or ms (milliseconds)

  • S or s (seconds)

  • M or m (minutes)

  • H or h (hours)

  • D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is the value of the request-timeout element.

<request-timeout>

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:

  • MS or ms (milliseconds)

  • S or s (seconds)

  • M or m (minutes)

  • H or h (hours)

  • D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is an infinite timeout.



outstanding-packets

Used in: flow-control.

Description

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

Auto Tuning

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

Elements

Table H-22 describes the elements you can define within the outstanding-packets element.

Table H-22 outstanding-packets Subelements

Element Required/Optional Description

<maximum-packets>

Optional

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

<minimum-packets>

Optional

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



packet-buffer

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

Description

Specifies the size of the operating system buffer for datagram sockets.

Performance Impact

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

It's just a hint

The operating system will only treat the specified value as a hint, and is not required to allocate the specified amount. In the event that less space is allocated then requested Coherence will issue a warning and continue to operate with the constrained buffer, which may degrade performance. See http://forums.oracle.com/forums/forum.jspa?forumID=480&start=0 for details on configuring your operating system to allow larger buffers.

Elements

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 SO_SNDBUF and SO_RCVBUF. Actual buffer sizes may be smaller if the underlying socket implementation cannot support more than a certain size. Defaults are 32 for publishing, 64 for multicast listening, and 1428 for unicast listening.



packet-bundling

Used in: packet-delivery.

Description

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

Default Configuration

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

Elements

Table H-24 describes the elements you can define within the packet-bundling element.

Table H-24 packet-bundling Subelements

Element Required/Optional Description

<maximum-deferral- time>

Optional

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

Default value is 1us (microsecond).

<aggression-factor>

Optional

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

Default value is zero.



packet-pool

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

Description

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.

Performance Impact

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

Elements

Table H-25 describes the subelements you can define within the packet-pool element.

Table H-25 packet-pool Subelements

Element Required/Optional Description

<maximum-packets>

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.



packet-delivery

Used in: packet-publisher.

Description

Specifies timing and transmission rate parameters related to packet delivery.

Death Detection

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

Elements

Table H-26 describes the elements you can define within the packet-delivery element.

Table H-26 packet-delivery Subelements

Element Required/Optional Description

<resend-milliseconds>

Required

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

<timeout-milliseconds>

Required

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

<heartbeat-milliseconds>

Required

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

<flow-control>

Optional

Configures per-node packet throttling and remote GC detection.

<packet-bundling>

Optional

Configures how aggressively Coherence will attempt to maximize packet utilization.



packet-publisher

Used in: cluster-config.

Description

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

Reliable packet delivery

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

Throttling

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

Elements

Table 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 true. Preconfigured value is tangosol.coherence.tcmp.enabled. See Appendix L, "Command Line Overrides" for more information.

<packet-size>

Required

Specifies the UDP packet sizes to use.

<packet-delivery>

Required

Specifies timing parameters related to reliable packet delivery.

<notification-queueing>

Required

Contains the notification queue related configuration info.

<burst-mode>

Required

Specifies the maximum number of packets the publisher may transmit without pausing.

<traffic-jam>

Required

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

<packet-buffer>

Required

Specifies how many outgoing packets the operating system will be requested to buffer.

<packet-pool>

Required

Specifies how many outgoing packets Coherence will buffer before blocking.

<priority>

Required

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


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


packet-size

Used in: packet-publisher.

Description

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

Note:

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

Elements

Table H-28 describes the subelements you can define within the packet-size element.

Table H-28 packet-size Subelement

Element Required/Optional Description

<maximum-length>

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.

<preferred-length>

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.



packet-speaker

Used in: cluster-config.

Description

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

Offloaded Transmission

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

Elements

Table H-29 describes the subelements you can define within the packet-speaker element.

Table H-29 packet-speaker Subelements

Element Required/Optional Description

<volume-threshold>

Optional

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

<priority>

Required

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


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


pause-detection

Used in: flow-control.

Description

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

Elements

Table H-30 describes the subelements you can define within the pause-detection element.

Table H-30 pause-detection Subelements

Element Required/Optional Description

<maximum-packets>

Optional

The maximum number of packets that will be resent to an unresponsive cluster node before assuming that the node is paused. Specifying a value of 0 will disable pause detection. Default is 16.



security-config

Used in: coherence.

Elements

Table H-31 describes the subelements you can define within the security-config element.

Table H-31 security-config Subelements

Element Required/Optional Description

<enabled>

Required

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

<login-module-name>

Required

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

<access-controller>

Required

Contains the configuration information for the class that implements com.tangosol.net.security.AccessController interface, which will be used by the security framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights. See Chapter 7, "Security Framework" for more information.

<callback-handler>

Optional

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


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


services

Used in: cluster-config.

Description

Specifies the configuration for Coherence services.

Service Components

The types of services which can be configured includes:

Elements

Table H-32 describes the subelements you can define for each services element.

Table H-32 services Subelements

Element Required/Optional Description

<service-type>

Required

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

<service-component>

Required

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

  • ReplicatedCache

  • ReplicatedCache.Optimistic

  • DistributedCache

  • SimpleCache

  • LocalCache

  • InvocationService

<use-filters>

Optional

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

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

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

<init-params>

Optional

Specifies the initialization parameters that are specific to each service-component. For more service specific parameter information see:


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


shutdown-listener

Used in: cluster-config.

Description

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

Elements

Table H-33 describes the elements you can define within the shutdown-listener element.

Table H-33 shutdown-listener Subelements

Element Required/Optional Description

<enabled>

Required

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

  • none—perform no explicit shutdown actions

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

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

  • true—same as force

  • false—same as none

Note: For production use, the suggested value is none unless testing has verified that the behavior on external shutdown is exactly what is desired. Default value is force. Preconfigured value is tangosol.coherence.shutdownhook. See Appendix L, "Command Line Overrides" for more information.


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


socket-address

Used in: well-known-addresses, tcp-initiator.

Elements

Table H-34 describes the subelements you can define within the socket-address element.

Table H-34 socket-address Subelements

Element Required/Optional Description

<address>

Required

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

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

<port>

Required

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



tcp-ring-listener

Used in: cluster-config.

Description

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

Elements

Table 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 true and false. Default value is true. Preconfigured value is tangosol.coherence.tcpring. see Appendix L, "Command Line Overrides" for more information.

<maximum-socket-closed- exceptions>

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 tcp-ring-listener/enabled is true. Legal values are integers greater than zero. Default value is 2.

<priority>

Required

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


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


traffic-jam

Used in: packet-publisher.

Description

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

Tuning

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

Traffic Jam and Flow Control

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

Elements

Table H-36 describes the subelements you can define within the traffic-jam element.

Table H-36 traffic-jam Subelements

Element Required/Optional Description

<maximum-packets>

Required

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

<pause-milliseconds>

Required

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



unicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Unicast listener. This element is used to specify the address and port that a cluster node will bind to, to listen for point-to-point cluster communications.

Automatic Address Settings

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

Multicast-Free Clustering

By default Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, the well-known-addresses feature may be used to eliminate the need for multicast traffic. If you are having difficulties in establishing a cluster by using multicast, see Chapter 16, "Performing a Multicast Connectivity Test."

Elements

Table H-37 describes the subelements you can define within the unicast-listener element.

Table H-37 unicast-listener Subelements

Element Required/Optional Description

<well-known-addresses>

Optional

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

<machine-id>

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.

<address>

Required

Specifies the IP address that a Socket will listen or publish on.Note: The localhost setting may not work on systems that define localhost as the loopback address; in that case, specify the machine name or the specific IP address. Default value is localhost. Preconfigured is tangosol.coherence.localhost. See Appendix L, "Command Line Overrides" for more information.

<port>

Required

Specifies the port that the Socket will listen or publish on. Legal values are from 1 to 65535. Default value is 8088. Preconfigured value is tangosol.coherence.localport. See Appendix L, "Command Line Overrides" for more information.

<port-auto-adjust>

Required

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

<packet-buffer>

Required

Specifies how many incoming packets the operating system will be requested to buffer.

<priority>

Required

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

<ignore-socket-closed>

Optional

Specifies whether the unicast listener will ignore socket exceptions that indicate that a Member is unreachable. Deprecated as of Coherence 3.2.

<maximum-socket-closed-exceptions>

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.


volume-threshold

Used in: packet-speaker

Description

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

Performance Impact

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

Elements

Table H-38 describes the elements you can define within the packet-speaker element.

Table H-38 packet-speaker Subelements

Element Required/Optional Description

<minimum-packets>

Required

Specifies the minimum number of packets which must be ready to be sent for the speaker daemon to be activated. A value of 0 will force the speaker to always be used, while a very high value will cause it to never be used. If unspecified, it will be set to match the packet-buffer, this is the default.



well-known-addresses

Used in: unicast-listener.

Note:

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

Use of the Well Known Addresses (WKA) feature is not supported by Caching Edition. If you are having difficulties in establishing a cluster by using multicast, see Chapter 16, "Performing a Multicast Connectivity Test".

Description

By default, Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, the Well Known Addresses feature may be used to eliminate the need for multicast traffic. When in use the cluster is configured with a relatively small list of nodes which are allowed to start the cluster, and which are likely to remain available over the cluster lifetime. There is no requirement for all WKA nodes to be simultaneously active at any point in time. This list is used by all other nodes to find their way into the cluster without the use of multicast, thus at least one well known node must be running for other nodes to be able to join.

Example

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>

Elements

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

<socket-address>

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 tangosol.coherence.wka and tangosol.coherence.wka.port. See Appendix L, "Command Line Overrides" for more information.


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


Element Attributes

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

Table 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

xml-override

Optional

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

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

id

Optional

Used in conjunction with the xml-override attribute in cases where there are multiple elements with the same name (for example, <services>) to identify the base element that will be overridden and the override element itself. The elements of the override document that do not have a match in the base document are just appended to the base.