Used in: security-config.
The following table describes the elements you can define within the access-controller element.
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 Coherence
Security Framework to check access rights for clustered resources and
encrypt/decrypt node-to-node communications regarding those rights. 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>
|
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.
The following table describes the elements you can define within the authorized-hosts element.
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.
Used in: packet-publisher.
The burst-mode element is used to control the rate at which packets will transmitted on the network, by specificing 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.
The following table describes the elements you can define within the burst-mode element.
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. |
Used in: security-config.
The following table describes the elements you can define within the callback-handler element.
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. |
Used in: coherence.
Contains the cluster configuration information, including communication and service parameters.
The following table describes the elements you can define within the cluster-config element.
Element | Required/Optional | Description |
---|---|---|
<member-identity> | Optional | Specifies detailed identity information that is useful for defining the location and role of the cluster member. |
<unicast-listener> | Required | Specifies the configuration information for the Unicast listener, used for receiving point-to-point network communications. |
<multicast-listener> | Required | Specifies the configuration information for the Multicast listener, used for receiving point-to-multipoint network communications. |
<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. |
<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. |
<incoming-message-handler> | Required | Specifies configuration information for the Incoming message handler, used for dispatching incoming cluster communications. |
<outgoing-message-handler> | Required | Specifies configuration information for the Outgoing message handler, used for dispatching outgoing cluster communications. |
<authorized-hosts> | Optional | Specifies the hosts which are allowed to join the cluster. |
<services> | Required | Specifies the declarative data for all available Coherence services. |
<filters> | Optional | Specifies data transformation filters, which can be used to perform custom transformations on data being transfered between cluster nodes. |
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.
The coherence element is the root element of the operational deployment descriptor.
The following table describes the elements you can define within the coherence element.
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. |
<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.
Used in: coherence.
The following table describes the elements you can define within the configurable-cache-factory-config element.
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 override
is tangosol.coherence.cacheconfig. |
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.
Used in: cluster-config.
Data transformation filters can be used by services to apply a custom transformation on data being transfered between cluster nodes. This can be used for instance to compress or encrypt Coherence network traffic.
Data transformation filters are implementations of the com.tangosol.util.WrapperStreamFactory interface.
Data transformation filters are not related to com.tangosol.util.Filter, which is part of the Coherence API for querying caches. |
The following table describes the elements you can define within each filter element.
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 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. |
<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 Compression Filter Parameters, Symmetric Encryption Filter Parameters and PKCS Encryption Filter Parameters. |
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: 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). Once 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.
The following table describes the elements you can define within the flow-control element.
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. |
Used in: authorized-hosts.
Specifies a range of unicast addresses of nodes which are allowed to join the cluster.
The following table describes the elements you can define within each host-range element.
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 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.
Used in: cluster-config.
The incoming-message-handler assembles UDP packets into logical messages and dispatches them to the appropriate Coherence service for processing.
The following table describes the elements you can define within the incoming-message-handler element.
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.
Used in: init-params.
Defines an individual initialization parameter.
The following table describes the elements you can define within the init-param element.
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 Parameters. |
<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 Parameters. |
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.
Used in: filters, services, configurable-cache-factory-config, access-controller and callback-handler.
Defines a series of initialization parameters.
The following table describes the elements you can define within the init-params element.
Element | Required/Optional | Description |
---|---|---|
<init-param> | Optional | Defines an individual initialization parameter. |
Used in: coherence.
The following table describes the elements you can define within the license-config element.
Element | Required/Optional | Description |
---|---|---|
<edition-name> | Optional | Specifies the product edition that the member will utilize. 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. |
Used in: coherence.
The following table describes the elements you can define within the logging-config element.
Element | Required/Optional | Description |
---|---|---|
<destination> | Required | Specifies the output device used by the logging system.
Legal values are: stdout stderr jdk log4j a file name Default value is stderr. 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, etc.) should be used to configure the JDK/Log4j logging libraries. Preconfigured override is tangosol.coherence.log |
<severity-level> | Required | Specifies which logged messages will be output to the log destination.
Legal values are: 0 - only output without a logging severity level specified will be logged 1 - all the above plus errors 2 - all the above plus warnings 3 - all the above plus informational messages 4-9 - all the above plus internal debugging messages (the higher the number, the more the messages) -1 - no messages Default value is 3. Preconfigured override is tangosol.coherence.log.level |
<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 once 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 override is tangosol.coherence.log.limit |
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.
Used in: coherence.
The following table describes the elements you can define within the management-config element.
Element | Required/Optional | Description |
---|---|---|
<default-domain-name> | Required | Specifies the name of the JMX domain used to register MBeans exposed by the Coherence Management Framework. |
<managed-nodes> | Required | Specifies whether or not a cluster node's JVM has an [in-process] MBeanServer and if so, whether or not this node allows management of other nodes' managed objects.
Legal values are:
Default value is none.
|
<allow-remote-management> | Required | Specifies whether or not this cluster node exposes its managed objects to remote MBeanServer(s).
Legal values are: true or false. Default value is false. Preconfigured override is tangosol.coherence.management.remote |
<read-only> | Required | Specifies whether or not the managed objects exposed by this cluster node allow operations that modify run-time attributes.
Legal values are: true or false. Default value is false. Preconfigured override is tangosol.coherence.management.readonly |
<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.
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.
The following table describes the elements you can define within the member-identity element.
Element | Required/Optional | Description |
---|---|---|
<cluster-name> | Optional | The cluster-name element contains the name of the cluster. In order to join the cluster all members must specify the same cluster name. It is strongly suggested that cluster-name be specified for production systems, thus preventing accidental cluster discovery among applications. Preconfigured override is tangosol.coherence.cluster |
<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 (i.e. the explicit backing up of data on separate geographic sites). The name is also useful for displaying management information (e.g. 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 override is tangosol.coherence.site. |
<rack-name> | Optional | The rack-name element contains the name of the location within a geographic site that the member is hosted at. 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 (i.e. the explicit backing up of data on separate bladeframes). The name is also useful for displaying management information (e.g. 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 override is tangosol.coherence.rack. |
<machine-name> | Optional | The machine-name element contains the name of the physical server that the member is hosted on. This is often the same name as the server identifies itself as (e.g. 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 (e.g. JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided. Preconfigured override is tangosol.coherence.machine. |
<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 (e.g. JMX) and interpreting log entries. It is optional to provide a value for this element. Often, a single member will exist per JVM, and in that situation this name would be redundant. Preconfigured override is tangosol.coherence.process. |
<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 (e.g. JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided. Preconfigured override is tangosol.coherence.member. |
<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 (e.g. JMX) and interpreting log entries. It is optional to provide a value for this element. However, it is strongly encouraged that a name always be provided. Preconfigured override is tangosol.coherence.role. |
<priority> | Optional | The priority element specifies a priority of the corresponding member. The priority is used as the basis for determining tie-breakers between members. If a condition occurs in which one of two members will be ejected from the cluster, and in the rare case that it is not possible to objectively determine which of the two is at fault and should be ejected, then the member with the lower priority will be ejected. Valid values are from 1 to 10. Preconfigured override is tangosol.coherence.priority. |
Used in: cluster-config.
Specifies the configuration information for the Multicast listener. This element is used to specify the address and port 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 via multicast, see the Multicast Test.
The following table describes the elements you can define within the multicast-listener element.
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 override is tangosol.coherence.clusteraddress |
||
<port> | Required | Specifies the port that the Socket will listen or publish on.
Legal values are from 1 to 65535. Default value depends on the release and build level and typically follows the convention of {version}+{{{build}. For example, for Coherence Release 2.2 build 255 it is 22255. Preconfigured override is tangosol.coherence.clusterport |
||
<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 via a router.
Legal values are from from 0 to 255.
Default value is 4.
|
||
<packet-buffer> | Required | Specifies how many incoming packets the OS 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 via 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 (i.e. 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:
|
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.
Used in: packet-publisher.
The notification-queueing element is used to specificy 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 utilize packet ordering to perform early packet loss detection. This allows Coherence to identify a packet as likely being lost and retransmit it well before the packets scheduled resend time.
The following table describes the elements you can define within the notification-queueing element.
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. |
Used in: cluster-config.
The outgoing-message-handler splits logical messages into packets for transmission on the network, and enqueues them on the packet-publisher.
The following table describes the elements you can define within the outgoing-message-handler element.
Element | Required/Optional | Description |
---|---|---|
<use-daemon> | Optional | Specifies whether or not a daemon thread will be created to perform the outgoing message handling.
Deprecated as of Coherence 3.2, splitting messages into packets is always performed on the message originators thread. |
<use-filters> | Optional | Contains the list of filter
names to be used by this outgoing message handler. For example, specifying use-filter as follows <use-filters> <filter-name>gzip</filter-name> </use-filters> will activate gzip compression for all network messages, which can help substantially with WAN and low-bandwidth networks. |
<priority> | Required | Specifies a priority of the outgoing message handler execution thread.
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.
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 via 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.
The following table describes the elements you can define within the outstanding-packets element.
Used in: unicast-listener, multicast-listener, packet-publisher.
Specifies the size of the OS 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 the originating node will need to detect the packet loss and retransmit the packet(s).
The OS 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.
The following table describes the elements you can define within the packet-buffer element.
Element | Required/Optional | Description |
---|---|---|
<maximum-packets> | Required | For unicast-listener, multicast-listener and packet-publisher: Specifies the number of packets of maximum 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. |
Used in: packet-publisher.
Specifies timing and transmission rate parameters related to packet delivery.
The timeout-milliseconds and heartbeat-milliseconds are used in detecting the death of other cluster nodes.
The following table describes the elements you can define within the packet-delivery element.
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. |
Used in: incoming-message-handler, packet-publisher.
Specifies the number of packets which Coherence will internally maintain for use in tranmitting and receving UDP packets. Unlike the packet-buffers these buffers are managed by Coherence rather then the OS, 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 receiption, this defines the number of packets which can be queued on the incoming-message-handler before the unicast, and multicast must block.
The following table describes the elements you can define within the packet-pool element.
Element | Required/Optional | Description |
---|---|---|
<maximum-packets> | Required | The maximum number of reusable packets to be utilized by the services responsible for publishing and receiving. The pools are intially small, and will grow on demand up to the specified limits. Defaults are 2048 for transmitting and receiving. |
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. The recipient node will delay the ACK, in order to batch a series of ACKs into a single response.
The rate at which the publisher will accept and transmit packet may be controlled via the traffic-jam and packet-delivery/flow-control settings. Throttling may be necessary when dealing with slow networks, or small packet-buffers.
The following table describes the elements you can define within the packet-publisher element.
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 via the Extend protocol.
Default value is true. Preconfigured override is tangosol.coherence.tcmp.enabled. |
<packet-size> | Required | Specifies the UDP packet sizes to utilize. |
<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 OS 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.
Used in: packet-publisher.
The packet-size element specifies the maximum and preferred UDP packet sizes. All cluster nodes must use identical maximum packet sizes. For optimal network utilization this value should be 32 bytes less then the network MTU.
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 the Performance Tuning guide for details. |
The following table describes the elements you can define within the packet-size element.
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. |
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 utilized 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 or not to utilize the speaker as the packet load changes.
The following table describes the elements you can define within the packet-speaker element.
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.
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). Once 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.
The following table describes the elements you can define within the pause-detection element.
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. |
Used in: coherence.
The following table describes the elements you can define within the security-config element.
Element | Required/Optional | Description |
---|---|---|
<enabled> | Required | Specifies whether the security features are enabled. All other configuration elements in the security-config group will be verified for validity and used if and only if the value of this element is true.
Legal values are true or false. Default value is false. Preconfigured override is tangosol.coherence.security |
<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 via 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 Coherence Security Framework to check access rights for clustered resources and encrypt/decrypt node-to-node communications regarding those rights. |
<callback-handler> | Optional | Contains the configuration information for the class that implements javax.security.auth.callback.CallbackHandler interace 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.
Used in: cluster-config.
Specifies the configuration for Coherence services.
The types of services which can be configured includes:
The following table describes the elements you can define for each service element.
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. |
<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:
|
<use-filters> | Optional | Contains the list of filter
names to be used by this service. For example, specifying 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.
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.
The following table describes the elements you can define within the shutdown-listener element.
Element | Required/Optional | Description |
---|---|---|
<enabled> | 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.
|
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.
Used in: well-known-addresses, remote-addresses.
The following table describes the elements you can define within the socket-address element.
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. |
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 utilize the TCP connection to detect the death of another node within a heartbeat interval (default one second). If disabled the cluster node must rely on detecting that another node has stopped responding to UDP packets for a considerately longer interval. Once the death has been detected it is communicated to all other cluster nodes.
The following table describes the elements you can define within the tcp-ring-listener element.
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 override is tangosol.coherence.tcpring |
<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.
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. Once 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 (i.e. > 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 then the flow-control/outstanding-packets/maximum-packets value. When flow-control is disabled the traffic-jam will take all outstanding packets into account.
The following table describes the elements you can define within the traffic-jam element.
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, in order 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. Additionally if the specified port is already in use, Coherence will by default auto increment the port number until the binding succeeds.
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 via multicast, see the Multicast Test.
The following table describes the elements you can define within the unicast-listener element.
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 override is tangosol.coherence.localhost |
<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 override is tangosol.coherence.localport |
<port-auto-adjust> | Required | Specifies whether or not 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 override is tangosol.coherence.localport.adjust |
<packet-buffer> | Required | Specifies how many incoming packets the OS 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 or not 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.
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 utilizing the speaker allows the publisher to continue preparing packets while the speaker transmits them on the network.
The following table describes the elements you can define within the packet-speaker element.
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 socket send buffer size, this is the default. |
Used in: unicast-listener.
Use of the Well Known Addresses (WKA) feature is not supported by Caching Edition. If you are having difficulties in establishing a cluster via multicast, see the Multicast 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.
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. |
The following configuration specifies two well-known-addresses, with the default port.
<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>
The following table describes the elements you can define within the well-known-addresses element.
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 overrides are tangosol.coherence.wka and tangosol.coherence.wka.port. |
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.