Message Group Example

This example shows you how to configure and use message groups with ActiveMQ.

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

You can make any message belong to a message group by setting its 'JMXGroupID' string property to the group id. In this example we create a message group 'Group-0'. And make such a message group of 10 messages. It also create two consumers on the queue where the 10 'Group-0' group messages are to be sent. You can see that with message grouping enabled, all the 10 messages will be received by the first consumer. The second consumer will receive none.

Alternatively, ActiveMQ's connection factories can be configured to auto group messages. By setting autogroup to true on the ActiveMQConnectionFactory (or setting <autogroup>true</autogroup> in activemq-jms.xml's connection factory settings), a random unique id will be picked to create a message group. Every messages sent by a producer created from this connection factory will automatically be part of this message group.

Example step-by-step

To run the example, simply type mvn verify -Pexample from this directory

1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config

           InitialContext initialContext = getContext();
        

2. We look-up the JMS queue object from JNDI

           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
        

3. We look-up the JMS connection factory object from JNDI

           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
        

4. We create a JMS connection

           connection = cf.createConnection();
        

5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.

           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
        

6. We create a JMS message producer on the session. This will be used to send the messages.

          MessageProducer messageProducer = session.createProducer(topic);
       

7. We create two consumers.

           
          MessageConsumer consumer1 = session.createConsumer(queue);
          consumer1.setMessageListener(new SimpleMessageListener("consumer-1"));
          MessageConsumer consumer2 = session.createConsumer(queue);
          consumer2.setMessageListener(new SimpleMessageListener("consumer-2"));
          
        

8. We create and send 10 text messages with group id 'Group-0'

           
         int msgCount = 10;
         TextMessage[] groupMessages = new TextMessage[msgCount];
         for (int i = 0; i < msgCount; i++)
         {
            groupMessages[i] = session.createTextMessage("Group-0 message " + i);
            groupMessages[i].setStringProperty("JMSXGroupID", "Group-0");
            producer.send(groupMessages[i]);
            System.out.println("Sent message: " + groupMessages[i].getText());
         }
           
        

9. We start the connection.

           connection.start();
        

10. We check the group messages are received by only one consumer

           
         String trueReceiver = messageReceiverMap.get(groupMessages[0].getText());
         for (TextMessage grpMsg : groupMessages)
         {
            String receiver = messageReceiverMap.get(grpMsg.getText());
            if (!trueReceiver.equals(receiver))
            {
               System.out.println("Group message [" + grpMsg.getText() + "[ went to wrong receiver: " + receiver);
               result = false;
            }
         }
           
        

11. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects

           finally
           {
              if (initialContext != null)
              {
                initialContext.close();
              }
              if (connection != null)
              {
                 connection.close();
              }
           }
        

More information

• User Manual's Message Grouping chapter