Appendix C. Cluster Connection Configuration Elements

The table below lists all of the configuration elements of a cluster-connection.

Table C.1. Cluster Connection Configuration Elements

NameDescription

address

Each cluster connection applies only to addresses that match the value specified in the address field. If no address is specified, then all addresses will be load balanced.

The address field also supports comma separated lists of addresses. Use exclude syntax, ! to prevent an address from being matched. Below are some example addresses:

jms.eu
Matches all addresses starting with jms.eu.
!jms.eu
Matches all addresses except for those starting with jms.eu
jms.eu.uk,jms.eu.de
Matches all addresses starting with either jms.eu.uk or jms.eu.de
jms.eu,!jms.eu.uk
Matches all addresses starting with jms.eu, but not those starting with jms.eu.uk
Note

You should not have multiple cluster connections with overlapping addresses (for example, "europe" and "europe.news"), because the same messages could be distributed between more than one cluster connection, possibly resulting in duplicate deliveries.

call-failover-timeout

Use when a call is made during a failover attempt. The default is -1, or no timeout.

call-timeout

When a packet is sent over a cluster connection, and it is a blocking call, call-timeout determines how long the broker will wait (in milliseconds) for the reply before throwing an exception. The default is 30000.

check-period

The interval, in milliseconds, between checks to see if the cluster connection has failed to receive pings from another broker. The default is 30000.

confirmation-window-size

The size, in bytes, of the window used for sending confirmations from the broker connected to. When the broker receives confirmation-window-size bytes, it notifies its client. The default is 1048576. A value of -1 means no window.

connector-ref

Identifies the connector that will be transmitted to other brokers in the cluster so that they have the correct cluster topology. This parameter is mandatory.

connection-ttl

Determines how long a cluster connection should stay alive if it stops receiving messages from a specific broker in the cluster. The default is 60000.

discovery-group-ref

Points to a discovery-group to be used to communicate with other brokers in the cluster. This element must include the attribute discovery-group-name, which must match the name attribute of a previously configured discovery-group.

initial-connect-attempts

Sets the number of times the system will try to connect a broker in the cluster initially. If the max-retry is achieved, this broker will be considered permanently down, and the system will not route messages to this broker. The default is -1, which means infinite retries.

max-hops

Configures the broker to load balance messages to brokers which might be connected to it only indirectly with other brokers as intermediates in a chain. This allows for more complex topologies while still providing message load-balancing. The default value is 1, which means messages are distributed only to other brokers directly connected to this broker. This parameter is optional.

max-retry-interval

The maximum delay for retries, in milliseconds. The default is 2000.

message-load-balancing

Determines whether and how messages will be distributed between other brokers in the cluster. Include the message-load-balancing element to enable load balancing. The default value is ON_DEMAND. You can provide a value as well. Valid values are:

OFF
Disables load balancing.
STRICT
Forwards messages to all brokers that have a matching queue, whether or not the queue has an active consumer or a matching selector.
ON_DEMAND
Ensures that messages are forwarded only to brokers that have active consumers or a matching selector.

min-large-message-size

If a message size, in bytes, is larger than min-large-message-size, it will be split into multiple segments when sent over the network to other cluster members. The default is 102400.

notification-attempts

Sets how many times the cluster connection should broadcast itself when connecting to the cluster. The default is 2.

notification-interval

Sets how often, in milliseconds, the cluster connection should broadcast itself when attaching to the cluster. The default is 1000.

producer-window-size

The size, in bytes, for producer flow control over cluster connection. By default, it is disabled, but you may want to set a value if you are using really large messages in cluster. A value of -1 means no window.

reconnect-attempts

Sets the number of times the system will try to reconnect to a broker in the cluster. If the max-retry is achieved, this broker will be considered permanently down and the system will stop routing messages to this broker. The default is -1, which means infinite retries.

retry-interval

Determines the interval, in milliseconds, between retry attempts. If the cluster connection is created and the target broker has not been started or is booting, then the cluster connections from other brokers will retry connecting to the target until it comes back up. This parameter is optional. The default value is 500 milliseconds.

retry-interval-multiplier

The multiplier used to increase the retry-interval after each reconnect attempt. The default is 1.

use-duplicate-detection

Cluster connections use bridges to link the brokers, and bridges can be configured to add a duplicate ID property in each message that is forwarded. If the target broker of the bridge crashes and then recovers, messages might be resent from the source broker. By setting use-duplicate-detection to true, any duplicate messages will be filtered out and ignored on receipt at the target broker. The default is true.