Get started with Spring JMS using ActiveMQ

Messaging is a mechanism to create and exchange data/information/objects within/between applications. An application that generates some useful data can send it's messages (objects) to an agent and these messages (objects) can then be read from another application. JMS is a Java API that enables applications to be able to communicate with each other using the mechanism described above.

You can read more about JMS here.

In this article, we will see how you can quickly start using JMS using the Spring JMS framework. Spring provides template based APIs which greatly simplify the use of JMS. A lot of work is done behind the scenes which saves the developer time to concentrate on the business requirement.

We will take a look at the important Spring JMS classes and apis as we go through an example. So let's get started!



Step 1: Download and install the JMS provided (ActiveMQ)
The first thing you would need is a JMS provider (which is an implementation of the JMS interface for a MOM - Message Oriented Middleware). There are a lot of providers available, such as Apache's ActiveMQ, IBM's WebSphere M, JBoss messaging, RabbitMQ, Oracle AQ and many others.

For the purpose of this tutorial we will be using ActiveMQ. You can download the zip file and install it using the instructions documented here. Start the provider (open a command prompt to the bin folder of the installation and type 'activemq').

To test the setup, browse to : http://localhost:8161/admin/

To be able to send and receive messages asynchronously, we would first need a queue, which is a destination for the messages. Let's create a fresh queue for our sample application.
Go to the 'Queues' menu on the top of the admin page, and create a new queue called 'orderQueue'.

Step 2: Create a Spring project

You can create a spring project manually or use the STS (SpringSource Tool Suite) like i am using. This IDE helps you get started with Spring projects within no time.
Create a 'Spring Utility Project' using 'File -> New -> Spring Template Project -> Simple Spring Utility Project'.

Type the project name , say 'OrderApp' and choose a base package say - com.test.orderapp

This project type uses maven for dependency management. We would need to add a few dependencies for using spring-jms and activemq.

Open the 'pom.xml' at the root of the project and add the following dependencies:

      <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jms</artifactId>
            <version>${spring.framework.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.activemq</groupId>
            <artifactId>activemq-all</artifactId>
            <version>5.4.2</version>
        </dependency>

Note: Update the version for activemq as per the installation you have used in Step 1.

Step 3: Configure beans in application context
Edit the Spring context file app-context.xml at \src\main\resources\META-INF\spring and add the following to it:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:context="http://www.springframework.org/schema/context"
     xmlns:jms="http://www.springframework.org/schema/jms"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context
                           http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/jms
                           http://www.springframework.org/schema/jms/spring-jms.xsd
                           http://activemq.apache.org/schema/core
                           http://activemq.apache.org/schema/core/activemq-core.xsd">

    <context:component-scan base-package="com.test.orderapp" />
    <context:annotation-config/>

    <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL">
            <value>tcp://localhost:61616</value>
        </property>
    </bean>
   
    <bean id="destination" class="org.apache.activemq.command.ActiveMQQueue">
        <constructor-arg value="orderQueue"/>
    </bean>
   
    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="defaultDestination" ref="destination" />
    </bean>
</beans>

Let's take a closer look at the beans we've defined in the spring xml.

1. connectionFactory:

A connectionFactory is required to create a connection to the jms provider i.e. activemq. The javax.jms.ConnectionFactory creates a javax.jms.Connection object, which then creates a javax.jmx.Session object which is used for the message exchange between the application and the jms provider. You need to specify the brocker URL , i.e. the URL at which the jms provider is listening.

2. destination:

The destination specifies the queue name to which the messages will be sent. Messages will be stored in and consumed from the destination specified. Destinations can, in general, be of two types: Queue and Topic. Queues represent a point-to-point messaging mechanism whereas Topics represent a publisher-subscriber sort of messaging where a single message is sent to multiple consumers. (we will be working with only queues in this tutorial)

3. jmsTemplate:

This is the class that does most of the jms related work, it creates connection factories, creates Sessions, takes care of the transactions, provides apis for creating and sending messages of different types. The jmsTemplate bean here takes a reference to the connectionFactory and a defaultDestination to which it would direct the messages. If you don't specify any defaultDestination, you can pass the destination in the 'send' methods that jmsTemplate provides. The important methods provided by jmsTemplate are : send, receive, convertAndSend and receiveAndConvert

Step 4: Create the domain class
We will be creating a simple domain class called 'Order' in a package com.test.orderapp.domain as follows:
 package com.test.orderapp.domain;

public class Order {

    private int orderId;
    private int customerId;
    private double price;
    private String orderCode;
  
    public Order(int orderId, int customerId, double price, String orderCode){
        this.orderId = orderId;
        this.customerId = customerId;
        this.price = price;
        this.orderCode = orderCode;
    }
  
    public int getOrderId() {
        return orderId;
    }
    public void setOrderId(int orderId) {
        this.orderId = orderId;
    }
    public int getCustomerId() {
        return customerId;
    }
    public void setCustomerId(int customerId) {
        this.customerId = customerId;
    }
    public double getPrice() {
        return price;
    }
    public void setPrice(double price) {
        this.price = price;
    }
    public String getOrderCode() {
        return orderCode;
    }
    public void setOrderCode(String orderCode) {
        this.orderCode = orderCode;
    }
}

Step 5: Write the code to send the objects

We will create a simple service class that creates new orders given some information and then sends them.

package com.test.orderapp.producer;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.test.orderapp.domain.Order;

@Service("orderService")
public class OrderService {
    static int orderSequence = 1;
   
    @Autowired
    private OrderSender orderSender;
    public void setOrderSender(OrderSender orderSender){
        this.orderSender = orderSender;
    }
   
    public void sendOrder(int customerId, double price)
    {
        Order order = new Order(orderSequence, 2, price, "ordercd"+ orderSequence++);
        orderSender.sendOrder(order);
    }
}

Nothing special about the service class. We are wiring the  OrderSender class into the service class.
The orderSender class is jms aware and has all the logic to convert and send the domain object as a jms message.

OrderSender.java :-

package com.test.orderapp.producer;

import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.Session;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.jms.core.MessageCreator;
import com.test.orderapp.domain.Order;

public class OrderSender {
   
    @Autowired
    private JmsTemplate jmsTemplate;
   
    public void sendOrder(final Order order){
        jmsTemplate.send(
        new MessageCreator() {
          public Message createMessage(Session session) throws JMSException {
               MapMessage mapMessage = session.createMapMessage();
               mapMessage.setInt("orderId", order.getOrderId());
               mapMessage.setInt("customerId", order.getCustomerId());
               mapMessage.setDouble("price", order.getPrice());
               mapMessage.setString("orderCode", order.getOrderCode());
               return mapMessage;
          }
        }
        );
        System.out.println("Order sent - id: "+ order.getOrderId());
    }
}

The OrderSender uses the JmsTemplate's send method to send the object. Notice the use of the MessageCreator class. You can send different types of messages via JMS eg: TextMessage, ObjectMessage, MapMessage (all part of the java.jms package) The most preferred way to send complex domain objects is to use MapMessage to which you can add all the fields of your domain object as key-value pairs.  The MessageCreator class is a callback interface for creating a message using the Session object that is passed as a parameter to the createMessage method.
Also note, that we are not specifying the destination in the send method since we have defined a defaultDestination for the jmsTemplate in the spring context. In case you are not going the default way, you can pass a string representing the destination as the first parameter to the jmsTemplate.send() method
for eg:      
          jmsTemplate.send( "orderQueue",     new MessageCreator() ..... )

There are other ways to send messages such as MessageConverter which can also be used to convert between Java objects and JMS messages. The convertAndSend and receiveAndConvert methods of the jmsTemplate class delegate the conversion to the MessageConverter interface. We are not using MessageConverter in this tutorial. Some other time maybe...

Let's update the app-context.xml file to declare two additional bean definitions:

<bean id="orderService" class="com.test.orderapp.source.OrderService" />
<bean id="orderSender" class="com.test.orderapp.source.OrderSender" /

Step 6: Test the message producer
Let's check if we are actually able to send any messages to the ActiveMQ 'orderQueue'. We will create a simple TestJms class as follows:

package com.test.orderapp.runner;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import com.test.orderapp.producer.OrderService;

public class TestJms {
    public static void main(String[] args) {
       
        ApplicationContext ctx = new ClassPathXmlApplicationContext("app-context.xml");
        OrderService orderService = (OrderService) ctx.getBean("orderService");
       
        for(int i =1; i<=5; i++)
            orderService.sendOrder(1+i, 10.0D+i);
    }
}

At this point, if you run the TestJms class, 5 messages would be sent to the 'orderQueue' queue. If you browse to the http://localhost:8161/admin/queues.jsp page you should see 5 messages enqueued on orderQueue.


Step 7: Consuming JMS Messages


Listening to the jms messages is in fact easier than sending them. All we need to do is define a jms Listener Container in the spring context to which we pass the connectionFactory bean which specifies the jms provider, a reference to the destination which specifies the queue name and we also specify here, which method from which bean needs to be called when a message is recieved.



Add the following to the app-context.xml file:

<jms:listener-container  connection-factory="connectionFactory">
     <jms:listener destination="orderQueue" ref="orderListener" method="orderReceived" />
</jms:listener-container>

Create a class OrderListener as follows:

package com.test.orderapp.listener;
import java.util.Map;
import org.springframework.stereotype.Component;
import com.test.orderapp.domain.Order;

@Component
public class OrderListener {

    public void orderReceived(Map<String, Object> message) throws Exception {
        int orderId = (Integer) message.get("orderId");
        int customerId = (Integer) message.get("customerId");
        double price = (Double) message.get("price");
        String orderCode = (String) message.get("orderCode");
        Order customer = new Order(orderId, customerId, price, orderCode);
        System.out.println("Order received: "+ orderId + ", customerId: "+ customerId + ", price: "+ price);
      }
}

Simple.

Let's run the TestJms class once again, this time we should see some prints from the OrderListener class too.
Pretty cool, isn't it!

Well, that brings us to the end of the introductory article to Spring JMS, i hope you can now appreciate how much easier it is to write JMS based applications using Spring.

Hope you find this article useful.
Happy coding!

Download the source code of the sample application : OrderApp.rar