Message groups are sets of messages that has the following characteristics:
Messages in a message group share the same group id, i.e. they have same group identifier property (JMSXGroupID for JMS, _JBM_GROUP_ID for JBoss Messaging Core API).
Messages in a message group are always consumed by the same consumer, even if there are many consumers on a queue. They pin all messages with the same group id to the same consumer. If that consumer closes another consumer is chosen and will receive all messages with the same group id.
Message grouping must be enabled in the address-setting configuration by using a specific distribution-policy-class:
<address-setting match="jms.queue.exampleQueue"> <distribution-policy-class> org.jboss.messaging.core.server.impl.GroupingRoundRobinDistributor </distribution-policy-class> </address-setting>
By default, distribution-policy-class is set to org.jboss.messaging.core.server.impl.RoundRobinDistributor and message groups will not be handled by the queue. Address wildcards can be used to configure the distribution policy for a set of addresses (see Chapter 11, Understanding the JBoss Messaging Wildcard Syntax).
The property name used to identify the message group is "_JBM_GROUP_ID"" (or the constant MessageImpl.HDR_GROUP_ID). Alternatively, you can set autogroup to true on the SessionFactory which will pick a random unique id.
The property name used to identify the message group is JMSXGroupID.
Within the same group, messages can also set a JMSXGroupSeq int property (starting at 1).
// send 2 messages in the same group to ensure the same // consumer will receive both Message message = ... message.setStringProperty("JMSXGroupID", "Group-0"); message.setIntProperty("JMSXGroupSeq", 1); producer.send(message); message = ... message.setStringProperty("JMSXGroupID", "Group-0"); message.setIntProperty("JMSXGroupSeq", 2); producer.send(message);
Alternatively, you can set autogroup to true on the JBossConnectonFactory which will pick a random unique id. This can also be set in the jbm-jms.xml file like this:
<connection-factory name="ConnectionFactory"> <connector-ref connector-name="netty-connector"/> <entries> <entry name="ConnectionFactory"/> </entries> <autogroup>true</autogroup> </connection-factory>
See Section 9.1.29, “Message Group” for an example which shows how message groups are configured and used with JMS.