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.

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.


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
<ignore-socket-closed> Required Specifies whether or not the unicast listener will ignore socket exceptions that indicate that a Member is unreachable. Ignoring these exceptions may make the cluster more fault tolerant, but the result will be that unexpected Member deaths will have a detection lag equal to the value of packet-publisher/packet-delivery/resend-milliseconds element.

Legal values are true or false.

Default value is true.
<maximum-socket-closed-exceptions> Required 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.

This value is used only if the value of unicast-listener/ignore-socket-closed is false.

Legal values are integers greater than zero.

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