JBoss.org Community Documentation

- Prev
- Next

## Chapter 2. Installation and Configuration

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

## 2.1. Installing Within Pre-configured Environment

The 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 (note: RESTEasy is available in most JBoss AS 7 profiles). Here's a sample Maven pom.xml that can build your WAR for this case. If you are unfamiliar with the Maven WAR plugin please reference the Maven documentation.

    <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.2.14.Final</version>
            </dependency>
        </dependencies>
    </project>

## Note

JBoss AS 7 loads classes differently than previous versions. To work properly in AS 7 the the WAR will need this in its MANIFEST.MF:

    Dependencies: org.hornetq, org.jboss.netty

You can add this to the `<plugins>` section of the pom.xml to create this entry automatically:

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

## 2.2. Bootstrapping HornetQ Along with REST

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.2.9.AS7.Final</version>
            </dependency>
            <dependency>
                <groupId>org.jboss.netty</groupId>
                <artifactId>netty</artifactId>
                <version>3.2.7.Final</version>
            </dependency>
            <dependency>
                <groupId>org.hornetq</groupId>
                <artifactId>hornetq-jms</artifactId>
                <version>2.2.9.AS7.Final</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.14.Final</version>
            </dependency>
            <dependency>
                <groupId>org.jboss.resteasy</groupId>
                <artifactId>resteasy-jaxrs</artifactId>
                <version>2.3.0.GA</version>
            </dependency>
            <dependency>
                <groupId>org.jboss.resteasy</groupId>
                <artifactId>resteasy-jaxb-provider</artifactId>
                <version>2.3.0.GA</version>
            </dependency>
        </dependencies>
    </project>

## 2.3. REST Configuration

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.

server-in-vm-id

  The HornetQ REST impl uses the IN-VM transport to communicate with HornetQ. It uses the default server id, which is "0".

use-link-headers

  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.

default-durable-send

  Whether a posted message should be persisted by default if the user does not specify a durable query parameter.

dups-ok

  If this is true, no duplicate detection protocol will be enforced for message posting.

topic-push-store-dir

  This must be a relative or absolute file system path. This is a directory where push registrations for topics are stored. See Chapter 6.

queue-push-store-dir

  This must be a relative or absolute file system path. This is a directory where push registrations for queues are stored. See Chapter 6.

producer-session-pool-size

  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.

session-timeout-task-interval

  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.

consumer-session-timeout-seconds

  Timeout in seconds for pull consumers/subscriptions that remain idle for that amount of time.

consumer-window-size

  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.

- PrevChapter 1. Introduction
- Top of page
- Front page
- NextChapter 3. HornetQ REST Interface Basics