HornetQ Rest Guide

Copyright © 2010 Red Hat, Inc. and others.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA").

An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

What is HornetQ?

Why use HornetQ? Here are just a few of the reasons:

The HornetQ REST interface allows you to leverage the reliability and scalability features of HornetQ over a simple REST/HTTP interface. Messages are produced and consumed by sending and receiving simple HTTP messages that contain the content you want to push around. For instance, here's a simple example of posting an order to an order processing queue express as an HTTP message:

POST /queue/orders/create HTTP/1.1
Host: example.com
Content-Type: application/xml

<order>
   <name>Bill</name>
   <item>iPhone 4</item>
   <cost>$199.99</cost>
</order>

As you can see, we're just posting some arbitrary XML document to a URL. When the XML is received on the server is it processed within HornetQ as a JMS message and distributed through core HornetQ. Simple and easy. Consuming messages from a queue or topic looks very similar. We'll discuss the entire interface in detail later in this docbook.

HornetQ's REST interface is installed as a Web archive (WAR). It depends on the RESTEasy project and can currently only run within a servlet container. Installing the HornetQ REST interface is a little bit different depending whether HornetQ is already installed and configured for your environment (e.g. you're deploying within JBoss AS 7) or you want the HornetQ REST WAR to startup and manage the HornetQ server (e.g. you're deploying within Tomcat).

<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

<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>

<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>

<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>

<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

The HornetQ REST interface publishes a variety of REST resources to perform various tasks on a queue or topic. Only the top-level queue and topic URI schemes are published to the outside world. You must discover all over resources to interact with by looking for and traversing links. You'll find published links within custom response headers and embedded in published XML representations. Let's look at how this works.

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

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-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers

This chapter discusses the protocol for posting messages to a queue or a topic. In Chapter 3, you saw that a queue or topic resource publishes variable custom headers that are links to other RESTful resources. The msg-create header is the URL you post messages to. Messages are published to a queue or topic by sending a simple HTTP message to the URL published by the msg-create header. The HTTP message contains whatever content you want to publish to the HornetQ destination. Here's an example scenario:

It is VERY IMPORTENT that you never re-use returned msg-create-next headers to post new messages. This URL may be uniquely generated for each message and used for duplicate detection. If you lose the URL within the msg-create-next header, then just go back to the queue or topic resource to get the msg-create URL.

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

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>

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>

There are two different ways to consume messages from a topic or queue. You can wait and have the messaging server push them to you, or you can continuously poll the server yourself to see if messages are available. This chapter discusses the latter. Consuming messages via a pull works almost identically for queues and topics with some minor, but important caveats. To start consuming you must create a consumer resource on the server that is dedicated to your client. Now, this pretty much breaks the stateless principle of REST, but after much prototyping, this is the best way to work most effectively with HornetQ through a REST interface.

You create consumer resources by doing a simple POST to the URL published by the msg-pull-consumers response header if you're interacting with a queue, the msg-pull-subscribers response header if you're interacting with a topic. These headers are provided by the main queue or topic resource discussed in Chapter 3. Doing an empty POST to one of these URLs will create a consumer resource that follows an auto-acknowledge protocol and, if you're interacting with a topic, creates a temporty subscription to the topic. If you want to use the acknowledgement protocol and/or create a durable subscription (topics only), then you must use the form parameters (application/x-www-form-urlencoded) described below.

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>

You can configure the HornetQ REST server to push messages to a registered URL either remotely through the REST interface, or by creating a pre-configured XML file for the HornetQ REST server to load at boot time.

<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>

<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>

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

<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-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>

<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>

You can create a durable queue or topic through the REST interface. Currently you cannot create a temporary queue or topic. To create a queue you do a POST to the relative URL /queues with an XML representation of the queue. The XML syntax is the same queue syntax that you would specify in hornetq-jms.xml if you were creating a queue there. For example:

POST /queues
 Host: example.com
 Content-Type: application/hornetq.jms.queue+xml

 <queue name="testQueue">
 <durable>true</durable>
 </queue>

 --- Response ---
 HTTP/1.1 201 Created
 Location: http://example.com/queues/jms.queue.testQueue
 

Notice that the Content-Type is application/hornetq.jms.queue+xml.

Here's what creating a topic would look like:

POST /topics
 Host: example.com
 Content-Type: application/hornetq.jms.topic+xml

 <topic name="testTopic">
 </topic>

 --- Response ---
 HTTP/1.1 201 Created
 Location: http://example.com/topics/jms.topic.testTopic

The HornetQ REST interface supports mixing JMS and REST producres and consumers. You can send an ObjectMessage through a JMS Producer, and have a REST client consume it. You can have a REST client POST a message to a topic and have a JMS Consumer receive it. Some simple transformations are supported if you have the correct RESTEasy providers installed.

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

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