3:42 p.m.
Author: jbertram
Date: 2012-01-17 09:42:43 -0500 (Tue, 17 Jan 2012)
New Revision: 12033
Modified:
branches/Branch_2_2_AS7/hornetq-rest/docbook/reference/en/master.xml
Log:
HORNETQ-823
Modified: branches/Branch_2_2_AS7/hornetq-rest/docbook/reference/en/master.xml
===================================================================
--- branches/Branch_2_2_AS7/hornetq-rest/docbook/reference/en/master.xml 2012-01-17
14:40:25 UTC (rev 12032)
+++ branches/Branch_2_2_AS7/hornetq-rest/docbook/reference/en/master.xml 2012-01-17
14:42:43 UTC (rev 12033)
@@ -30,7 +30,8 @@
here's a simple example of posting an order to an order processing queue
express as an HTTP message:</para>
- <para><programlisting>POST /queue/orders/create HTTP/1.1
+ <para><programlisting>
+POST /queue/orders/create HTTP/1.1
Host: example.com
Content-Type: application/xml
@@ -38,8 +39,7 @@
<name>Bill</name>
<item>iPhone 4</item>
<cost>$199.99</cost>
-</order>
-</programlisting>As you can see, we're just posting some arbitrary XML
+</order></programlisting>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
@@ -101,19 +101,21 @@
depends on the <ulink
url="http://jboss.org/resteasy">RESTEasy</ulink>
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.</para>
+ 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).</para>
<sect1>
<title>Installing Within Pre-configured Environment</title>
<para>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
+ running, e.g. JBoss AS 7. You must create a Web archive
(.WAR) file with the following web.xml settings:</para>
- <programlisting><web-app>
+ <programlisting>
+<web-app>
<listener>
<listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
</listener>
@@ -133,22 +135,27 @@
<filter-name>Rest-Messaging</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
+</web-app></programlisting>
-</web-app</programlisting>
-
<para>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.</para>
+ 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 <ulink
+ url="http://maven.apache.org/plugins/maven-war-plugin/usage.html&quo...
+ Maven documentation</ulink>.</para>
- <programlisting><project
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ <programlisting>
+<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>
@@ -156,8 +163,8 @@
</repository>
</repositories>
-
- <build>
+ <build>
+ <plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
@@ -175,10 +182,26 @@
<version>2.2.6.Final</version>
</dependency>
</dependencies>
-</project>
-</programlisting>
+</project></programlisting>
- <para></para>
+ <note><para>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:</para>
+ <programlisting>Dependencies: org.hornetq,
org.jboss.netty</programlisting>
+ <para>You can add this to the
<literal><plugins></literal> section of the
+ pom.xml to create this entry automatically:</para><programlisting>
+<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></programlisting>
+ </note>
+
</sect1>
<sect1>
@@ -192,12 +215,12 @@
REST distribution show how to do this. You must also add an additional
listener to your web.xml file. Here's an example:</para>
- <programlisting><web-app>
+ <programlisting>
+<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>
@@ -217,7 +240,6 @@
<filter-name>Rest-Messaging</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
-
</web-app></programlisting>
<para>Here's a Maven pom.xml file for creating a WAR for this
@@ -225,13 +247,15 @@
src/main/resources directory so that they are stuffed within the WAR's
WEB-INF/classes directory!</para>
- <programlisting><project
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ <programlisting>
+<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>
@@ -239,6 +263,7 @@
</repository>
</repositories>
<build>
+ <plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
@@ -253,16 +278,17 @@
<dependency>
<groupId>org.hornetq</groupId>
<artifactId>hornetq-core</artifactId>
- <version>2.1.1.GA</version>
+ <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.1.1.GA</version>
+ <version>2.2.9.AS7.Final</version>
</dependency>
<dependency>
<groupId>org.jboss.spec.javax.jms</groupId>
@@ -277,12 +303,12 @@
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxrs</artifactId>
- <version>2.0.1.GA</version>
+ <version>2.3.0.GA</version>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxb-provider</artifactId>
- <version>2.0.1.GA</version>
+ <version>2.3.0.GA</version>
</dependency>
</dependencies>
</project></programlisting>
@@ -300,7 +326,8 @@
configuration file. Below is the format of the XML configuration file
and the default values for each.</para>
- <programlisting><rest-messaging>
+ <programlisting>
+<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>
@@ -311,8 +338,7 @@
<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
-</programlisting>
+</rest-messaging</programlisting>
<para>Let's give an explanation of each config option.</para>
@@ -435,9 +461,9 @@
<para>To interact with a queue or topic you do a HEAD or GET request on
the following relative URI pattern:</para>
- <programlisting>/queues/{name}
-/topics/{name}
-</programlisting>
+ <programlisting>
+/queues/{name}
+/topics/{name}</programlisting>
<para>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
@@ -453,15 +479,15 @@
perform your HEAD or GET request on this URI. Here's what a
request/response would look like.</para>
- <programlisting>HEAD /queues/jms.queue.bar HTTP/1.1
+ <programlisting>
+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
-</programlisting>
+msg-push-consumers:
http://example.com/queues/jms.queue.bar/push-consumers</programlisting...
<para>The HEAD or GET response contains a number of custom response
headers that are URLs to additional REST resources that allow you to
@@ -644,7 +670,7 @@
</listitem>
</orderedlist>
- <para>It is <emphasis>VERY IMPORTENT</emphasis> that you never
re-use
+ <para>It is <emphasis>VERY IMPORTANT</emphasis> that you never
re-use
returned <literal>msg-create-next</literal> 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