Operational Configuration (Full)

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 the Packet publisher will transmit packets on the network, by specif icing the maximum number of packets to transmit without pausing.

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.

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.

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.

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. Note: The use of the Well Known Addressing feature requires an Coherence Enterprise License. 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.

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.

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. See Forums: Coherence Support for details on configuring your OS to allow larger buffers.

Elements

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

packet-delivery

Used in: packet-publisher.

Description

Specifies timing parameters related to reliable 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-publisher

Used in: cluster-config.

Description

Specifies configuration information for the Packet publisher, used for 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 burst-mode and traffic-jam 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 Forums: Coherence Support for details.

Elements

The following table describes the elements you can define within the packet-size 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.

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 pending packets drops below the specified limit. To limit the rate at which the Publisher transmits packets see the burst-mode element.

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 (singles of milliseconds), and that the limit on the number of packets be kept high (i.e. > 5000).

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. Note: Use of the Well Known Addresses (WKA) feature requires a Coherence Enterprise License. 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.

well-known-addresses

Used in: unicast-listener.

Description

Specifies a list of "well known" addresses to use in forming a cluster.

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.

Use of the Well Known Addresses (WKA) feature requires a Coherence Enterprise License.

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