26.3.  Clustered Grouping

Using message groups in a cluster is a bit more complex because messages with a particular group ID can arrive on any node. Each node needs to know which group IDs are bound to which consumer on which node.

The consumer handling messages for a particular group ID may be on a different node of the cluster, so each node needs to know this information so it can route the message correctly to the node which has that consumer.

To solve this there is a grouping handler. Each node has its own grouping handler and when a message is sent with a group ID assigned, the handlers will decide between them which route the message should take.

There are two types of handlers; local and remote. Each cluster should choose one node to have a local grouping handler and all the other nodes should have remote handlers. The Local handler makes the decision regarding what route to use. The remote handlers converse with this. Here is a sample configuration for both types of handler. This should be configured in the <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml file.

<grouping-handler name="my-grouping-handler">
   <type>LOCAL</type>
   <address>jms</address>
   <timeout>5000</timeout>
</grouping-handler>
<grouping-handler name="my-grouping-handler">
   <type>REMOTE</type>
   <address>jms</address>
   <timeout>5000</timeout>
</grouping-handler>

The address attribute refers to a cluster connection and the type of addressing it uses (jms, or core). The timeout attribute refers to how long to wait for a decision to be made (in milliseconds); an exception will be thrown during the send if this timeout is reached. This ensures that strict ordering is kept.

The decision about where a message should be routed is initially proposed by the node that receives the message. The node will pick a suitable route as per the normal clustered routing conditions (that is, circulate available queues, use a local queue first, and choose a queue that has a consumer). If the proposal is accepted by the grouping handlers, the node will route messages to this queue from that point on. If rejected an alternative route will be offered and the node will route to that queue indefinitely. All other nodes will also route to the queue chosen at proposal time. Once the message arrives at the queue, normal single-server message group semantics take over and the message is attached to a consumer on that queue.

You may have noticed that there is a single point of failure with the single local handler. If this node crashes then no decisions will be able to be made. Any sent messages will be not be delivered and an exception will be thrown. To avoid this happening, local handlers can be replicated on another backup node. Simple create your back up node and configure it with the same local handler.