This section should be used when you want to use the HornetQ REST interface in an environment that already has HornetQ installed and running, e.g. JBoss AS 7. You must create a Web archive (.WAR) file with the following web.xml settings:

<web-app>
   <listener>
      <listener-class>
         org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
      </listener-class>
   </listener>

   <listener>
      <listener-class>
         org.hornetq.rest.integration.RestMessagingBootstrapListener
      </listener-class>
   </listener>

   <filter>
      <filter-name>Rest-Messaging</filter-name>
      <filter-class>
         org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
      </filter-class>
   </filter>

   <filter-mapping>
      <filter-name>Rest-Messaging</filter-name>
      <url-pattern>/*</url-pattern>
   </filter-mapping>
</web-app>

Within your WEB-INF/lib directory you must have the hornetq-rest.jar file. If RESTEasy is not installed within your environment, you must add the RESTEasy jar files within the lib directory as well. Here's a sample Maven pom.xml that can build your WAR for this case.

<project xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

   <modelVersion>4.0.0</modelVersion>
   <groupId>org.somebody</groupId>
   <artifactId>myapp</artifactId>
   <packaging>war</packaging>
   <name>My App</name>
   <version>0.1-SNAPSHOT</version>
   <repositories>
      <repository>
         <id>jboss</id>
         <url>http://repository.jboss.org/nexus/content/groups/public/</url>
      </repository>
   </repositories>

   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
               <source>1.6</source>
               <target>1.6</target>
            </configuration>
         </plugin>
      </plugins>
   </build>

   <dependencies>
      <dependency>
         <groupId>org.hornetq.rest</groupId>
         <artifactId>hornetq-rest</artifactId>
         <version>2.3.0-SNAPSHOT</version>
      </dependency>
   </dependencies>
</project>

Dependencies: org.hornetq, org.jboss.netty

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-war-plugin</artifactId>
   <configuration>
      <archive>
         <manifestEntries>
            <Dependencies>org.hornetq, org.jboss.netty</Dependencies>
         </manifestEntries>
      </archive>
   </configuration>
</plugin>

It is worth noting that when deploying a WAR in a Java EE application server like AS7 the URL for the resulting application will include the name of the WAR by default. For example, if you've constructed a WAR as described above named "hornetq-rest.war" then clients will access it at, e.g. http://localhost:8080/hornetq-rest/[queues|topics]. We'll see more about this later.

You can bootstrap HornetQ within your WAR as well. To do this, you must have the HornetQ core and JMS jars along with Netty, Resteasy, and the HornetQ REST jar within your WEB-INF/lib. You must also have a hornetq-configuration.xml, hornetq-jms.xml, and hornetq-users.xml config files within WEB-INF/classes. The examples that come with the HornetQ REST distribution show how to do this. You must also add an additional listener to your web.xml file. Here's an example:

<web-app>
   <listener>
      <listener-class>
         org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
      </listener-class>
   </listener>

   <listener>
      <listener-class>
         org.hornetq.rest.integration.HornetqBootstrapListener
      </listener-class>
   </listener>

   <listener>
      <listener-class>
         org.hornetq.rest.integration.RestMessagingBootstrapListener
      </listener-class>
   </listener>

   <filter>
      <filter-name>Rest-Messaging</filter-name>
      <filter-class>
         org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
      </filter-class>
   </filter>

   <filter-mapping>
      <filter-name>Rest-Messaging</filter-name>
      <url-pattern>/*</url-pattern>
   </filter-mapping>
</web-app>

Here's a Maven pom.xml file for creating a WAR for this environment. Make sure your hornetq configuration files are within the src/main/resources directory so that they are stuffed within the WAR's WEB-INF/classes directory!

<project xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

   <modelVersion>4.0.0</modelVersion>
   <groupId>org.somebody</groupId>
   <artifactId>myapp</artifactId>
   <packaging>war</packaging>
   <name>My App</name>
   <version>0.1-SNAPSHOT</version>
   <repositories>
      <repository>
         <id>jboss</id>
         <url>http://repository.jboss.org/nexus/content/groups/public/</url>
      </repository>
   </repositories>
   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
               <source>1.6</source>
               <target>1.6</target>
            </configuration>
         </plugin>
      </plugins>
   </build>
   <dependencies>
      <dependency>
         <groupId>org.hornetq</groupId>
         <artifactId>hornetq-core</artifactId>
         <version>2.3.0-SNAPSHOT</version>
      </dependency>
      <dependency>
         <groupId>io.netty</groupId>
         <artifactId>netty</artifactId>
         <version>3.4.5.Final</version>
      </dependency>
      <dependency>
         <groupId>org.hornetq</groupId>
         <artifactId>hornetq-jms</artifactId>
         <version>2.3.0-SNAPSHOT</version>
      </dependency>
      <dependency>
         <groupId>org.jboss.spec.javax.jms</groupId>
         <artifactId>jboss-jms-api_1.1_spec</artifactId>
         <version>1.0.0.Final</version>
      </dependency>
      <dependency>
         <groupId>org.hornetq.rest</groupId>
         <artifactId>hornetq-rest</artifactId>
         <version>2.3.0-SNAPSHOT</version>
      </dependency>
      <dependency>
         <groupId>org.jboss.resteasy</groupId>
         <artifactId>resteasy-jaxrs</artifactId>
         <version>2.3.4.Final</version>
      </dependency>
      <dependency>
         <groupId>org.jboss.resteasy</groupId>
         <artifactId>resteasy-jaxb-provider</artifactId>
         <version>2.3.4.Final</version>
      </dependency>
   </dependencies>
</project>

The HornetQ REST implementation does have some configuration options. These are configured via XML configuration file that must be in your WEB-INF/classes directory. You must set the web.xml context-param rest.messaging.config.file to specify the name of the configuration file. Below is the format of the XML configuration file and the default values for each.

<rest-messaging>
   <server-in-vm-id>0</server-in-vm-id>
   <use-link-headers>false</use-link-headers>
   <default-durable-send>false</default-durable-send>
   <dups-ok>true</dups-ok>
   <topic-push-store-dir>topic-push-store</topic-push-store-dir>
   <queue-push-store-dir>queue-push-store</queue-push-store-dir>
   <producer-time-to-live>0</producer-time-to-live>
   <producer-session-pool-size>10</producer-session-pool-size>
   <session-timeout-task-interval>1</session-timeout-task-interval>
   <consumer-session-timeout-seconds>300</consumer-session-timeout-seconds>
   <consumer-window-size>-1</consumer-window-size>
</rest-messaging>

Let's give an explanation of each config option.

To interact with a queue or topic you do a HEAD or GET request on the following relative URI pattern:

/queues/{name}
/topics/{name}

The base of the URI is the base URL of the WAR you deployed the HornetQ REST server within as defined in the Installation and Configuration section of this document. Replace the {name} string within the above URI pattern with the name of the queue or topic you are interested in interacting with. For example if you have configured a JMS topic named "foo" within your hornetq-jms.xml file, the URI name should be "jms.topic.foo". If you have configured a JMS queue name "bar" within your hornetq-jms.xml file, the URI name should be "jms.queue.bar". Internally, HornetQ prepends the "jms.topic" or "jms.queue" strings to the name of the deployed destination. Next, perform your HEAD or GET request on this URI. Here's what a request/response would look like.

HEAD /queues/jms.queue.bar HTTP/1.1
Host: example.com

--- Response ---
HTTP/1.1 200 Ok
msg-create: http://example.com/queues/jms.queue.bar/create
msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers

curl --head http://example.com/queues/jms.queue.bar

The HEAD or GET response contains a number of custom response headers that are URLs to additional REST resources that allow you to interact with the queue or topic in different ways. It is important not to rely on the scheme of the URLs returned within these headers as they are an implementation detail. Treat them as opaque and query for them each and every time you initially interact (at boot time) with the server. If you treat all URLs as opaque then you will be isolated from implementation changes as the HornetQ REST interface evolves over time.

Below is a list of response headers you should expect when interacting with a Queue resource.

Below is a list of response headers you should expect when interacting with a Topic resource.

Sometimes you might have network problems when posting new messages to a queue or topic. You may do a POST and never receive a response. Unfortunately, you don't know whether or not the server received the message and so a re-post of the message might cause duplicates to be posted to the queue or topic. By default, the HornetQ REST interface is configured to accept and post duplicate messages. You can change this by turning on duplicate message detection by setting the dups-ok config option to false as described in HornetQ REST Interface Basics. When you do this, the initial POST to the msg-create URL will redirect you, using the standard HTTP 307 redirection mechanism to a unique URL to POST to. All other interactions remain the same as discussed earlier. Here's an example:

How can this work? As you can see, with each successful response, the HornetQ REST server returns a uniquely generated URL within the msg-create-next header. This URL is dedicated to the next new message you want to post. Behind the scenes, the code extracts an identify from the URL and uses HornetQ's duplicate detection mechanism by setting the DUPLICATE_DETECTION_ID property of the JMS message that is actually posted to the system.

If you happen to use the same ID more than once you'll see a message like this on the server:

WARN  [org.hornetq.core.server] (Thread-3 (HornetQ-remoting-threads-HornetQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) HQ112098: Duplicate message detected - message will not be routed. Message information:
ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _HQ_DUPL_ID=42}]]@12835058

An alternative to this approach is to use the msg-create-with-id header. This is not an invokable URL, but a URL template. The idea is that the client provides the DUPLICATE_DETECTION_ID and creates its own create-next URL. The msg-create-with-id header looks like this (you've see it in previous examples, but we haven't used it):

msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}

You see that it is a regular URL appended with a {id}. This {id} is a pattern matching substring. A client would generate its DUPLICATE_DETECTION_ID and replace {id} with that generated id, then POST to the new URL. The URL the client creates works exactly like a create-next URL described earlier. The response of this POST would also return a new msg-create-next header. The client can continue to generate its own DUPLICATE_DETECTION_ID, or use the new URL returned via the msg-create-next header.

The advantage of this approach is that the client does not have to repost the message. It also only has to come up with a unique DUPLICATE_DETECTION_ID once.

By default, posted messages are not durable and will not be persisted in HornetQ's journal. You can create durable messages by modifying the default configuration as expressed in Chapter 2 so that all messages are persisted when sent. Alternatively, you can set a URL query parameter called durable to true when you post your messages to the URLs returned in the msg-create, msg-create-with-id, or msg-create-next headers. here's an example of that.

POST /queues/jms.queue.bar/create?durable=true
Host: example.com
Content-Type: application/xml

<order>
   <name>Bill</name>
   <item>iPhone4</item>
   <cost>$199.99</cost>
</order>

You can set the time to live, expiration, and/or the priority of the message in the queue or topic by setting an additional query parameter. The expiration query parameter is an long specify the time in milliseconds since epoch (a long date). The ttl query parameter is a time in milliseconds you want the message active. The priority is another query parameter with an integer value between 0 and 9 expressing the priority of the message. i.e.:

POST /queues/jms.queue.bar/create?expiration=30000&priority=3
Host: example.com
Content-Type: application/xml

<order>
   <name>Bill</name>
   <item>iPhone4</item>
   <cost>$199.99</cost>
</order>

This section focuses on the auto-acknowledge protocol for consuming messages via a pull. Here's a list of the response headers and URLs you'll be interested in.

The manual acknowledgement protocol is similar to the auto-ack protocol except there is an additional round trip to the server to tell it that you have received the message and that the server can internally ack the message. Here is a list of the response headers you will be interested in.

Unless your queue or topic has a high rate of message flowing though it, if you use the pull protocol, you're going to be receiving a lot of 503 responses as you continuously pull the server for new messages. To alleviate this problem, the HornetQ REST interface provides the Accept-Wait header. This is a generic HTTP request header that is a hint to the server for how long the client is willing to wait for a response from the server. The value of this header is the time in seconds the client is willing to block for. You would send this request header with your pull requests. Here's an example:

POST /queues/jms.queue.bar/pull-consumers/consume-next-2
Host: example.com
Accept-Wait: 30

--- Response ---
HTTP/1.1 200 Ok
Content-Type: application/xml
msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3

<order>...</order>

In this example, we're posting to a msg-consume-next URL and telling the server that we would be willing to block for 30 seconds.

When the client is done with its consumer or topic subscription it should do an HTTP DELETE call on the consumer URL passed back from the Location header or the msg-consumer response header. The server will time out a consumer with the value of consumer-session-timeout-seconds configured from REST configuration, so you don't have to clean up if you don't want to, but if you are a good kid, you will clean up your messes. A consumer timeout for durable subscriptions will not delete the underlying durable JMS subscription though, only the server-side consumer resource (and underlying JMS session).

Creating a push consumer for a queue first involves creating a very simple XML document. This document tells the server if the push subscription should survive server reboots (is it durable). It must provide a URL to ship the forwarded message to. Finally, you have to provide authentication information if the final endpoint requires authentication. Here's a simple example:

<push-registration>
   <durable>false</durable>
   <selector><![CDATA[
   SomeAttribute > 1
   ]]>
   </selector>
   <link rel="push" href="http://somewhere.com" type="application/json" method="PUT"/>
   <maxRetries>5</maxRetries>
   <retryWaitMillis>1000</retryWaitMillis>
   <disableOnFailure>true</disableOnFailure>
</push-registration>

The durable element specifies whether the registration should be saved to disk so that if there is a server restart, the push subscription will still work. This element is not required. If left out it defaults tofalse. If durable is set to true, an XML file for the push subscription will be created within the directory specified by the queue-push-store-dir config variable defined in Chapter 2 (topic-push-store-dir for topics).

The selector element is optional and defines a JMS message selector. You should enclose it within CDATA blocks as some of the selector characters are illegal XML.

The maxRetries element specifies how many times a the server will try to push a message to a URL if there is a connection failure.

The retryWaitMillis element specifies how long to wait before performing a retry.

The disableOnFailure element, if set to true, will disable the registration if all retries have failed. It will not disable the connection on non-connection-failure issues (like a bad request for instance). In these cases, the dead letter queue logic of HornetQ will take over.

The link element specifies the basis of the interaction. The href attribute contains the URL you want to interact with. It is the only required attribute. The type attribute specifies the content-type of what the push URL is expecting. The method attribute defines what HTTP method the server will use when it sends the message to the server. If it is not provided it defaults to POST. The rel attribute is very important and the value of it triggers different behavior. Here's the values a rel attribute can have:

The push XML for a topic is the same except the root element is push-topic-registration. (Also remember the selector element is optional). The rest of the document is the same. Here's an example of a template registration:

<push-topic-registration>
   <durable>true</durable>
   <selector><![CDATA[
   SomeAttribute > 1
   ]]>
   </selector>
   <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
</push-topic registration>

Creating a push subscription at runtime involves getting the factory resource URL from the msg-push-consumers header, if the destination is a queue, or msg-push-subscriptions header, if the destination is a topic. Here's an example of creating a push registration for a queue:

Here's an example of creating a push registration for a topic:

You can create a push XML file yourself if you do not want to go through the REST interface to create a push subscription. There is some additional information you need to provide though. First, in the root element, you must define a unique id attribute. You must also define a destination element to specify the queue you should register a consumer with. For a topic, the destination element is the name of the subscription that will be created. For a topic, you must also specify the topic name within the topic element.

Here's an example of a hand-created queue registration. This file must go in the directory specified by the queue-push-store-dir config variable defined in Chapter 2:

<push-registration id="111">
   <destination>jms.queue.bar</destination>
   <durable>true</durable>
   <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
</push-registration>

Here's an example of a hand-created topic registration. This file must go in the directory specified by the topic-push-store-dir config variable defined in Chapter 2:

<push-topic-registration id="112">
   <destination>my-subscription-1</destination
   <durable>true</durable>
   <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
   <topic>jms.topic.foo</topic>
</push-topic-registration>

Push subscriptions only support BASIC and DIGEST authentication out of the box. Here is an example of adding BASIC authentication:

<push-topic-registration>
   <durable>true</durable>
   <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
   <authentication>
      <basic-auth>
         <username>guest</username>
         <password>geheim</password>
      </basic-auth>
   </authentication>
</push-topic registration>

For DIGEST, just replace basic-auth with digest-auth.

For other authentication mechanisms, you can register headers you want transmitted with each request. Use the header element with the name attribute representing the name of the header. Here's what custom headers might look like:

<push-topic-registration>
   <durable>true</durable>
   <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
   <header name="secret-header">jfdiwe3321</header>
</push-topic registration>

Securing the HornetQ REST interface is very simple with the JBoss Application Server. You turn on authentication for all URLs within your WAR's web.xml, and let the user Principal to propagate to HornetQ. This only works if you are using the JBossSecurityManager with HornetQ. See the HornetQ documentation for more details.

To secure the HornetQ REST interface in other environments you must role your own security by specifying security constraints with your web.xml for every path of every queue and topic you have deployed. Here is a list of URI patterns:

If you have a JMS producer, the HornetQ REST interface only supports ObjectMessage type. If the JMS producer is aware that there may be REST consumers, it should set a JMS property to specify what Content-Type the Java object should be translated into by REST clients. The HornetQ REST server will use RESTEasy content handlers (MessageBodyReader/Writers) to transform the Java object to the type desired. Here's an example of a JMS producer setting the content type of the message.

ObjectMessage message = session.createObjectMessage();
message.setStringProperty(org.hornetq.rest.HttpHeaderProperty.CONTENT_TYPE, "application/xml");

If the JMS producer does not set the content-type, then this information must be obtained from the REST consumer. If it is a pull consumer, then the REST client should send an Accept header with the desired media types it wants to convert the Java object into. If the REST client is a push registration, then the type attribute of the link element of the push registration should be set to the desired type.

If you have a REST client producing messages and a JMS consumer, HornetQ REST has a simple helper class for you to transform the HTTP body to a Java object. Here's some example code:

public void onMessage(Message message)
{
   MyType obj = org.hornetq.rest.Jms.getEntity(message, MyType.class);
}

The way the getEntity() method works is that if the message is an ObjectMessage, it will try to extract the desired type from it like any other JMS message. If a REST producer sent the message, then the method uses RESTEasy to convert the HTTP body to the Java object you want. See the Javadoc of this class for more helper methods.