# Message Group Example

This example shows you how to configure and use message groups via a connection factory with HornetQ.

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 JMSXGroupID string property values.
- Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the first message of a group will receive all the messages that belongs to the group.

You can make any message belong to a message group by setting a 'group-id' on the connection factory. All producers created via this connection factory will set that group id on its messages. In this example we set the group id 'Group-0'on a connection factory and send messages via 2 different producers and check that only 1 consumer receives them.

Alternatively, HornetQ's connection factories can be configured to auto group messages. By setting `autogroup` to true on the `HornetQConnectionFactory` (or setting `<autogroup>true</autogroup>` in `hornetq-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 `./build.sh` (or `build.bat` on windows) 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 2 JMS message producers on the session. This will be used to send the messages.

                  MessageProducer producer1 = session.createProducer(queue);

                  MessageProducer producer2 = session.createProducer(queue);

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 using each producer

             int msgCount = 10;
             for (int i = 0; i < msgCount; i++)
             {
                TextMessage m = session.createTextMessage("producer1 message " + i);
                producer1.send(m);
                System.out.println("Sent message: " + m.getText());
                TextMessage m2 = session.createTextMessage("producer2 message " + i);
                producer2.send(m2);
                System.out.println("Sent message: " + m2.getText());
             }

9. We start the connection.

               connection.start();

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

                String trueReceiver = messageReceiverMap.get("producer1 message " + 0);
                for (int i = 0; i < msgCount; i++)
                {
                   String receiver = messageReceiverMap.get("producer1 message " + i);
                   if (!trueReceiver.equals(receiver))
                   {
                      System.out.println("Group message [producer1 message " + i + "] went to wrong receiver: " + receiver);
                      result = false;
                   }
                   receiver = messageReceiverMap.get("producer2 message " + i);
                   if (!trueReceiver.equals(receiver))
                   {
                      System.out.println("Group message [producer2 message " + i + "] 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