The jms setup command sets up a JMS provider for your enterprise application. The jms setup command accepts the following arguments:

The jms setup command creates an application context XML file: applicationContext-jms.xml in SRC_MAIN_RESOURCES/META-INF/spring directory. The applicationContext-jms.xml file configures embedded ActiveMQ broker, JmsTemplate, JMS ConnectionFactory, JMS destinations, and message listener containers.

The following listing shows the embedded ActiveMQ broker configuration in applicationContext-jms.xml:

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core" ...>

  <amq:broker persistent="false" useJmx="true">
    <amq:transportConnectors>
      <amq:transportConnector uri="tcp://localhost:61616"/>
    </amq:transportConnectors>
  </amq:broker>
  ...
</beans>

The amq namespace refers to ActiveMQ schema, which allows configuring ActiveMQ in Spring's application context XML file. The <broker> element configures an embedded ActiveMQ broker whose name is localhost. If you want to specify a custom name for the broker, then you can do so by using brokerName attribute of <broker> element. The persistent attribute specifies whether the JMS messages received by the ActiveMQ broker are persisted into a data store or not. The value false instructs the broker not to persist messages. If you specify true as the value of the persistent attribute, ActiveMQ configures KahaDB as the default data store for messages. The useJmx attribute specifies if broker's services are exposed via JMX. If the attribute value is true, then you can use JMX clients to invoke ActiveMQ broker's services such as start or stop broker, to add or remove topics and queue JMS destinations, and so on. The <transportConnectors> element defines the transport connectors on which ActiveMQ broker listens to a connection from clients. The <transportConnector> element in the given code listing specifies a tcp transport connector that listens on port 61616.

JMS ConnectionFactory is configured in the applicationContext-jms.xml file, as shown here:

<amq:connectionFactory brokerURL="vm://localhost" 
  id="jmsFactory"/>

<bean class="org.springframework.jms.connection.CachingConnectionFactory" id="cachingConnectionFactory">
  <property name="targetConnectionFactory">
    <ref local="jmsFactory"/>
  </property>
</bean>

The <connectionFactory> element of the amq namespace configures a JMS ConnectionFactory . JMS ConnectionFactory is typically configured in the application server and fetched by applications using JNDI. If ConnectionFactory is configured in the application server, then you can make use of the <jndi-lookup> element of Spring's jee schema to obtain it. The brokerURL attribute identifies the URL for connecting to ActiveMQ broker. The value of the brokerURL attribute is vm://localhost, which means that the VM (Virtual Machine) protocol is used by clients to access ActiveMQ broker named localhost. The vm protocol is used because the client (which is flightapp-web application in our case) and broker are located in the same JVM. The use of the VM protocol ensures improved performance because there is no network overhead involved between client and broker communication and the client directly invokes the methods of the broker.

Spring's CachingConnectionFactory class is a JMS ConnectionFactory adapter that caches instances of JMS Session, MessageConsumer, and MessageProducer for improved performance. The targetConnectionFactory property identifies the ConnectionFactory, which the CachingConnectionFactory instance uses to obtain the JMS Connection. The targetConnectionFactory property in the given configuration refers to the JMS ConnectionFactory created by the <connectionFactory> element of the amq namespace.

In the jms setup command, we also passed JMS destination name (myDestination) and type (QUEUE), which JMS add-on uses to configure a JMS queue named myDestination in the applicationContext-jms.xml file, as shown here:

<amq:queue id="myDestination" physicalName="myDestination"/>

Here, the <queue> element of amq namespace configures a JMS queue named myDestination. The physicalName attribute specifies the name of the JMS queue in ActiveMQ. JMS destinations are typically configured in the application server and fetched by applications using JNDI. If JMS destination is configured in the application server, then you can make use of <jndi-lookup> element of Spring's jee schema to fetch it.

Spring's JmsTemplate is also configured in applicationContext-jms.xml file, as shown here:

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

The connectionFactory property refers to the CachingConnectionFactory instance. JmsTemplate defines send methods that accept the JMS Destination object or JMS destination name as the parameter. The defaultDestination property refers to the JMS destination that is used for sending or receiving messages when the send method used doesn't accept the JMS Destination object or JMS destination name as the parameter.

To allow the flighapp-web application to asynchronously receive JMS messages, the jms setup command configures a Spring's message listener container in the applicationContext-jms.xml file, as shown here:

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:jms="http://www.springframework.org/schema/jms" ...>
   ...
   <jms:listener-container connection-factory="jmsFactory"
      destination-type="queue" />
   ...
</beans>

A message listener container receives messages from the JMS provider and dispatches it to a message consumer implementation. The message listener container saves the effort for writing the code that you'll need to write for asynchronous message consumption, which includes registering with the JMS provider, managing transactions, and so on.

In the given configuration, the <listener-container> element of Spring's jms namespace creates a message listener container. The connection-factory attribute identifies the JMS ConnectionFactory that the container uses for creating connections with the JMS provider. The destination-type identifies the JMS destination type (queue, topic, or durable topic) from which the container receives messages. You can add <listener> elements (of Spring's jms namespace) inside <listener-container> to define the message consumers to which the listener container dispatches the messages for processing.

Let's now look at how we send JMS messages using the JmsTemplate class.

The field jms template command autowires the JmsTemplate instance into a class identified by the class argument. The fieldName argument identifies the name of the field with which JmsTemplate is added to the class.

The following code shows the FlightController.java file into which we added the JmsTemplate field using the jms template command:

import org.springframework.jms.core.JmsTemplate;
...
public class FlightController {

    @Autowired
    private transient JmsTemplate jmsTemplate;

    public void sendMessage(Object messageObject) {
        jmsTemplate.convertAndSend(messageObject);
    }
}

The given code shows that the jms template command adds a JmsTemplate field and a sendMessage method to the FlightController class. The sendMessage method accepts Object type as argument, which represents the object that you want to send as a JMS message to the JMS destination. The sendMessage method invokes the convertAndSend method of JmsTemplate, which converts the passed object into a JMS message and sends it to the default destination set by the setDefaultDestination(...) method or specified by the defaultDestination property of JmsTemplate in the application context XML file. In the case of Roo-generated code, the default destination of JmsTemplate is specified by the defaultDestination property (refer to the applicationContext-jms.xml file of the flightapp-web project).

So, you might ask—how is the conversion between an object and JMS message performed? Spring provides a MessageConverter interface, which you can implement to define how to handle conversion from a Java object to a JMS message and vice versa. Spring provides a built-in MessageConverter implementation: SimpleMessageConverter, which is used by default by JmsTemplate and is responsible for conversion between String and JMS TextMessage, byte[] and JMS ByteMessage, Map and JMS MapMessage, and between the Serializable object and JMS ObjectMessage. As Flight and FlightDescription objects in the flightapp-web application implement the Serializable interface, the convertAndSend method of JmsTemplate converts them into JMS ObjectMessage instances.

The jms listener command creates an asynchronous JMS message consumer. If you want your application to synchronously consume messages, then you can use one of the receive methods of JmsTemplate. If you also want to convert the received JMS message into a Java object using SimpleMessageConverter, then you can use receiveAndConvert(...) method of JmsTemplate to receive messages.

The jms listener command creates a message consumer and updates the applicationContext-jms.xml file to create a new message listener container containing the newly created message consumer as a listener. In the case of flightapp-web, the jms listener command creates the MyListener JMS message consumer and adds the following configuration to the applicationContext-jms.xml file:

<bean class="sample.roo.flightapp.web.MyListener" 
    id="myListener"/>

<jms:listener-container connection-factory="jmsFactory" 
     destination-type="queue">
  <jms:listener destination="myDestination" 
     method="onMessage" ref="myListener"/>
</jms:listener-container>

The <bean> element configures MyListener message consumer as a Spring bean.

The <listener> element of Spring's jms namespace defines a message listener to which the message listener container (specified by the enclosing <listener-container> element) dispatches JMS messages for processing. The destination-type attribute of <listener-container> is derived from the value of destinationType argument of jms listener command. The ref attribute refers to the message consumer instance, which is responsible for processing the JMS message. The destination attribute (which corresponds to the destinationName argument value of the jms listener command) identifies the JMS destination from which the message consumer receives JMS messages (via the message container listener) for processing. The method attribute specifies the name of the method of the message consumer class, which is responsible for processing the receive JMS message.

So, by executing jms listener command for flightapp-web we have created a MyListener class, which is responsible for processing JMS messages received by the myDestination JMS destination. The following code listing from MyListener.java shows the Roo-generated MyListener class:

public class MyListener {

  public void onMessage(Object message) {
     System.out.println("JMS message received: " + message);
  }
}

As the given code shows, the Roo-generated message listener doesn't implement any interface or extend any class, and defines an onMessage method which accepts the JMS message as argument. The onMessage doesn't do anything interesting—it simply prints the message on the standard output.

The field jms template command supports an async argument, which you can use to specify that the Roo-generated sendMessage method is annotated with Spring's @Async annotation. An @Async annotated method of an object is executed asynchronously by Spring using java.util.concurrent.ThreadPoolExecutor. If async argument is specified, Roo performs the following actions: