Operational Configuration Elements Reference

access-controller

Used in: security-config.

The following table describes the elements you can define within the access-controller element.

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

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

The following table describes the elements you can define within the authorized-hosts element.

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.

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

Elements

The following table describes the elements you can define within the burst-mode element.

callback-handler

Used in: security-config.

The following table describes the elements you can define within the callback-handler element.

cluster-config

Used in: coherence.

Description

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

Elements

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

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.

coherence

Description

The coherence element is the root element of the operational deployment descriptor.

Elements

The following table describes the elements you can define within the coherence element.

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.

configurable-cache-factory-config

Used in: coherence.

Elements

The following table describes the elements you can define within the configurable-cache-factory-config element.

<init-param>
  <param-type>java.lang.String</param-type>
  <param-value system-property="tangosol.coherence.cacheconfig">
    coherence-cache-config.xml
  </param-value>
</init-param>

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.

filters

Used in: cluster-config.

Description

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.

Implementation

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.

Elements

The following table describes the elements you can define within each filter element.

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

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.

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

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

The following table describes the elements you can define within the flow-control element.

host-range

Used in: authorized-hosts.

Description

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

Elements

The following table describes the elements you can define within each host-range element.

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.

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

The following table describes the elements you can define within the incoming-message-handler element.

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.

init-param

Used in: init-params.

Description

Defines an individual initialization parameter.

Elements

The following table describes the elements you can define within the init-param element.

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.

init-params

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

Description

Defines a series of initialization parameters.

Elements

The following table describes the elements you can define within the init-params element.

license-config

Used in: coherence.

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

logging-config

Used in: coherence.

Elements

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

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.

management-config

Used in: coherence.

Elements

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

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.

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

The following table describes the elements you can define within the member-identity element.

multicast-listener

Used in: cluster-config.

Description

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.

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 via multicast, see the Multicast Test.

Elements

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. For production use, this value should be set to the lowest integer value that works. On a single server cluster, it should work at 0; on a simple switched backbone, it should work at 1; on an advanced backbone with intelligent switching, it may require a value of 2 or more. Setting the value too high can use unnecessary bandwidth on other LAN segments and can even cause the OS or network devices to disable multicast traffic. While a value of 0 is meant to keep packets from leaving the originating machine, some OSs do not implement this correctly, and the packets may in fact be transmitted on the network. Default value is 4. Preconfigured override is tangosol.coherence.ttl
<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 packet is being sent over the network to more than one other node, i.e. (d > 1). The number of nodes is greater than the threshold,i.e. (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 (e.g. 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.

notification-queueing

Used in: packet-publisher.

Description

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.

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

Elements

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

outgoing-message-handler

Used in: cluster-config.

Description

The outgoing-message-handler splits logical messages into packets for transmission on the network, and enqueues them on the packet-publisher.

Elements

The following table describes the elements you can define within the outgoing-message-handler element.

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

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.

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 Tunning

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.

Elements

The following table describes the elements you can define within the outstanding-packets element.

packet-buffer

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

Description

Specifies the size of the OS 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 the originating node will need to detect the packet loss and retransmit the packet(s).

It's just a hint

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.

Elements

The following table describes the elements you can define within the packet-buffer element.

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 are used in detecting the death of other cluster nodes.

Elements

The following table describes the elements you can define within the packet-delivery element.

packet-pool

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

Description

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.

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 receiption, this defines the number of packets which can be queued on the incoming-message-handler before the unicast, and multicast must block.

Elements

The following table describes the elements you can define within the packet-pool element.

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. The recipient node will delay the ACK, in order to batch a series of ACKs into a single response.

Throttling

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.

Elements

The following table describes the elements you can define within the packet-publisher element.

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.

packet-size

Used in: packet-publisher.

Description

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.

Elements

The following table describes the elements you can define within the packet-size element.

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

Elements

The following table describes the elements you can define within the packet-speaker element.

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.

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

Elements

The following table describes the elements you can define within the pause-detection element.

security-config

Used in: coherence.

Elements

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

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.

services

Used in: cluster-config.

Description

Specifies the configuration for Coherence services.

Service Components

The types of services which can be configured includes:

• ReplicatedCache - A cach service which maintains copies of all cache entries on all cluster nodes which run the service.
• ReplicatedCache.Optimistic - A version of the ReplicatedCache which uses optimistic locking.
• DistributedCache - A cache service which evenly partitions cache entries across the cluster nodes which run the service.
• SimpleCache - A version of the ReplicatedCache which lacks concurrent control.
• LocalCache - A cache service for caches where all cache entries reside in a single cluster node.
• InvocationService - A service used for performing custom operations on remote cluster nodes.

Elements

The following table describes the elements you can define for each service element.

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

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

The following table describes the elements you can define within the shutdown-listener element.

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.

socket-address

Used in: well-known-addresses, remote-addresses.

Elements

The following table describes the elements you can define within the socket-address element.

tcp-ring-listener

Used in: cluster-config.

Description

The TCP-ring provides a means for fast death detection of another node within the cluster. When enabled the cluster nodes form a single "ring" of TCP connections spanning the entire cluster. A cluster node is able to 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.

Elements

The following table describes the elements you can define within the tcp-ring-listener element.

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.

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

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 (i.e. > 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 then the flow-control/outstanding-packets/maximum-packets value. When flow-control is disabled the traffic-jam will take all outstanding packets into account.

Elements

The following table describes the elements you can define within the traffic-jam element.

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, in order 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. Additionally if the specified port is already in use, Coherence will by default auto increment the port number until the binding succeeds.

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 via multicast, see the Multicast Test.

Elements

The following table describes the elements you can define within the unicast-listener element.

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.

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 utilizing the speaker allows the publisher to continue preparing packets while the speaker transmits them on the network.

Elements

The following table describes the elements you can define within the packet-speaker element.

well-known-addresses

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.

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.

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.

Example

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>

Elements

The following table describes the elements you can define within the well-known-addresses element.

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.