You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/08 16:49:36 UTC
[05/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/rest.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/rest.xml b/docs/user-manual/en/rest.xml
deleted file mode 100644
index 10165e4..0000000
--- a/docs/user-manual/en/rest.xml
+++ /dev/null
@@ -1,2150 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-<chapter id="rest">
- <title>REST Interface</title>
-
- <para>The ActiveMQ REST interface allows you to leverage the reliability
- and scalability features of ActiveMQ 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:
- </para>
-
- <programlisting>
-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></programlisting>
-
- <para>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 ActiveMQ as a JMS message and distributed through core ActiveMQ.
- 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.
- </para>
-
- <section>
- <title>Goals of REST Interface</title>
-
- <para>Why would you want to use ActiveMQ's REST interface? What are the
- goals of the REST interface?
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Easily usable by machine-based (code) clients.</para>
- </listitem>
-
- <listitem>
- <para>Zero client footprint. We want ActiveMQ to be usable by any
- client/programming language that has an adequate HTTP client
- library. You shouldn't have to download, install, and configure a
- special library to interact with ActiveMQ.
- </para>
- </listitem>
-
- <listitem>
- <para>Lightweight interoperability. The HTTP protocol is strong
- enough to be our message exchange protocol. Since interactions are
- RESTful the HTTP uniform interface provides all the interoperability
- you need to communicate between different languages, platforms, and
- even messaging implementations that choose to implement the same
- RESTful interface as ActiveMQ (i.e. the
- <ulink url="http://rest-star.org">REST-*</ulink> effort.)
- </para>
- </listitem>
-
- <listitem>
- <para>No envelope (e.g. SOAP) or feed (e.g. Atom) format
- requirements. You shouldn't have to learn, use, or parse a specific
- XML document format in order to send and receive messages through
- ActiveMQ's REST interface.
- </para>
- </listitem>
-
- <listitem>
- <para>Leverage the reliability, scalability, and clustering features
- of ActiveMQ on the back end without sacrificing the simplicity of a
- REST interface.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
-
- <section id="install">
- <title>Installation and Configuration</title>
-
- <para>ActiveMQ's REST interface is installed as a Web archive (WAR). It
- depends on the
- <ulink url="http://jboss.org/resteasy">RESTEasy</ulink>
- project and can currently only run within a servlet container. Installing
- the ActiveMQ REST interface is a little bit different depending whether
- ActiveMQ is already installed and configured for your environment (e.g.
- you're deploying within JBoss AS 7) or you want the ActiveMQ REST
- WAR to startup and manage the ActiveMQ server (e.g. you're deploying
- within something like Apache Tomcat).
- </para>
-
- <section>
- <title>Installing Within Pre-configured Environment</title>
-
- <para>This section should be used when you want to use the ActiveMQ REST
- interface in an environment that already has ActiveMQ installed and
- running, e.g. JBoss AS 7. You must create a Web archive
- (.WAR) file with the following web.xml settings:
- </para>
-
- <programlisting>
-<web-app>
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.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></programlisting>
-
- <para>Within your WEB-INF/lib directory you must have the
- activemq-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>
-
- <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>
- <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.apache.activemq.rest</groupId>
- <artifactId>activemq-rest</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- </dependencies>
-</project></programlisting>
-
- <note>
- <para>JBoss AS 7 loads classes differently than previous versions.
- To work properly in AS 7 the WAR will need this in its MANIFEST.MF:
- </para>
- <programlisting>Dependencies: org.apache.activemq, 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.apache.activemq, org.jboss.netty</Dependencies>
- </manifestEntries>
- </archive>
- </configuration>
-</plugin></programlisting>
- </note>
-
- <para>
- 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 "activemq-rest.war" then clients will access it at, e.g.
- http://localhost:8080/activemq-rest/[queues|topics]. We'll see more about
- this later.
- </para>
- <note>
- <para>
- It is possible to put the WAR file at the "root context" of AS7, but
- that is beyond the scope of this documentation.
- </para>
- </note>
- </section>
-
- <section>
- <title>Bootstrapping ActiveMQ Along with REST</title>
-
- <para>You can bootstrap ActiveMQ within your WAR as well. To do this, you
- must have the ActiveMQ core and JMS jars along with Netty, Resteasy, and
- the ActiveMQ REST jar within your WEB-INF/lib. You must also have a
- activemq-configuration.xml, activemq-jms.xml, and activemq-users.xml config
- files within WEB-INF/classes. The examples that come with the ActiveMQ
- 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>
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.rest.integration.ActiveMQBootstrapListener
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.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></programlisting>
-
- <para>Here's a Maven pom.xml file for creating a WAR for this
- environment. Make sure your activemq configuration files are within the
- 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"
- 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.apache.activemq</groupId>
- <artifactId>activemq-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.apache.activemq</groupId>
- <artifactId>activemq-jms</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- <dependency>
- <groupId>org.jboss.spec.javax.jms</groupId>
- <artifactId>jboss-jms-api_2.0_spec</artifactId>
- <version>1.0.0.Final</version>
- </dependency>
- <dependency>
- <groupId>org.apache.activemq.rest</groupId>
- <artifactId>activemq-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></programlisting>
- </section>
-
- <section id="configuration">
- <title>REST Configuration</title>
-
- <para>The ActiveMQ 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
- <literal>rest.messaging.config.file</literal> to specify the name of the
- configuration file. Below is the format of the XML configuration file
- and the default values for each.
- </para>
-
- <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>
- <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></programlisting>
-
- <para>Let's give an explanation of each config option.</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>server-in-vm-id</literal>. The ActiveMQ REST
- impl uses the IN-VM transport to communicate with ActiveMQ.
- It uses the default server id, which is "0".
- </para>
- </listitem>
- <listitem>
- <para><literal>use-link-headers</literal>. By default, all
- links (URLs) are published using custom headers. You can
- instead have the ActiveMQ REST implementation publish links
- using the <ulink url="http://tools.ietf.org/html/draft-nottingham-http-link-header-10">
- Link Header specification
- </ulink> instead if you desire.
- </para>
- </listitem>
- <listitem>
- <para><literal>default-durable-send</literal>. Whether a posted
- message should be persisted by default if the user does not
- specify a durable query parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>dups-ok</literal>. If this is true, no duplicate
- detection protocol will be enforced for message posting.
- </para>
- </listitem>
- <listitem>
- <para><literal>topic-push-store-dir</literal>. This must be
- a relative or absolute file system path. This is a directory
- where push registrations for topics are stored. See
- <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>queue-push-store-dir</literal>. This must be
- a relative or absolute file system path. This is a
- directory where push registrations for queues are stored.
- See <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>producer-session-pool-size</literal>. The REST
- implementation pools ActiveMQ sessions for sending messages.
- This is the size of the pool. That number of sessions will
- be created at startup time.
- </para>
- </listitem>
- <listitem>
- <para><literal>producer-time-to-live</literal>. Default time
- to live for posted messages. Default is no ttl.
- </para>
- </listitem>
- <listitem>
- <para><literal>session-timeout-task-interval</literal>. 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.
- </para>
- </listitem>
- <listitem>
- <para><literal>consumer-session-timeout-seconds</literal>.
- Timeout in seconds for pull consumers/subscriptions that
- remain idle for that amount of time.
- </para>
- </listitem>
- <listitem>
- <para><literal>consumer-window-size</literal>. For consumers,
- this config option is the same as the ActiveMQ one of the
- same name. It will be used by sessions created by the
- ActiveMQ REST implementation.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
-
- <section id="basics">
- <title>ActiveMQ REST Interface Basics</title>
-
- <para>The ActiveMQ 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.
- </para>
-
- <section>
- <title>Queue and Topic Resources</title>
-
- <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>
-
- <para>The base of the URI is the base URL of the WAR you deployed the
- ActiveMQ REST server within as defined in the
- <link linkend="install">Installation and Configuration</link>
- section of this document. Replace the <literal>{name}</literal>
- 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
- <literal>activemq-jms.xml</literal> file, the URI name should be
- "jms.topic.foo". If you have configured a JMS queue name "bar" within
- your <literal>activemq-jms.xml</literal> file, the URI name should be
- "jms.queue.bar". Internally, ActiveMQ 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.
- </para>
-
- <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-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</programlisting>
-
- <note>
- <para>
- You can use the "curl" utility to test this easily. Simply execute
- a command like this:
- </para>
-
- <programlisting>
-curl --head http://example.com/queues/jms.queue.bar</programlisting>
- </note>
-
- <para>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 ActiveMQ REST interface evolves over
- time.
- </para>
- </section>
-
- <section>
- <title>Queue Resource Response Headers</title>
-
- <para>Below is a list of response headers you should expect when
- interacting with a Queue resource.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-create</literal>. This is a URL you POST messages
- to. The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-create-with-id</literal>. This is a URL
- <emphasis>template</emphasis> you can use to POST messages.
- The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. This is a URL for
- creating consumers that will pull from a queue. The semantics
- of this link are described in
- <link linkend="message-pull">Consuming Messages via Pull</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-push-consumers</literal>. This is a URL for
- registering other URLs you want the ActiveMQ REST server to
- push messages to. The semantics of this link are described
- in <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Topic Resource Response Headers</title>
-
- <para>Below is a list of response headers you should expect when
- interacting with a Topic resource.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-create</literal>. This is a URL you POST
- messages to. The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-create-with-id</literal>. This is a URL
- <emphasis>template</emphasis> you can use to POST messages.
- The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. This is a
- URL for creating subscribers that will pull from a topic.
- The semantics of this link are described in
- <link linkend="message-pull">Consuming Messages via Pull</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-push-subscriptions</literal>. This is a
- URL for registering other URLs you want the ActiveMQ REST
- server to push messages to. The semantics of this link
- are described in <link linkend="message-push">Pushing
- Messages</link>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
-
- <section id="posting-messages">
- <title>Posting Messages</title>
-
- <para>This chapter discusses the protocol for posting messages to a queue
- or a topic. In <link linkend="basics">ActiveMQ REST Interface Basics</link>,
- you saw that a queue or topic resource publishes variable custom headers
- that are links to other RESTful resources. The <literal>msg-create</literal>
- header is a URL you can post a message to. Messages are published to a queue
- or topic by sending a simple HTTP message to the URL published by the
- <literal>msg-create</literal> header. The HTTP message contains whatever
- content you want to publish to the ActiveMQ destination. Here's an example
- scenario:
- </para>
-
- <note>
- <para>You can also post messages to the URL template found in
- <literal>msg-create-with-id</literal>, but this is a more advanced
- use-case involving duplicate detection that we will discuss later in
- this section.
- </para>
- </note>
-
- <orderedlist>
- <listitem>
- <para>Obtain the starting <literal>msg-create</literal> header from
- the queue or topic resource.
- </para>
-
- <para>
- <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-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>Do a POST to the URL contained in the <literal>msg-create</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response ---
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create</programlisting>
-
- <note>
- <para>You can use the "curl" utility to test this easily. Simply execute
- a command like this:
- </para>
- <programlisting>
-curl --verbose --data "123" http://example.com/queues/jms.queue.bar/create</programlisting>
- </note>
-
- <para>A successful response will return a 201 response code. Also
- notice that a <literal>msg-create-next</literal> response header
- is sent as well. You must use this URL to POST your next message.
- </para>
- </listitem>
-
- <listitem>
- <para>POST your next message to the queue using the URL returned in
- the <literal>msg-create-next</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Monica</name>
- <item>iPad</item>
- <cost>$499.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create</programlisting>
- <para>Continue using the new <literal>msg-create-next</literal>
- header returned with each response.
- </para>
- </listitem>
- </orderedlist>
-
- <warning>
- <para>It is <emphasis>VERY IMPORTANT</emphasis> that you never re-use returned
- <literal>msg-create-next</literal> headers to post new messages. If the
- <literal>dups-ok</literal> configuration property is set to
- <literal>false</literal> on the server then this URL will be uniquely
- generated for each message and used for duplicate detection. If you lose
- the URL within the <literal>msg-create-next</literal> header, then just
- go back to the queue or topic resource to get the
- <literal>msg-create</literal> URL again.
- </para>
- </warning>
-
- <section>
- <title>Duplicate Detection</title>
-
- <para>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 ActiveMQ
- REST interface is configured to accept and post duplicate messages. You
- can change this by turning on duplicate message detection by setting the
- <literal>dups-ok</literal> config option to <literal>false</literal>
- as described in <link linkend="basics">ActiveMQ REST Interface Basics</link>.
- When you do this, the initial POST to the <literal>msg-create</literal>
- 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:
- </para>
-
- <orderedlist>
- <listitem>
- <para>Obtain the starting <literal>msg-create</literal> header from
- the queue or topic resource.
- </para>
-
- <para>
- <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-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>Do a POST to the URL contained in the <literal>msg-create</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response ---
-HTTP/1.1 307 Redirect
-Location: http://example.com/queues/jms.queue.bar/create/13582001787372</programlisting>
-
- <para>A successful response will return a 307 response code. This
- is standard HTTP protocol. It is telling you that you must re-POST
- to the URL contained within the <literal>Location</literal>
- header.
- </para>
- </listitem>
-
- <listitem>
- <para>re-POST your message to the URL provided within the
- <literal>Location</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create/13582001787372
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787373</programlisting>
- <para>You should receive a 201 Created response. If there is a
- network failure, just re-POST to the Location header. For new
- messages, use the returned <literal>msg-create-next</literal>
- header returned with each response.
- </para>
- </listitem>
-
- <listitem>
- <para>POST any new message to the returned
- <literal>msg-create-next</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create/13582001787373
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Monica</name>
- <item>iPad</name>
- <cost>$499.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374</programlisting>
- <para>If there ever is a network problem, just repost to the URL
- provided in the <literal>msg-create-next</literal> header.
- </para>
- </listitem>
- </orderedlist>
-
- <para>How can this work? As you can see, with each successful response,
- the ActiveMQ 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 ActiveMQ's duplicate detection mechanism by setting the
- <literal>DUPLICATE_DETECTION_ID</literal> property of the JMS message
- that is actually posted to the system.
- </para>
-
- <para>If you happen to use the same ID more than once you'll see a message
- like this on the server:
- </para>
- <programlisting>
-WARN [org.apache.activemq.core.server] (Thread-3 (ActiveMQ-remoting-threads-ActiveMQServerImpl::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</programlisting>
-
- <para>An alternative to this approach is to use the <literal>msg-create-with-id</literal>
- header. This is not an invokable URL, but a URL template. The idea is that
- the client provides the <literal>DUPLICATE_DETECTION_ID</literal> and creates
- its own <literal>create-next</literal> URL. The <literal>msg-create-with-id</literal>
- header looks like this (you've see it in previous examples, but we haven't used it):
- </para>
-
- <programlisting>
-msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
-
- <para>You see that it is a regular URL appended with a <literal>{id}</literal>. This
- <literal>{id}</literal> is a pattern matching substring. A client would generate its
- <literal>DUPLICATE_DETECTION_ID</literal> and replace <literal>{id}</literal>
- with that generated id, then POST to the new URL. The URL the client creates
- works exactly like a <literal>create-next</literal> URL described earlier. The
- response of this POST would also return a new <literal>msg-create-next</literal>
- header. The client can continue to generate its own DUPLICATE_DETECTION_ID, or
- use the new URL returned via the <literal>msg-create-nex</literal>t header.
- </para>
-
- <para>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
- <literal>DUPLICATE_DETECTION_ID</literal> once.
- </para>
- </section>
-
- <section>
- <title>Persistent Messages</title>
-
- <para>By default, posted messages are not durable and will not be
- persisted in ActiveMQ'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 <literal>durable</literal> to true when you post
- your messages to the URLs returned in the <literal>msg-create</literal>,
- <literal>msg-create-with-id</literal>, or <literal>msg-create-next</literal>
- headers. here's an example of that.
- </para>
-
- <programlisting>
-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></programlisting>
- </section>
-
- <section>
- <title>TTL, Expiration and Priority</title>
-
- <para>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 <literal>expiration</literal> query parameter is an long
- specify the time in milliseconds since epoch (a long date). The
- <literal>ttl</literal> query parameter is a time in milliseconds you
- want the message active. The <literal>priority</literal> is another
- query parameter with an integer value between 0 and 9 expressing the
- priority of the message. i.e.:
- </para>
-
- <programlisting>
-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></programlisting>
- </section>
- </section>
-
- <section id="message-pull">
- <title>Consuming Messages via Pull</title>
-
- <para>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 ActiveMQ through a REST
- interface.
- </para>
-
- <para>You create consumer resources by doing a simple POST to the URL
- published by the <literal>msg-pull-consumers</literal>
- response header if you are interacting with a queue, the
- <literal>msg-pull-subscribers</literal> response header if you're
- interacting with a topic. These headers are provided by the main queue or
- topic resource discussed in <link linkend="basics">ActiveMQ REST Interface
- Basics</link>. Doing an empty POST to one of these
- URLs will create a consumer resource that follows an auto-acknowledge
- protocol and, if you are interacting with a topic, creates a temporarily
- 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 (<literal>application/x-www-form-urlencoded</literal>)
- described below.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>autoAck</literal>. A value of <literal>true</literal>
- or <literal>false</literal> can be given. This defaults to
- <literal>true</literal> if you do not pass this parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>durable</literal>. A value of <literal>true</literal>
- or <literal>false</literal> can be given. This defaults to
- <literal>false</literal> if you do not pass this parameter.
- Only available on topics. This specifies whether you want a
- durable subscription or not. A durable subscription persists
- through server restart.
- </para>
- </listitem>
- <listitem>
- <para><literal>name</literal>. This is the name of the durable
- subscription. If you do not provide this parameter, the name
- will be automatically generated by the server. Only usable
- on topics.
- </para>
- </listitem>
- <listitem>
- <para><literal>selector</literal>. This is an optional JMS selector
- string. The ActiveMQ REST interface adds HTTP headers to the
- JMS message for REST produced messages. HTTP headers are
- prefixed with "http_" and every '-' character is converted
- to a '$'.
- </para>
- </listitem>
- <listitem>
- <para><literal>idle-timeout</literal>. For a topic subscription,
- idle time in milliseconds in which the consumer connections
- will be closed if idle.
- </para>
- </listitem>
- <listitem>
- <para><literal>delete-when-idle</literal>. Boolean value, If
- true, a topic subscription will be deleted (even if it is
- durable) when an the idle timeout is reached.
- </para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>If you have multiple pull-consumers active at the same time
- on the same destination be aware that unless the
- <literal>consumer-window-size</literal> is 0 then one consumer
- might buffer messages while the other consumer gets none.
- </para>
- </note>
-
- <section>
- <title>Auto-Acknowledge</title>
-
- <para>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.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. The URL of
- a factory resource for creating queue consumer
- resources. You will pull from these created resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. The URL
- of a factory resource for creating topic subscription
- resources. You will pull from the created resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consume-next</literal>. The URL you
- will pull the next message from. This is returned
- with every response.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consumer</literal>. This is a URL
- pointing back to the consumer or subscription
- resource created for the client.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Creating an Auto-Ack Consumer or Subscription</title>
-
- <para>Here is an example of creating an auto-acknowledged
- queue pull consumer.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the pull-consumers URL by doing a HEAD or
- GET request to the base queue resource.
- </para>
-
- <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>
- </listitem>
-
- <listitem>
- <para>Next do an empty POST to the URL returned in the
- <literal>msg-pull-consumers</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
-Host: example.com
-
---- response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- consumer resource that was created on the server. It is good to
- remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Creating an auto-acknowledged consumer for a topic is pretty
- much the same. Here's an example of creating a durable
- auto-acknowledged topic pull subscription.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the
- <literal>pull-subscriptions</literal>
- URL by doing
- a HEAD or GET request to the base topic resource
- </para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.foo/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-subscriptions</literal>
- header passing in a <literal>true</literal>
- value for the <literal>durable</literal>
- form parameter.
- </para>
-
- <programlisting>
-POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-durable=true
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222
-msg-consume-next:
-http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- subscription resource that was created on the server. It is good
- to remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Consuming Messages</title>
-
- <para>After you have created a consumer resource, you are ready to
- start pulling messages from the server. Notice that when you created
- the consumer for either the queue or topic, the response contained a
- <literal>msg-consume-next</literal> response header. POST to the URL
- contained within this header to consume the next message in the queue
- or topic subscription. A successful POST causes the server to extract
- a message from the queue or topic subscription, acknowledge it, and
- return it to the consuming client. If there are no messages in the
- queue or topic subscription, a 503 (Service Unavailable) HTTP code is
- returned.
- </para>
-
- <warning>
- <para>For both successful and unsuccessful posts to the
- msg-consume-next URL, the response will contain a new
- msg-consume-next header. You must ALWAYS use this new URL returned
- within the new msg-consume-next header to consume new
- messages.
- </para>
- </warning>
-
- <para>Here's an example of pulling multiple messages from the consumer
- resource.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Do a POST on the msg-consume-next URL that was returned with
- the consumer or subscription resource discussed earlier.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-1
-Host: example.com
-
---- 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-2
-msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
-
-<order>...</order></programlisting>
-
- <para>The POST returns the message consumed from the queue. It
- also returns a new msg-consume-next link. Use this new link to get
- the next message. Notice also a msg-consumer response header is
- returned. This is a URL that points back to the consumer or
- subscription resource. You will need that to clean up your
- connection after you are finished using the queue or topic.
- </para>
- </listitem>
-
- <listitem>
- <para>The POST returns the message consumed from the queue. It
- also returns a new msg-consume-next link. Use this new link to get
- the next message.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-2
-Host: example.com
-
---- Response ---
-Http/1.1 503 Service Unavailable
-Retry-After: 5
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2</programlisting>
-
- <para>In this case, there are no messages in the queue, so we get
- a 503 response back. As per the HTTP 1.1 spec, a 503 response may
- return a Retry-After head specifying the time in seconds that you
- should retry a post. Also notice, that another new
- msg-consume-next URL is present. Although it probably is the same
- URL you used last post, get in the habit of using URLs returned in
- response headers as future versions of ActiveMQ REST might be
- redirecting you or adding additional data to the URL after
- timeouts like this.
- </para>
- </listitem>
-
- <listitem>
- <para>POST to the URL within the last
- <literal>msg-consume-next</literal>
- to get the next
- message.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-2
-Host: example.com
-
---- 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></programlisting>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Recovering From Network Failures</title>
-
- <para>If you experience a network failure and do not know if your post
- to a msg-consume-next URL was successful or not, just re-do your POST.
- A POST to a msg-consume-next URL is idempotent, meaning that it will
- return the same result if you execute on any one msg-consume-next URL
- more than once. Behind the scenes, the consumer resource caches the
- last consumed message so that if there is a message failure and you do
- a re-post, the cached last message will be returned (along with a new
- msg-consume-next URL). This is the reason why the protocol always
- requires you to use the next new msg-consume-next URL returned with
- each response. Information about what state the client is in is
- embedded within the actual URL.
- </para>
- </section>
-
- <section>
- <title>Recovering From Client or Server Crashes</title>
-
- <para>If the server crashes and you do a POST to the msg-consume-next
- URL, the server will return a 412 (Preconditions Failed) response
- code. This is telling you that the URL you are using is out of sync
- with the server. The response will contain a new msg-consume-next
- header to invoke on.
- </para>
-
- <para>If the client crashes there are multiple ways you can recover.
- If you have remembered the last msg-consume-next link, you can just
- re-POST to it. If you have remembered the consumer resource URL, you
- can do a GET or HEAD request to obtain a new msg-consume-next URL. If
- you have created a topic subscription using the name parameter
- discussed earlier, you can re-create the consumer. Re-creation will
- return a msg-consume-next URL you can use. If you cannot do any of
- these things, you will have to create a new consumer.
- </para>
-
- <para>The problem with the auto-acknowledge protocol is that if the
- client or server crashes, it is possible for you to skip messages. The
- scenario would happen if the server crashes after auto-acknowledging a
- message and before the client receives the message. If you want more
- reliable messaging, then you must use the acknowledgement
- protocol.
- </para>
- </section>
- </section>
-
- <section>
- <title>Manual Acknowledgement</title>
-
- <para>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.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. The URL of a factory resource for creating queue
- consumer
- resources. You will pull from these created resources
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. The URL of a factory resource for creating topic
- subscription resources. You will pull from the created
- resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-acknowledge-next</literal>. URL used to obtain the next message in the queue or
- topic
- subscription. It does not acknowledge the message though.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-acknowledgement</literal>. URL used to acknowledge a message.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consumer</literal>. This is a URL pointing back to the consumer or subscription
- resource created for the client.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Creating manually-acknowledged consumers or
- subscriptions
- </title>
-
- <para>Here is an example of creating an auto-acknowledged queue pull
- consumer.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the pull-consumers URL by doing a HEAD or GET request
- to the base queue resource.
- </para>
-
- <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>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-consumers</literal>
- header passing in a
- <literal>false</literal>
- value to the
- <literal>autoAck</literal>
- form parameter .
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-autoAck=false
-
---- response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333
-msg-acknowledge-next: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333/acknowledge-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- consumer resource that was created on the server. It is good to
- remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Creating an manually-acknowledged consumer for a topic is pretty
- much the same. Here's an example of creating a durable
- manually-acknowledged topic pull subscription.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the
- <literal>pull-subscriptions</literal>
- URL by doing
- a HEAD or GET request to the base topic resource
- </para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.foo/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-subscriptions</literal>
- header passing in a <literal>true</literal>
- value for the <literal>durable</literal>
- form parameter and a <literal>false</literal>
- value to the <literal>autoAck</literal>
- form parameter.
- </para>
-
- <programlisting>
-POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-durable=true&autoAck=false
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222
-msg-acknowledge-next:
-http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal> header points to the JMS
- subscription resource that was created on the server. It is good
- to remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Consuming and Acknowledging a Message</title>
-
- <para>After you have created a consumer resource, you are ready to
- start pulling messages from the server. Notice that when you created
- the consumer for either the queue or topic, the response contained a
- <literal>msg-acknowledge-next</literal> response header. POST to the
- URL contained within this header to consume the next message in the
- queue or topic subscription. If there are no messages in the queue or
- topic subscription, a 503 (Service Unavailable) HTTP code is returned.
- A successful POST causes the server to extract a message from the
- queue or topic subscription and return it to the consuming client. It
- does not acknowledge the message though. The response will contain the
- <literal>acknowledgement</literal>
- header which you will use to
- acknowledge the message.
- </para>
-
- <para>Here's an example of pulling multiple messages from the consumer
- resource.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Do a POST on the msg-acknowledge-next URL that was returned
- with the consumer or subscription resource discussed
- earlier.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-Content-Type: application/xml
-msg-acknowledgement:
-http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledgement/2
-msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
-
-<order>...</order></programlisting>
-
- <para>The POST returns the message consumed from the queue. It
- also returns a<literal>msg-acknowledgemen</literal>t link. You
- will use this new link to acknowledge the message. Notice also a
- <literal>msg-consumer</literal> response header is returned. This
- is a URL that points back to the consumer or subscription
- resource. You will need that to clean up your connection after you
- are finished using the queue or topic.
- </para>
- </listitem>
-
- <listitem>
- <para>Acknowledge or unacknowledge the message by doing a POST to
- the URL contained in the <literal>msg-acknowledgement</literal>
- header. You must pass an <literal>acknowledge</literal>
- form parameter set to <literal>true</literal>
- or <literal>false</literal> depending on whether you want to
- acknowledge or unacknowledge the message on the server.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/acknowledgement/2
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-acknowledge=true
-
---- Response ---
-Http/1.1 200 Ok
-msg-acknowledge-next:
-http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledge-next-2</programlisting>
-
- <para>Whether you acknowledge or unacknowledge the message, the
- response will contain a new msg-acknowledge-next header that you
- must use to obtain the next message.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Recovering From Network Failures</title>
-
- <para>If you experience a network failure and do not know if your post
- to a
- <literal>msg-acknowledge-next</literal>
- or
- <literal>msg-acknowledgement</literal> URL was successful or not, just
- re-do your POST. A POST to one of these URLs is idempotent, meaning
- that it will return the same result if you re-post. Behind the scenes,
- the consumer resource keeps track of its current state. If the last
- action was a call to<literal>msg-acknowledge-next</literal>, it will
- have the last message cached, so that if a re-post is done, it will
- return the message again. Same goes with re-posting to
- <literal>msg-acknowledgement</literal>. The server remembers its last
- state and will return the same results. If you look at the URLs you'll
- see that they contain information about the expected current state of
- the server. This is how the server knows what the client is
- expecting.
- </para>
- </section>
-
- <section>
- <title>Recovering From Client or Server Crashes</title>
-
- <para>If the server crashes and while you are doing a POST to the
- <literal>msg-acknowledge-next</literal> URL, just re-post. Everything
- should reconnect all right. On the other hand, if the server crashes
- while you are doing a POST to<literal>msg-acknowledgement</literal>,
- the server will return a 412 (Preconditions Failed) response code.
- This is telling you that the URL you are using is out of sync with the
- server and the message you are acknowledging was probably re-enqueued.
- The response will contain a new <literal>msg-acknowledge-next</literal>
- header to invoke on.
- </para>
-
- <para>As long as you have "bookmarked" the consumer resource URL
- (returned from <literal>Location</literal> header on a create, or the
- <literal>msg-consumer</literal> header), you can recover from client
- crashes by doing a GET or HEAD request on the consumer resource to
- obtain what state you are in. If the consumer resource is expecting
- you to acknowledge a message, it will return a
- <literal>msg-acknowledgement</literal> header in the response. If the
- consumer resource is expecting you to pull for the next message, the
- <literal>msg-acknowledge-next</literal> header will be in the
- response. With manual acknowledgement you are pretty much guaranteed
- to avoid skipped messages. For topic subscriptions that were created
- with a name parameter, you do not have to "bookmark" the returned URL.
- Instead, you can re-create the consumer resource with the same exact
- name. The response will contain the same information as if you did a
- GET or HEAD request on the consumer resource.
- </para>
- </section>
- </section>
-
- <section>
- <title>Blocking Pulls with Accept-Wait</title>
-
- <para>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 ActiveMQ REST interface provides
- the <literal>Accept-Wait</literal> 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:
- </para>
-
- <programlisting>
-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></programlisting>
-
- <para>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.
- </para>
- </section>
-
- <section>
- <title>Clean Up Your Consumers!</title>
-
- <para>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
- <literal>consumer-session-timeout-seconds</literal> configured from
- <link linkend="configuration">REST configuration</link>, 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).
- </para>
- </section>
- </section>
-
-
- <section id="message-push">
- <title>Pushing Messages</title>
-
- <para>You can configure the ActiveMQ 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 ActiveMQ REST server to load at boot
- time.
- </para>
-
- <section>
- <title>The Queue Push Subscription XML</title>
-
- <para>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:
- </para>
-
- <programlisting>
-<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></programlisting>
-
- <para>The <literal>durable</literal> 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 to<literal>false</literal>. If
- durable is set to true, an XML file for the push subscription will be
- created within the directory specified by the
- <literal>queue-push-store-dir</literal> config variable defined in
- Chapter 2 (<literal>topic-push-store-dir</literal> for topics).
- </para>
-
- <para>The <literal>selector</literal> 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.
- </para>
-
- <para>The <literal>maxRetries</literal> element specifies how many times
- a the server will try to push a message to a URL if there is a
- connection failure.
- </para>
-
- <para>The <literal>retryWaitMillis</literal> element specifies how long
- to wait before performing a retry.
- </para>
-
- <para>The
- <literal>disableOnFailure</literal> 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
- ActiveMQ will take over.
- </para>
-
- <para>The <literal>link</literal> element specifies the basis of the
- interaction. The <literal>href</literal> attribute contains the URL you
- want to interact with. It is the only required attribute. The
- <literal>type</literal> attribute specifies the content-type of what the
- push URL is expecting. The <literal>method</literal> 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
- <literal>rel</literal> attribute is very important and the value of it
- triggers different behavior. Here's the values a rel attribute can
- have:
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>destination</literal>. The href URL is assumed to be a queue or topic resource of
- another ActiveMQ REST server. The push registration will initially
- do a HEAD request to this URL to obtain a msg-create-with-id
- header. It will use this header to push new messages to the
- ActiveMQ REST endpoint reliably. Here's an example:
- </para>
-
- <programlisting>
-<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
-</push-registration></programlisting>
- </listitem>
- <listitem>
- <para><literal>template</literal>. In this case, the server is expecting the link element's
- href attribute to be a URL expression. The URL expression must
- have one and only one URL parameter within it. The server will use
- a unique value to create the endpoint URL. Here's an
- example:
- </para>
-
- <programlisting>
-<push-registration>
- <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
-</push-registration></programlisting>
-
- <para>In this example, the {id} sub-string is the one and only one
- URL parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>user defined</literal>. If the rel attributes is not destination or template (or is
- empty or missing), then the server will send an HTTP message to
- the href URL using the HTTP method defined in the method
- attribute. Here's an example:
- </para>
-
- <programlisting>
-<push-registration>
- <link href="http://somewhere.com" type="application/json" method="PUT"/>
-</push-registration></programlisting>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>The Topic Push Subscription XML</title>
-
- <para>The push XML for a topic is the same except the root element is
- push-topic-registration. (Also remember the <literal>selector</literal>
- element is optional). The rest of the document is the same. Here's an
- example of a template registration:
- </para>
-
- <programlisting>
-<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></programlisting>
- </section>
-
- <section>
- <title>Creating a Push Subscription at Runtime</title>
-
- <para>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:
- </para>
-
- <orderedlist>
- <listitem>
- <para>First do a HEAD request to the queue resource:</para>
-
- <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>
- </listitem>
-
- <listitem>
- <para>Next POST your subscription XML to the URL returned from
- msg-push-consumers header
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/push-consumers
-Host: example.com
-Content-Type: application/xml
-
-<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
-</push-registration>
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/push-consumers/1-333-1212</programlisting>
-
- <para>The Location header contains the URL for the created resource.
- If you want to unregister this, then do a HTTP DELETE on this
- URL.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Here's an example of creating a push registration for a
- topic:
- </para>
-
- <orderedlist>
- <listitem>
- <para>First do a HEAD request to the topic resource:</para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.bar/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.bar/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.bar/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next POST your subscription XML to the URL returned from
- msg-push-subscriptions header
- </para>
-
- <programlisting>
-POST /topics/jms.topic.bar/push-subscriptions
-Host: example.com
-Content-Type: application/xml
-
-<push-registration>
- <link rel="template" href="http://somewhere.com/resources/{id}"/>
-</push-registration>
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212</programlisting>
-
- <para>The Location header contains the URL for the created resource.
- If you want to unregister this, then do a HTTP DELETE on this
- URL.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Creating a Push Subscription by Hand</title>
-
- <para>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.
- </para>
-
- <para>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:
- </para>
-
- <programlisting>
-<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></programlisting>
-
- <para>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:
- </para>
-
- <programlisting>
-<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-registra
<TRUNCATED>