${build.shortName} messaging clusters allow groups of ${build.shortName} messaging servers to be grouped together in order to share message processing load. Each active node in the cluster is an active ${build.shortName} messaging server which manages its own messages and handles its own connections.

The cluster is formed by each node declaring cluster connections to other nodes in the ${build.shortName} configuration file. When a node forms a cluster connection to another node, it internally creates a core api connection between itself and the other node. This is done transparently behind the scenes; you do not have to declare an explicit api for each node. These cluster connections allow messages to flow between the nodes of the cluster to balance the load.

For a complete documentation about clustering, see Clusters Overview.

This section contains the configuration for the following topics:

Broadcast Groups

A broadcast group is the means by which a server broadcasts connectors over the network. A connector defines a way in which a client, or other server, can make connections to the server.

The broadcast group takes a set of connectors and broadcasts them on the network. Depending on which broadcasting technique you configure the cluster, it uses either UDP or JGroups to broadcast connector pairs information.

Broadcast groups are defined in the messaging-activemq subsystem of the server configuration. There can be many broadcast groups per ${build.shortName} messaging server.

Discovery Groups

While the broadcast group defines how connector information is broadcasted from a server, a discovery group defines how connector information is received from a broadcast endpoint, for example, a UDP multicast address or JGroup channel.

A discovery group maintains a list of connectors, one for each broadcast by a different server. As it receives broadcasts on the broadcast endpoint from a particular server, it updates its entry in the list for that server. If it has not received a broadcast from a particular server for a length of time it will remove that server’s entry from its list.

Cluster Connections

Cluster connections group servers into clusters so that messages can be load balanced between the nodes of the cluster. Cluster connections are defined in the ${build.shortName} server configuration using the cluster-connection element. There can be zero or more cluster connections defined per ${build.shortName} messaging server.

Grouping Handlers

In a cluster, message groups with specific group ids can arrive on any of the nodes. It is important for a node to determine which group ids are bound to which consumer on which node. Each node is responsible for routing message groups correctly to the node which has the consumer processing those group ids, irrespective of where the message groups arrive by default. Once messages with a given group id are sent to a specific consumer connected to the given node in the cluster, then those messages are never sent to another node even if the consumer is disconnected.

This situation is addressed by a grouping handler. Each node has a grouping handler and this grouping handler (along with other handlers) is responsible for routing the message groups to the correct node.

Core Bridges

The function of a api is to consume messages from one destination and forward them to another one, typically on a different ${build.shortName} messaging server.

The source and target servers do not have to be in the same cluster which makes bridging suitable for reliably sending messages from one cluster to another, for instance across a WAN, or internet and where the connection may be unreliable.

The api has built-in resilience to failure so if the target server connection is lost, for example, due to network failure, the api will retry connecting to the target until it comes back online. When it comes back online it will resume operation as normal.

Bridges are a way to reliably connect two separate ${build.shortName} messaging servers together. With a core api both source and target servers must be ${build.shortName} messaging servers.