JMS REST tutorial - HORNETQ REST Interface tutorial

Venkat Nandanavanam
Introduction
HORNETQ is the defualt messaging system provided by JBOSS Application Server. In one of my previous tutorial I covered how to configure, produce and consume Messages through JMS API using HORNETQ as provider. You can find the tutorial @ HERE.
NOTE: This tutorial uses queue named 'restInterfaceQueue'. To know how to create this queue please take a look into the above tutorial.
This tutorial will focus on creating and consuming messages from HORNETQ using REST API.
Why would one ever need to produce and consume messages through REST?
Well!!! I would say to support CROSS LANGUAGE CLIENTS.... and also to provide web based API for messaging. With these capabilities one no longer needs producer and consumer to be through JMS API. So anyone who understands HTTP can produce and consume messages. This one big advantage of REST interface. HORNETQ provides a very good REST interface. Some of the features of REST interface provided by HORNETQ are given below

• Avoid posting of duplicate messages
• Mix and match JMS and REST producers and consumers
• Acknowledgement and auto acknowledgement 

Technologies Used

• JAVA 
• J2EE
• RESTEasy
• HORNETQ 
• HORNETQ REST Interface
• Maven  

Coplete list of features and more information about REST interface and HORNETQ can be found @here. Lets get started!!!! 
Boot strapping HORNETQ with REST
To use HORNETQ REST interface in our application we first need to bootstrap it. This can be done by adding the below listener in web.xml

  org.hornetq.rest.integration.RestMessagingBootstrapListener
 

REST Interface Configuration

We should add some configuration information for REST interface. This can be done in an xml file under WEB-INF/classes. The name of the file should be mentioned in web.xml using rest.messaging.config.file context param

hornetq-rest.xml

   0
   false
   true
   
   true
   topic-push-store
   queue-push-store
   10
   1
   300
   0

The entries in above XML file are explained below
Server-in-vm-id : This is to differentiate different HORNETQ servers running in
same VM. We can default it to zero
Use-link-headers: To tell HORNETQ how to publish the links. By default it publishes
using cutoms headers. This tutorial uses the default behaviour so we can mark it as
false
default-durable-send: Used to identify if the posted message needs to persisted in
DB.We will mark it as false. This default behaviour can be overriddden by sending
durable custom header as true
dups-ok Should duplicate messages be allowed?
client-window-size Used to identify buffering capabilities. By specifying it as zero we are saying we don't want any buffering to happen for delivery of messages.
Now lets take a look at our complete web.xml

 
  rest.messaging.config.file
  hornetq-rest.xml
 

 
  resteasy.resources
  itsvenkis.blogspot.in.rest.services.OrderSrvc
 

 
  resteasy.servlet.mapping.prefix
  /resteasy/hornetq
 

 
  org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
 

 
  org.hornetq.rest.integration.RestMessagingBootstrapListener
 

 
  resteasy
  
   org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
  
 

 
  resteasy
  /resteasy/hornetq/*
 

 
 
    BASIC
 
 
 
  
   Rest-Messaging
   /resteasy/hornetq/queues/*
   GET
   POST
   PUT
   HEAD
   DELETE
  
  
   admin
  
 

We will reuse the modified OrderSrvc.java class here. It has single method which will consume XML message and puts it in Queue using JMS API.

package itsvenkis.blogspot.in.rest.services;

import javax.annotation.Resource;
import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.JMSException;
import javax.jms.MessageProducer;
import javax.jms.ObjectMessage;
import javax.jms.Queue;
import javax.jms.Session;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.apache.log4j.Logger;

/**
 * @author itsvenkis
 *
 */
@Path("/postOrder")
public class OrderSrvc {
 
 private final Logger log = Logger.getLogger(OrderSrvc.class);
 /*
  * Map a JNDI connection factory name.As this service is going to be in same
  * JAVA VM as JMS use "java:/ConnectionFactory". You can find this entry in JBOSS server
  * standalone-full.xml configuration file. 
  */
 @Resource(mappedName = "java:/ConnectionFactory")
 private ConnectionFactory connectionFactory;
 
 /*
  * Map the queue. Note how the queue name is defined here. This should match the context
  * of JNDI defined which is "java" namespace followed by the entry name as given in
  * standalone-full.xml configuration file.
  */
 @Resource(mappedName = "java:/queue/restInterfaceQueue")
 private Queue orderQueue;
 
 @POST
 @Consumes(MediaType.APPLICATION_XML)
 public Response postOrder(String xmlStr) throws JMSException{
  log.debug("Started processing the order....");
  Connection con = null;
  try{
   //In real world you may want to do this only once
   con = connectionFactory.createConnection();
   Session session = con.createSession(false,
     Session.AUTO_ACKNOWLEDGE);
   MessageProducer producer = session.createProducer(orderQueue);
   log.debug("starting HornetQ-JMS connection");
   con.start();
   log.debug("started HornetQ-JMS connection");
   //HORNETQ REST accepts only HTTP or OBJECTMESSAGE
   ObjectMessage objMsg = session.createObjectMessage();
   objMsg.setStringProperty("http_content$type",
     "application/xml");
   objMsg.setObject(xmlStr);
   producer.send(objMsg);
   log.debug("Sent message HornetQ-JMS to QUEUE");
  }catch(JMSException e){
   log.error("Failed to push order to the queue ", e);
  }finally{
   if(con != null){
    try{
     con.close();
    }catch(JMSException e){
     log.error("Unexpected error while trying to close the connection", e);
    }
   }
  }
  return Response.status(200).entity("Received XML").build();
 }

}

As we are using JEE 6 i.e. CDI in OrderSrvc.java we are required to turn it on by using a simple beans.xml under WEB-INF directory. It can be a empty XML file
beans.xml

pom.xml

 4.0.0
 in.itsvenkis.blogspot
 JMS-REST-EXAMPLES
 0.0.1-SNAPSHOT
 war
 A simple HORNETQ examples to demonstrate REST interface
 
  
  jms-rest-examples
  
   
    org.apache.maven.plugins
    maven-war-plugin
    
     
      
       org.hornetq
      
     
    
   
  
 
 
  
   jboss
   http://repository.jboss.org/maven2
  
 
 
  
   org.jboss.resteasy
   resteasy-jaxrs
   3.0.0.Final
  
  
   org.jboss.resteasy
   resteasy-jaxb-provider
   3.0.0.Final
  
  
   org.jboss.spec.javax.jms
   jboss-jms-api_1.1_spec
   1.0.1.Final
  
  
   log4j
   log4j
   1.2.17
  
  
   org.hornetq.rest
   hornetq-rest
   2.3.5.Final
  
 

project structure
dependencies

Now build and deploy the application. We are now ready to consume and produce messages using HORNETQ REST interface.
DEMO
Start your server after deploying the war file

Now post our first message to the queue named "restInterfaceQueue" using REST WS call in OrderSrvc.java. It uses regular JMS API to post the message to queue. url to post the xml message using restclient firefox plugin 'http://localhost:8080/jms-rest-examples/resteasy/hornetq/postOrder'

XML posted

Mumbai

300

f238
OR908765

The message counter for the queue should be 1 now as shown in admin console of our JBOSS server.
Now let us consume this message using REST interface. First we will do a GET request to 'http://localhost:8080/jms-rest-examples/resteasy/hornetq/queues/jms.queue.restInterfaceQueue'. To understand how this URL is formed lets break it into pieces

•  http://localhost:8080/jms-rest-examples- your application context path
• /resteasy/hornetq- As mapped for RESTEasy path in web.xml
• /queues- All REST interface URLS should have queues followed by the original queue name itself which is jms.queue.restInterfaceQueue

As you may have already guessed HORNETQ will retrun us some bunch of custom headers with the GET request. Custom headers returned are shown below

Notice the msg-pull-consumer header returned. We will use that URL to create a service so that we can pull the message from the queue. To create a service do a empty post to the URL as mentioned by msg-pull-consumer header

Below are the custom headers returned from above request.

Notice the 'msg-consume-next' header value returned.Do a POST request to this URL to consume/pull the message from the queue.

below is the consumed message

This network roundtrip is just done once and to consume next message we need not issue the GET request again and start the cycle. Instead we can use 'msg-consume-next' header returned to consume next message and do the polling.If by any chance you miss the URL you can issue a get again to get url values as headers.
Now let us look at Produce an message using REST interface
Do a get request to 'http://localhost:8080/jms-rest-examples/resteasy/hornetq/postOrder' and use 'msg-create' header value and do a post

Notice the headers returned from the above POST request.'msg-create-next: http://localhost:8080/jms-rest-examples/resteasy/hornetq/queues/jms.queue.restInterfaceQueue/create'. Do a post to the URL returned as mentioned by 'msg-create-next' to create a message in the queue

This will create a new message in the queue.
This brings us to the end of the tutorial which covers how to post message and consume message using REST interface.
I was really excited to see producers and consumers via REST interface in JMS queue. If your application needs to support cross platform messaging I would strongly suggest to use REST interface.
Hope this tutorial helps you to understand REST interface. If you have any questions please do not hesitate to ask it in comments section. I will be very happy to answer them.
Dear Readers, kindly like us on facebook or follow me on Google+