JMS Client-Side Load-Balancing Example

This example demonstrates how connnections created from a single JMS Connection factory can be created to different nodes of the cluster. In other words it demonstrates how ActiveMQ does client side load balancing of connections across the cluster.

The particular load-balancing policy can be chosen to be random, round-robin or user-defined. Please see the user guide for more details of how to configure the specific load-balancing policy. In this example we will use the default round-robin load balancing policy.

The list of servers over which ActiveMQ will round-robin the connections can either be specified explicitly in the connection factory when instantiating it directly, when configuring it on the server or configured to use UDP discovery to discover the list of servers over which to round-robin. This example will use UDP discovery to obtain the list.

This example starts three servers which all broadcast their location using UDP discovery. The UDP broadcast configuration can be seen in the activemq-configuration.xml file.

A JMS ConnectionFactory is deployed on each server specifying the discovery group that will be used by that connection factory.

For more information on ActiveMQ load balancing, and clustering in general, please see the clustering section of the user manual.

Example step-by-step

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

1. Get an initial context for looking up JNDI from server 0.

           initialContext = getContext(0);
        

2. Look-up the JMS Queue object from JNDI

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

3. Look-up a JMS Connection Factory object from JNDI on server 0

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

4. We create 3 JMS connections from the same connection factory. Since we are using round-robin load-balancing this should result in each sessions being connected to a different node of the cluster

           
        Connection conn = connectionFactory.createConnection();
        connectionA = connectionFactory.createConnection();
        connectionB = connectionFactory.createConnection();
        connectionC = connectionFactory.createConnection();
        conn.close();
           
        

5. We create JMS Sessions

           
         Session sessionA = connectionA.createSession(false, Session.AUTO_ACKNOWLEDGE);
         Session sessionB = connectionB.createSession(false, Session.AUTO_ACKNOWLEDGE);
         Session sessionC = connectionC.createSession(false, Session.AUTO_ACKNOWLEDGE);
           
        

6. We create JMS MessageProducer objects on the sessions

           
        MessageProducer producerA = sessionA.createProducer(queue);
        MessageProducer producerB = sessionB.createProducer(queue);
        MessageProducer producerC = sessionC.createProducer(queue);
           
        

7. We send some messages on each producer

           
         final int numMessages = 10;

         for (int i = 0; i < numMessages; i++)
         {
            TextMessage messageA = sessionA.createTextMessage("A:This is text message " + i);
            producerA.send(messageA);
            System.out.println("Sent message: " + messageA.getText());
            
            TextMessage messageB = sessionB.createTextMessage("B:This is text message " + i);
            producerB.send(messageB);
            System.out.println("Sent message: " + messageB.getText());
            
            TextMessage messageC = sessionC.createTextMessage("C:This is text message " + i);
            producerC.send(messageC);
            System.out.println("Sent message: " + messageC.getText());            
         }
            
        

8. We start the connection to consume messages

           
       connectionA.start();
       connectionB.start();
       connectionC.start();
           
        

9. We consume messages from the 3 session, one at a time.
   We try to consume one more message than expected from each session. If the session were not properly load-balanced, we would be missing a message from one of the sessions at the end.

            
         consume(sessionA, queue, numMessages, "A");
         consume(sessionB, queue, numMessages, "B");
         consume(sessionC, queue, numMessages, "C");
            
         

10. And finally (no pun intended), always remember to close your JMS 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 (connectionA != null)
         {
            connectionA.close();
         }
         if (connectionB != null)
         {
            connectionB.close();
         }
         if (connectionC != null)
         {
            connectionC.close();
         }

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