Chapter 12. Message Grouping

Message groups are sets of messages that have the following characteristics:

  • Messages in a message group share the same group ID, that is, they have same group identifier property. For JMS messages, the property is JMSXGroupID.
  • Messages in a message group are always consumed by the same consumer, even if there are many consumers on a queue. Another consumer is chosen to receive a message group if the original consumer closes.

Message groups are useful when you want all messages for a certain value of the property to be processed serially by the same consumer. For example, you may want orders for any particular stock purchase to be processed serially by the same consumer. To do this you could create a pool of consumers, then set the stock name as the value of the message property. This ensures that all messages for a particular stock are always processed by the same consumer.

Note

Grouped messages might impact the concurrent processing of non-grouped messages due to the underlying FIFO semantics of a queue. For example, if there is a chunk of 100 grouped messages at the head of a queue followed by 1,000 non-grouped messages, all the grouped messages are sent to the appropriate client before any of the non-grouped messages are consumed. The functional impact in this scenario is a temporary suspension of concurrent message processing while all the grouped messages are processed. Keep this potential performance bottleneck in mind when determining the size of your message groups. Consider whether to isolate your grouped messages from your non-grouped messages.

12.1. Client-Side Message Grouping

The examples below show how to use message grouping using Core JMS clients.

Procedure

  • Set the group ID.

    • If you are using JNDI to establish a JMS connection factory for your JMS client, add the groupID parameter and supply a value. All messages sent using this connection factory have the property JMSXGroupID set to the specified value. 

      java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.myConnectionFactory=tcp://localhost:61616?groupID=MyGroup

    • If you are not using JNDI, set the JMSXGroupID property using the setStringProperty() method. 

       Message message = new TextMessage();
 message.setStringProperty("JMSXGroupID", "MyGroup");
 producer.send(message);

Related Information

See mesagge-group and message-group2 under INSTALL_DIR/examples/features/standard for working examples of how message groups are configured and used.

12.2. Automatic Message Grouping

Instead of supplying a group ID yourself, you can have the ID automatically generated for you. Messages grouped in this way are still processed serially by a single consumer.

Procedure

The examples below show how to enable message grouping using Core JMS clients.

  • Enable automatic generation of the group ID.

    • If you are using a JNDI context environment to instantiate your JMS connection factory, add the autogroup=true name-value pair to the query string of the connection URL. 

      java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.myConnectionFactory=tcp://localhost:61616?autoGroup=true

    • If you are not using JNDI, set autogroup to true on the ActiveMQConnectonFactory. 

      ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
cf.setAutoGroup(true);