First, let's look at how to send and receive JMS messages without Spring's support. The following FrontDeskImpl class sends JMS messages with the JMS API directly.

<dependency>
   <groupId>javax.jms</groupId>
   <artifactId>jms</artifactId>
   <version>1.1</version>
 </dependency>

 <dependency>
   <groupId>org.apache.activemq</groupId>
   <version>5.3.0</version>
   <artifactId>activemq-all</artifactId>
 </dependency>

package com.apress.springrecipes.post;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.MapMessage;

import javax.jms.MessageProducer;
import javax.jms.Session;

import org.apache.activemq.ActiveMQConnectionFactory;
import org.apache.activemq.command.ActiveMQQueue;

public class FrontDeskImpl implements FrontDesk {

    public void sendMail(Mail mail) {
        ConnectionFactory cf =
            new ActiveMQConnectionFactory("tcp://localhost:61616");
        Destination destination = new ActiveMQQueue("mail.queue");

        Connection conn = null;
        try {
            conn = cf.createConnection();
            Session session =
                conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
            MessageProducer producer = session.createProducer(destination);

            MapMessage message = session.createMapMessage();
            message.setString("mailId", mail.getMailId());
            message.setString("country", mail.getCountry());
            message.setDouble("weight", mail.getWeight());
            producer.send(message);

            session.close();
        } catch (JMSException e) {
            throw new RuntimeException(e);
        } finally {
            if (conn != null) {
                try {
                    conn.close();
                } catch (JMSException e) {
                }
            }
        }
    }
}

In the preceding sendMail() method, you first create JMS-specific ConnectionFactory and Destination objects with the classes provided by ActiveMQ. The message broker URL is the default for ActiveMQ if you run it on localhost. In JMS, there are two types of destinations: queue and topic. As explained before, a queue is for the point-to-point communication model, while topic is for the publish-subscribe communication model. Because you are sending JMS messages point to point from front desk to back office, you should use a message queue. You can easily create a topic as a destination using the ActiveMQTopic class.

Next, you have to create a connection, session, and message producer before you can send your message. There are several types of messages defined in the JMS API, including TextMessage, MapMessage, BytesMessage, ObjectMessage, and StreamMessage. MapMessage contains message content in key/value pairs like a map. All of them are interfaces, whose super class is simply Message. In the meantime, you have to handle JMSException, which may be thrown by the JMS API. Finally, you must remember to close the session and connection to release system resources. Every time a JMS connection is closed, all its opened sessions will be closed automatically. So you only have to ensure that the JMS connection is closed properly in the finally block.

On the other hand, the following BackOfficeImpl class receives JMS messages with the JMS API directly:

package com.apress.springrecipes.post;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.MessageConsumer;
import javax.jms.Session;

import org.apache.activemq.ActiveMQConnectionFactory;
import org.apache.activemq.command.ActiveMQQueue;

public class BackOfficeImpl implements BackOffice {

    public Mail receiveMail() {
        ConnectionFactory cf =
            new ActiveMQConnectionFactory("tcp://localhost:61616");
        Destination destination = new ActiveMQQueue("mail.queue");

        Connection conn = null;
        try {
            conn = cf.createConnection();
            Session session =
                conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
            MessageConsumer consumer = session.createConsumer(destination);

            conn.start();
            MapMessage message = (MapMessage) consumer.receive();
            Mail mail = new Mail();
            mail.setMailId(message.getString("mailId"));
            mail.setCountry(message.getString("country"));
            mail.setWeight(message.getDouble("weight"));

session.close();
            return mail;
        } catch (JMSException e) {
            throw new RuntimeException(e);
        } finally {
            if (conn != null) {
                try {
                    conn.close();
                } catch (JMSException e) {
                }
            }
        }
    }
}

Most of the code in this method is similar to that for sending JMS messages, except that you create a message consumer and receive a JMS message from it. Note that we used the connection's start() method here, although we didn't in the FrontDeskImpl example before. When using a Connection to receive messages, you can add listeners to the connection that are invoked on receipt of a message, or you can block synchronously, waiting for a message to arrive. The container has no way of knowing which approach you will take and so it doesn't start polling for messages until you've explicitly called start(). If you add listeners or do any kind of configuration, you do so before you invoke start().

Finally, you create two bean configuration files—one for the front desk subsystem (e.g., beans-front.xml), and one for the back office subsystem (e.g., beans-back.xml)—in the root of the classpath.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="frontDesk"
        class="com.apress.springrecipes.post.FrontDeskImpl" />
</beans>

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="backOffice"
        class="com.apress.springrecipes.post.BackOfficeImpl" />
</beans>

Now, your front desk and back office subsystems are ready to send and receive JMS messages. You must start up your message broker before sending and receiving messages with the following main classes. To run them, first run FrontDeskMain and then run BackOfficeMain in another window or console.

package com.apress.springrecipes.post;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class FrontDeskMain {

    public static void main(String[] args) {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans-front.xml");

        FrontDesk frontDesk = (FrontDesk) context.getBean("frontDesk");
        frontDesk.sendMail(new Mail("1234", "US", 1.5));
    }
}

package com.apress.springrecipes.post;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class BackOfficeMain {

    public static void main(String[] args) {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans-back.xml");

        BackOffice backOffice = (BackOffice) context.getBean("backOffice");
        Mail mail = backOffice.receiveMail();
        System.out.println("Mail #" + mail.getMailId() + " received");
    }
}

Spring offers a JMS template that can significantly simplify your JMS code. To send a JMS message with this template, you simply call the send() method and provide a message destination, as well as a MessageCreator object, which creates the JMS message you are going to send. The MessageCreator object is usually implemented as an anonymous inner class.

package com.apress.springrecipes.post;

import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.Session;

import org.springframework.jms.core.JmsTemplate;
import org.springframework.jms.core.MessageCreator;

public class FrontDeskImpl implements FrontDesk {

    private JmsTemplate jmsTemplate;
    private Destination destination;

    public void setJmsTemplate(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    public void setDestination(Destination destination) {
        this.destination = destination;
    }

    public void sendMail(final Mail mail) {
        jmsTemplate.send(destination, new MessageCreator() {
            public Message createMessage(Session session) throws JMSException {
                MapMessage message = session.createMapMessage();
                message.setString("mailId", mail.getMailId());
                message.setString("country", mail.getCountry());
                message.setDouble("weight", mail.getWeight());
                return message;
            }
        });
    }
}

Note that an inner class can access only arguments or variables of the enclosing method that are declared as final. The MessageCreator interface declares only a createMessage() method for you to implement. In this method, you create and return your JMS message with the JMS session provided.

A JMS template helps you to obtain and release the JMS connection and session, and it sends the JMS message created by your MessageCreator object. Moreover, it converts the JMS API's JMSException hierarchy into Spring's JMS runtime exception hierarchy, whose base exception class is org.springframework.jms.JmsException. You can catch the JmsException thrown from send and the other send variants and then take action in the catch block if you want.

In the front desk subsystem's bean configuration file, you declare a JMS template that refers to the JMS connection factory for opening connections. Then, you inject this template as well as the message destination into your front desk bean.

<beans ...>
    <bean id="connectionFactory"
        class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>

    <bean id="mailDestination"
        class="org.apache.activemq.command.ActiveMQQueue">
        <constructor-arg value="mail.queue" />
    </bean>

    <bean id="jmsTemplate"
        class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
    </bean>

    <bean id="frontDesk"
        class="com.apress.springrecipes.post.FrontDeskImpl">
        <property name="destination" ref="mailDestination" />
        <property name="jmsTemplate" ref="jmsTemplate" />
    </bean>
</beans>

To receive a JMS message with a JMS template, you call the receive() method by providing a message destination. This method returns a JMS message, javax.jms.Message, whose type is the base JMS message type (that is, an interface), so you have to cast it into proper type before further processing.

package com.apress.springrecipes.post;

import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.MapMessage;

import org.springframework.jms.core.JmsTemplate;
import org.springframework.jms.support.JmsUtils;

public class BackOfficeImpl implements BackOffice {

    private JmsTemplate jmsTemplate;
    private Destination destination;

    public void setJmsTemplate(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

public void setDestination(Destination destination) {
        this.destination = destination;
    }

    public Mail receiveMail() {
        MapMessage message = (MapMessage) jmsTemplate.receive(destination);
        try {
            if (message == null) {
                return null;
            }
            Mail mail = new Mail();
            mail.setMailId(message.getString("mailId"));
            mail.setCountry(message.getString("country"));
            mail.setWeight(message.getDouble("weight"));
            return mail;
        } catch (JMSException e) {
            throw JmsUtils.convertJmsAccessException(e);
        }
    }
}

However, when extracting information from the received MapMessage object, you still have to handle the JMS API's JMSException. This is in stark contrast to the default behavior of the framework, where it automatically maps exceptions for you when invoking methods on the JmsTemplate. To make the type of the exception thrown by this method consistent, you have to make a call to JmsUtils.convertJmsAccessException() to convert the JMS API's JMSException into Spring's JmsException.

In the back office subsystem's bean configuration file, you declare a JMS template and inject it together with the message destination into your back office bean.

<beans ...>
    <bean id="connectionFactory"
        class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>

    <bean id="mailDestination"
        class="org.apache.activemq.command.ActiveMQQueue">
        <constructor-arg value="mail.queue" />
    </bean>

    <bean id="jmsTemplate"
        class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="receiveTimeout" value="10000" />
    </bean>

<bean id="backOffice"
        class="com.apress.springrecipes.post.BackOfficeImpl">
        <property name="destination" ref="mailDestination" />
        <property name="jmsTemplate" ref="jmsTemplate" />
    </bean>
</beans>

Pay special attention to the receiveTimeout (which specifies how long to wait in milliseconds) property of the JMS template. By default, this template will wait for a JMS message at the destination forever, and the calling thread is blocked in the meantime. To avoid waiting for a message so long, you should specify a receive timeout for this template. If there's no message available at the destination in the duration, the JMS template's receive() method will return a null message.

In your applications, the main use of receiving a message might be because you're expecting a response to something or want to check for messages at an interval, handling the messages and then spinning down until the next interval. If you intend to receive messages and respond to them as a service, you're likely going to want to use the message-driven POJO functionality described later in this chapter. There, we discuss a mechanism that will constantly sit and wait for messages, handling them by calling back into your application as the messages arrive.

Instead of specifying a message destination for each JMS template's send() and receive() method call, you can specify a default destination for a JMS template. Then, you will no longer need to inject it into your message sender and receiver beans again.

<beans ...>
    ...
    <bean id="jmsTemplate"
        class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
           <property name="defaultDestination" ref="mailDestination" />
    </bean>

    <bean id="frontDesk"
        class="com.apress.springrecipes.post.FrontDeskImpl">
        <property name="jmsTemplate" ref="jmsTemplate" />
    </bean>
</beans>

<beans ...>
    ...
    <bean id="jmsTemplate"
        class="org.springframework.jms.core.JmsTemplate">
        <property name="receiveTimeout" value ="10000"/>
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="defaultDestination" ref="mailDestination" />
    </bean>

<bean id="backOffice"
        class="com.apress.springrecipes.post.BackOfficeImpl">
        <property name="jmsTemplate" ref="jmsTemplate" />
    </bean>
</beans>

With the default destination specified for a JMS template, you can delete the setter method for a message destination from your message sender and receiver classes. Now, when you call the send() and receive() methods, you no longer need to specify a message destination.

package com.apress.springrecipes.post;
...
import org.springframework.jms.core.MessageCreator;

public class FrontDeskImpl implements FrontDesk {
    ...
    public void sendMail(final Mail mail) {
        jmsTemplate.send(new MessageCreator() {
            ...
        });
    }
}

package com.apress.springrecipes.post;
...
import javax.jms.MapMessage;
...

public class BackOfficeImpl implements BackOffice {
    ...
    public Mail receiveMail() {
        MapMessage message = (MapMessage) jmsTemplate.receive();
        ...
    }
}

Instead of specifying an instance of the Destination interface for a JMS template, you can specify the destination name to let the JMS template resolve it for you, so you can delete the Destination object's declaration from both bean configuration files.

<bean id="jmsTemplate"
    class="org.springframework.jms.core.JmsTemplate">
    ...
    <property name="defaultDestinationName" value="mail.queue" />
</bean>

Just like your DAO class can extend JdbcDaoSupport to retrieve a JDBC template, your JMS sender and receiver classes can also extend JmsGatewaySupport to retrieve a JMS template. You have the following two options for classes that extend JmsGatewaySupport to create their JMS template:

Of them, the second approach is more suitable if you have to configure the JMS template yourself. You can delete the private field jmsTemplate and its setter method from both your sender and receiver classes. When you need access to the JMS template, you just make a call to getJmsTemplate().

package com.apress.springrecipes.post;

import org.springframework.jms.core.support.JmsGatewaySupport;
...

public class FrontDeskImpl extends JmsGatewaySupport implements FrontDesk {
    ...
    public void sendMail(final Mail mail) {
        getJmsTemplate().send(new MessageCreator() {
            ...
        });
    }
}

package com.apress.springrecipes.post;
...

import org.springframework.jms.core.support.JmsGatewaySupport;

public class BackOfficeImpl extends JmsGatewaySupport implements BackOffice {
    public Mail receiveMail() {
        MapMessage message = (MapMessage) getJmsTemplate().receive();
        ...
    }
}

First, you create a message listener to listen for JMS messages. This negates the need for the approach taken in BackOfficeImpl in previous recipes. For example, the following MailListener listens for JMS messages that contain mail information:

package com.apress.springrecipes.post;

import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.MessageListener;

import org.springframework.jms.support.JmsUtils;

public class MailListener implements MessageListener {

    public void onMessage(Message message) {
        MapMessage mapMessage = (MapMessage) message;
        try {
            Mail mail = new Mail();
            mail.setMailId(mapMessage.getString("mailId"));
            mail.setCountry(mapMessage.getString("country"));
            mail.setWeight(mapMessage.getDouble("weight"));
            displayMail(mail);
        } catch (JMSException e) {
            throw JmsUtils.convertJmsAccessException(e);
        }
    }

    private void displayMail(Mail mail) {
        System.out.println("Mail #" + mail.getMailId() + " received");
    }
}

A message listener must implement the javax.jms.MessageListener interface. When a JMS message arrives, the onMessage() method will be called with the message as the method argument. In this sample, you simply display the mail information to the console. Note that when extracting message information from a MapMessage object, you need to handle the JMS API's JMSException. You can make a call to JmsUtils.convertJmsAccessException() to convert it into Spring's runtime exception JmsException.

Next, you have to configure this listener in the back office's bean configuration file. Declaring this listener alone is not enough to listen for JMS messages. You need a message listener container to monitor JMS messages at a message destination and trigger your message listener on message arrival.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="connectionFactory"
        class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>

<bean id="mailListener"
        class="com.apress.springrecipes.post.MailListener" />

    <bean
        class="org.springframework.jms.listener.SimpleMessageListenerContainer">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="destinationName" value="mail.queue" />
        <property name="messageListener" ref="mailListener" />
    </bean>
</beans>

Spring provides several types of message listener containers for you to choose from in the org.springframework.jms.listener package, of which SimpleMessageListenerContainer and DefaultMessageListenerContainer are the most commonly used. SimpleMessageListenerContainer is the simplest one that doesn't support transaction. If you have a transaction requirement in receiving messages, you have to use DefaultMessageListenerContainer.

Now, you can start your message listener with the following main class, which starts the Spring IoC container only:

package com.apress.springrecipes.post;

import org.springframework.context.support.ClassPathXmlApplicationContext;

public class BackOfficeMain {

    public static void main(String[] args) {
        new ClassPathXmlApplicationContext("beans-back.xml");
    }
}

While a listener that implements the MessageListener interface can listen for messages, so can an arbitrary bean declared in the Spring IoC container. Doing so means that beans are decoupled from the Spring framework interfaces as well as the JMS MessageListener interface. For a method of this bean to be triggered on message arrival, it must accept one of the following types as its sole method argument:

For example, to listen for MapMessage, you declare a method that accepts a map as its argument. This listener no longer needs to implement the MessageListener interface.

package com.apress.springrecipes.post;
...
public class MailListener {

    public void displayMail(Map map) {
        Mail mail = new Mail();
        mail.setMailId((String) map.get("mailId"));
        mail.setCountry((String) map.get("country"));
        mail.setWeight((Double) map.get("weight"));
        System.out.println("Mail #" + mail.getMailId() + " received");
    }
}

A POJO is registered to a listener container through a MessageListenerAdapter instance. This adapter implements the MessageListener interface and will delegate message handling to the target bean's method via reflection.

<beans ...>
    ...
    <bean id="mailListener"
        class="com.apress.springrecipes.post.MailListener" />

    <bean id="mailListenerAdapter"
        class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
        <property name="delegate" ref="mailListener" />
        <property name="defaultListenerMethod" value="displayMail" />
    </bean>

    <bean
        class="org.springframework.jms.listener.SimpleMessageListenerContainer">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="destinationName" value="mail.queue" />
        <property name="messageListener" ref="mailListenerAdapter" />
    </bean>
</beans>

You have to set the delegate property of MessageListenerAdapter to your target bean. By default, this adapter will call the method whose name is handleMessage on that bean. If you want to call another method, you can specify it in the defaultListenerMethod property. Finally, notice that you have to register the listener adapter, not the target bean, with the listener container.

You can also create a message converter for converting mail objects from JMS messages that contain mail information. Because message listeners receive messages only, the method toMessage() will not be called, so you can simply return null for it. However, if you use this message converter for sending messages too, you have to implement this method. The following example reprints the MailMessageConvertor class written earlier:

package com.apress.springrecipes.post;

import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.Session;

import org.springframework.jms.support.converter.MessageConversionException;
import org.springframework.jms.support.converter.MessageConverter;

public class MailMessageConverter implements MessageConverter {

    public Object fromMessage(Message message) throws JMSException,
            MessageConversionException {
        MapMessage mapMessage = (MapMessage) message;
        Mail mail = new Mail();
        mail.setMailId(mapMessage.getString("mailId"));
        mail.setCountry(mapMessage.getString("country"));
        mail.setWeight(mapMessage.getDouble("weight"));
        return mail;
    }

    public Message toMessage(Object object, Session session) throws JMSException,
            MessageConversionException {
        ...
    }
}

A message converter should be applied to a listener adapter for it to convert messages into objects before calling your POJO's methods.

<beans ...>
    ...
    <bean id="mailMessageConverter"
        class="com.apress.springrecipes.post.MailMessageConverter" />

    <bean id="mailListenerAdapter"
        class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
        <property name="delegate" ref="mailListener" />
        <property name="defaultListenerMethod" value="displayMail" />
        <property name="messageConverter" ref="mailMessageConverter" />
    </bean>
</beans>

With this message converter, the listener method of your POJO can accept a mail object as the method argument.

package com.apress.springrecipes.post;

public class MailListener {

    public void displayMail(Mail mail) {
        System.out.println("Mail #" + mail.getMailId() + " received");
    }
}

As mentioned before, SimpleMessageListenerContainer doesn't support transactions. So, if you need transaction management for your message listener method, you have to use DefaultMessageListenerContainer instead. For local JMS transactions, you can simply enable its sessionTransacted property, and your listener method will run within a local JMS transaction (as opposed to XA transactions).

<bean
    class="org.springframework.jms.listener.DefaultMessageListenerContainer">
    <property name="connectionFactory" ref="connectionFactory" />
    <property name="destinationName" value="mail.queue" />
    <property name="messageListener" ref="mailListenerAdapter" />
    <property name="sessionTransacted" value="true" />
</bean>

However, if you want your listener to participate in a JTA transaction, you need to declare a JtaTransactionManager instance and inject it into your listener container.

Spring, from 2.5 and onward, offers a new JMS schema to simplify your JMS listener and listener container configuration. You must add the jms schema definition to the <beans> root element beforehand.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jms="http://www.springframework.org/schema/jms"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/jms
        http://www.springframework.org/schema/jms/spring-jms-3.0.xsd">

    <bean id="connectionFactory"
        class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>

<bean id="transactionManager"
        class="org.springframework.jms.connection.JmsTransactionManager">
        <property name="connectionFactory">
            <ref bean="connectionFactory" />
        </property>
    </bean>

    <bean id="mailMessageConverter"
        class="com.apress.springrecipes.post.MailMessageConverter" />

    <bean id="mailListener"
        class="com.apress.springrecipes.post.MailListener" />

    <jms:listener-container
        connection-factory="connectionFactory"
        transaction-manager="transactionManager"
        message-converter="mailMessageConverter">
        <jms:listener
            destination="mail.queue"
            ref="mailListener" method="displayMail" />
    </jms:listener-container>
</beans>

Actually, you don't need to specify the connection-factory attribute for a listener container explicitly if your JMS connection factory's name is connectionFactory, which can be located by default.