JBoss.orgCommunity Documentation
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 (i.e. you're deploying within JBoss 6 AppServer) or you want the HornetQ REST WAR to startup and manage the HornetQ server.
The section should be used when you want to use the HornetQ REST interface in an environment that already has HornetQ installed and running, i.e. JBoss 6 Application Server. 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-appWithin 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>
<repositories>
<repository>
<id>jboss</id>
<url>http://repository.jboss.org/nexus/content/groups/public/</url>
</repository>
</repositories>
<build>
<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.2.5.Final</version>
</dependency>
</dependencies>
</project>
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>
<repositories>
<repository>
<id>jboss</id>
<url>http://repository.jboss.org/nexus/content/groups/public/</url>
</repository>
</repositories>
<build>
<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.1.1.GA</version>
</dependency>
<dependency>
<groupId>org.jboss.netty</groupId>
<artifactId>netty</artifactId>
</dependency>
<dependency>
<groupId>org.hornetq</groupId>
<artifactId>hornetq-jms</artifactId>
<version>2.1.1.GA</version>
</dependency>
<dependency>
<groupId>org.jboss.spec.javax.jms</groupId>
<artifactId>jboss-jms-api_1.1_spec</artifactId>
<version>1.0.0.Beta1</version>
</dependency>
<dependency>
<groupId>org.hornetq.rest</groupId>
<artifactId>hornetq-rest</artifactId>
<version>2.2.5.Final</version>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxrs</artifactId>
<version>2.0.1.GA</version>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxb-provider</artifactId>
<version>2.0.1.GA</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-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.
The HornetQ REST impl uses the IN-VM transport to communicate with HornetQ. It uses the default server id, which is "0".
By default, all links (URLs) are published using custom headers. You can instead have the HornetQ REST implementation publish links using the Link Header specification instead if you desire.
Whether a posted message should be persisted by default if the user does not specify a durable query parameter.
If this is true, no duplicate detection protocol will be enforced for message posting.
This must be a relative or absolute file system path. This is a directory where push registrations for topics are stored. See Chapter 6.
This must be a relative or absolute file system path. This is a directory where push registrations for queues are stored. See Chapter 6.
The REST implementation pools HornetQ sessions for sending messages. This is the size of the pool. That number of sessions will be created at startup time.
Pull consumers and pull subscriptions can time out. This is the interval the thread that checks for timed-out sessions will run at. A value of 1 means it will run every 1 second.
Timeout in seconds for pull consumers/subscriptions that remain idle for that amount of time.
For consumers, this config option is the same as the HornetQ one of the same name. It will be used by sessions created by the HornetQ REST implementation.