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 2017/09/14 19:48:13 UTC
svn commit: r1018163 [35/45] - in
/websites/production/activemq/content/artemis/docs: 2.2.0/ latest/
latest/diagrams/ latest/gitbook/ latest/gitbook/fonts/
latest/gitbook/fonts/fontawesome/
latest/gitbook/gitbook-plugin-fontsettings/ latest/gitbook/git...
Added: websites/production/activemq/content/artemis/docs/latest/rest.html
==============================================================================
--- websites/production/activemq/content/artemis/docs/latest/rest.html (added)
+++ websites/production/activemq/content/artemis/docs/latest/rest.html Thu Sep 14 19:48:11 2017
@@ -0,0 +1,2391 @@
+
+<!DOCTYPE HTML>
+<html lang="" >
+ <head>
+ <title>REST Interface · ActiveMQ Artemis Documentation</title>
+ <meta charset="UTF-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+ <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
+ <meta name="description" content="">
+ <meta name="generator" content="GitBook 3.1.1">
+
+
+
+
+ <link rel="stylesheet" href="gitbook/style.css">
+
+
+
+
+ <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
+
+
+
+ <link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
+
+
+
+ <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <meta name="HandheldFriendly" content="true"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+ <meta name="apple-mobile-web-app-capable" content="yes">
+ <meta name="apple-mobile-web-app-status-bar-style" content="black">
+ <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
+ <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
+
+
+ <link rel="next" href="embedding-activemq.html" />
+
+
+ <link rel="prev" href="logging.html" />
+
+
+ </head>
+ <body>
+
+<div class="book">
+ <div class="book-summary">
+
+
+<div id="book-search-input" role="search">
+ <input type="text" placeholder="Type to search" />
+</div>
+
+
+ <nav role="navigation">
+
+
+
+<ul class="summary">
+
+
+
+
+
+
+
+
+
+ <li class="chapter " data-level="1.1" data-path="./">
+
+ <a href="./">
+
+
+ Introduction
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.2" data-path="notice.html">
+
+ <a href="notice.html">
+
+
+ Legal Notice
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.3" data-path="preface.html">
+
+ <a href="preface.html">
+
+
+ Preface
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.4" data-path="project-info.html">
+
+ <a href="project-info.html">
+
+
+ Project Info
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.5" data-path="messaging-concepts.html">
+
+ <a href="messaging-concepts.html">
+
+
+ Messaging Concepts
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.6" data-path="architecture.html">
+
+ <a href="architecture.html">
+
+
+ Architecture
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.7" data-path="using-server.html">
+
+ <a href="using-server.html">
+
+
+ Using the Server
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.8" data-path="address-model.html">
+
+ <a href="address-model.html">
+
+
+ Address Model
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.9" data-path="using-jms.html">
+
+ <a href="using-jms.html">
+
+
+ Using JMS
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.10" data-path="using-core.html">
+
+ <a href="using-core.html">
+
+
+ Using Core
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.11" data-path="using-AMQP.html">
+
+ <a href="using-AMQP.html">
+
+
+ Using AMQP
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.12" data-path="jms-core-mapping.html">
+
+ <a href="jms-core-mapping.html">
+
+
+ Mapping JMS Concepts to the Core API
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.13" data-path="client-classpath.html">
+
+ <a href="client-classpath.html">
+
+
+ The Client Classpath
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.14" data-path="examples.html">
+
+ <a href="examples.html">
+
+
+ Examples
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.15" data-path="wildcard-routing.html">
+
+ <a href="wildcard-routing.html">
+
+
+ Routing Messages With Wild Cards
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.16" data-path="wildcard-syntax.html">
+
+ <a href="wildcard-syntax.html">
+
+
+ Understanding the Apache ActiveMQ Artemis Wildcard Syntax
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.17" data-path="filter-expressions.html">
+
+ <a href="filter-expressions.html">
+
+
+ Filter Expressions
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.18" data-path="persistence.html">
+
+ <a href="persistence.html">
+
+
+ Persistence
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.19" data-path="configuring-transports.html">
+
+ <a href="configuring-transports.html">
+
+
+ Configuring Transports
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.20" data-path="config-reload.html">
+
+ <a href="config-reload.html">
+
+
+ Configuration Reload
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.21" data-path="connection-ttl.html">
+
+ <a href="connection-ttl.html">
+
+
+ Detecting Dead Connections
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.22" data-path="slow-consumers.html">
+
+ <a href="slow-consumers.html">
+
+
+ Detecting Slow Consumers
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.23" data-path="network-isolation.html">
+
+ <a href="network-isolation.html">
+
+
+ Avoiding Network Isolation
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.24" data-path="critical-analysis.html">
+
+ <a href="critical-analysis.html">
+
+
+ Detecting Broker Issues (Critical Analysis)
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.25" data-path="transaction-config.html">
+
+ <a href="transaction-config.html">
+
+
+ Resource Manager Configuration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.26" data-path="flow-control.html">
+
+ <a href="flow-control.html">
+
+
+ Flow Control
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.27" data-path="send-guarantees.html">
+
+ <a href="send-guarantees.html">
+
+
+ Guarantees of sends and commits
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.28" data-path="undelivered-messages.html">
+
+ <a href="undelivered-messages.html">
+
+
+ Message Redelivery and Undelivered Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.29" data-path="message-expiry.html">
+
+ <a href="message-expiry.html">
+
+
+ Message Expiry
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.30" data-path="large-messages.html">
+
+ <a href="large-messages.html">
+
+
+ Large Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.31" data-path="paging.html">
+
+ <a href="paging.html">
+
+
+ Paging
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.32" data-path="queue-attributes.html">
+
+ <a href="queue-attributes.html">
+
+
+ Queue Attributes
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.33" data-path="scheduled-messages.html">
+
+ <a href="scheduled-messages.html">
+
+
+ Scheduled Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.34" data-path="last-value-queues.html">
+
+ <a href="last-value-queues.html">
+
+
+ Last-Value Queues
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.35" data-path="message-grouping.html">
+
+ <a href="message-grouping.html">
+
+
+ Message Grouping
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.36" data-path="pre-acknowledge.html">
+
+ <a href="pre-acknowledge.html">
+
+
+ Extra Acknowledge Modes
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.37" data-path="management.html">
+
+ <a href="management.html">
+
+
+ Management
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.38" data-path="management-console.html">
+
+ <a href="management-console.html">
+
+
+ Management Console
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.39" data-path="security.html">
+
+ <a href="security.html">
+
+
+ Security
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.40" data-path="broker-plugins.html">
+
+ <a href="broker-plugins.html">
+
+
+ Broker Plugins
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.41" data-path="resource-limits.html">
+
+ <a href="resource-limits.html">
+
+
+ Resource Limits
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.42" data-path="jms-bridge.html">
+
+ <a href="jms-bridge.html">
+
+
+ The JMS Bridge
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.43" data-path="client-reconnection.html">
+
+ <a href="client-reconnection.html">
+
+
+ Client Reconnection and Session Reattachment
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.44" data-path="diverts.html">
+
+ <a href="diverts.html">
+
+
+ Diverting and Splitting Message Flows
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.45" data-path="core-bridges.html">
+
+ <a href="core-bridges.html">
+
+
+ Core Bridges
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.46" data-path="duplicate-detection.html">
+
+ <a href="duplicate-detection.html">
+
+
+ Duplicate Message Detection
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.47" data-path="clusters.html">
+
+ <a href="clusters.html">
+
+
+ Clusters
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.48" data-path="ha.html">
+
+ <a href="ha.html">
+
+
+ High Availability and Failover
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.49" data-path="graceful-shutdown.html">
+
+ <a href="graceful-shutdown.html">
+
+
+ Graceful Server Shutdown
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.50" data-path="libaio.html">
+
+ <a href="libaio.html">
+
+
+ Libaio Native Libraries
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.51" data-path="thread-pooling.html">
+
+ <a href="thread-pooling.html">
+
+
+ Thread management
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.52" data-path="logging.html">
+
+ <a href="logging.html">
+
+
+ Logging
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter active" data-level="1.53" data-path="rest.html">
+
+ <a href="rest.html">
+
+
+ REST Interface
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.54" data-path="embedding-activemq.html">
+
+ <a href="embedding-activemq.html">
+
+
+ Embedding Apache ActiveMQ Artemis
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.55" data-path="karaf.html">
+
+ <a href="karaf.html">
+
+
+ Apache Karaf
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.56" data-path="spring-integration.html">
+
+ <a href="spring-integration.html">
+
+
+ Spring Integration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.57" data-path="cdi-integration.html">
+
+ <a href="cdi-integration.html">
+
+
+ CDI Integration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.58" data-path="intercepting-operations.html">
+
+ <a href="intercepting-operations.html">
+
+
+ Intercepting Operations
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.59" data-path="protocols-interoperability.html">
+
+ <a href="protocols-interoperability.html">
+
+
+ Protocols and Interoperability
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.60" data-path="tools.html">
+
+ <a href="tools.html">
+
+
+ Tools
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.61" data-path="maven-plugin.html">
+
+ <a href="maven-plugin.html">
+
+
+ Maven Plugin
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.62" data-path="unit-testing.html">
+
+ <a href="unit-testing.html">
+
+
+ Unit Testing
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.63" data-path="perf-tuning.html">
+
+ <a href="perf-tuning.html">
+
+
+ Troubleshooting and Performance Tuning
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.64" data-path="configuration-index.html">
+
+ <a href="configuration-index.html">
+
+
+ Configuration Reference
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.65" data-path="updating-artemis.html">
+
+ <a href="updating-artemis.html">
+
+
+ Updating Artemis
+
+ </a>
+
+
+
+ </li>
+
+
+
+
+ <li class="divider"></li>
+
+ <li>
+ <a href="https://www.gitbook.com" target="blank" class="gitbook-link">
+ Published with GitBook
+ </a>
+ </li>
+</ul>
+
+
+ </nav>
+
+
+ </div>
+
+ <div class="book-body">
+
+ <div class="body-inner">
+
+
+
+<div class="book-header" role="navigation">
+
+
+ <!-- Title -->
+ <h1>
+ <i class="fa fa-circle-o-notch fa-spin"></i>
+ <a href="." >REST Interface</a>
+ </h1>
+</div>
+
+
+
+
+ <div class="page-wrapper" tabindex="-1" role="main">
+ <div class="page-inner">
+
+<div id="book-search-results">
+ <div class="search-noresults">
+
+ <section class="normal markdown-section">
+
+ <h1 id="rest-interface">REST Interface</h1>
+<p>The Apache ActiveMQ Artemis REST interface allows you to leverage the reliability and
+scalability features of Apache ActiveMQ Artemis over a simple REST/HTTP interface.
+The REST Interface implementation sits on top of an Apache ActiveMQ Artemis JMS API and
+as such exposes JMS like concepts via REST.</p>
+<p>Using the REST interface Messages can be 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:</p>
+<pre><code>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>
+</code></pre><p>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 Apache ActiveMQ Artemis
+as a JMS message and distributed through core Apache ActiveMQ Artemis. Simple and easy.
+Consuming messages from a queue or topic looks very similar. We'll
+discuss the entire interface in detail later.</p>
+<h2 id="goals-of-rest-interface">Goals of REST Interface</h2>
+<p>Why would you want to use Apache ActiveMQ Artemis's REST interface? What are the goals
+of the REST interface?</p>
+<ul>
+<li><p>Easily usable by machine-based (code) clients.</p>
+</li>
+<li><p>Zero client footprint. We want Apache ActiveMQ Artemis 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 Apache ActiveMQ Artemis.</p>
+</li>
+<li><p>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 Apache ActiveMQ Artemis (i.e. the <a href="http://rest-star.org" target="_blank">REST-*</a>
+effort.)</p>
+</li>
+<li><p>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 Apache ActiveMQ Artemis's REST
+interface.</p>
+</li>
+<li><p>Leverage the reliability, scalability, and clustering features of
+Apache ActiveMQ Artemis on the back end without sacrificing the simplicity of a
+REST interface.</p>
+</li>
+</ul>
+<h2 id="installation-and-configuration">Installation and Configuration</h2>
+<p>Apache ActiveMQ Artemis's REST interface is installed as a Web archive (WAR). It depends on the <a href="http://jboss.org/resteasy" target="_blank">RESTEasy</a> project and can currently only run within a servlet container. Installing the Apache ActiveMQ Artemis REST interface is a little bit different depending whether Apache ActiveMQ Artemis is already embedded (e.g. you're deploying within Wildfly) or configured on the network somewhere, or you want the ActiveMQ Artemis REST WAR itself to startup and manage the Apache ActiveMQ Artemis server.</p>
+<h3 id="installing-within-pre-configured-environment">Installing Within Pre-configured Environment</h3>
+<p>This section should be used when you want to use the Apache ActiveMQ Artemis REST interface in an environment that already has Apache ActiveMQ Artemis installed and running. You must create a Web archive (.WAR) file with the following web.xml settings:</p>
+<pre><code><web-app>
+ <listener>
+ <listener-class>
+ org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.artemis.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>
+</code></pre><p>Within your WEB-INF/lib directory you must have the artemis-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 a WAR with the Apache ActiveMQ Artemis REST library.</p>
+<pre><code><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>artemis-rest</artifactId>
+ <packaging>war</packaging>
+ <name>My App</name>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.activemq.rest</groupId>
+ <artifactId>artemis-rest</artifactId>
+ <version>$VERSION</version>
+ <exclusions>
+ <exclusion>
+ <groupId>*</groupId>
+ <artifactId>*</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+</project>
+</code></pre><p>The project structure should look this like:</p>
+<pre><code>|-- pom.xml
+`-- src
+ `-- main
+ `-- webapp
+ `-- WEB-INF
+ `-- web.xml
+</code></pre><p>It is worth noting that when deploying a WAR in a Java EE application server like Wildfly 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. <a href="http://localhost:8080/activemq-rest/[queues|topics" target="_blank">http://localhost:8080/activemq-rest/[queues|topics</a>]. We'll see more about this later.</p>
+<h3 id="bootstrapping-activemq-artemis-along-with-rest">Bootstrapping ActiveMQ Artemis Along with REST</h3>
+<p>You can bootstrap Apache ActiveMQ Artemis within your WAR as well. To do this, you must have the Apache ActiveMQ Artemis core and JMS jars along with Netty, RESTEasy, and the Apache ActiveMQ Artemis REST jar within your WEB-INF/lib. You must also have a broker.xml config file within WEB-INF/classes. The examples that come with the Apache ActiveMQ Artemis REST distribution show how to do this. You must also add an additional listener to your web.xml file. Here's an example:</p>
+<pre><code><web-app>
+ <listener>
+ <listener-class>
+ org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.artemis.rest.integration.ActiveMQBootstrapListener
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.artemis.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>
+</code></pre><p>Here's a Maven pom.xml file for creating a WAR for this environment. Make sure your Apache ActiveMQ Artemis configuration file(s) are within the src/main/resources directory so that they are stuffed within the WAR's WEB-INF/classes directory!</p>
+<pre><code><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>artemis-rest</artifactId>
+ <packaging>war</packaging>
+ <name>My App</name>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.activemq.rest</groupId>
+ <artifactId>artemis-rest</artifactId>
+ <version>$VERSION</version>
+ </dependency>
+ </dependencies>
+</project>
+</code></pre><p>The project structure should look this like:</p>
+<pre><code>|-- pom.xml
+`-- src
+ `-- main
+ `-- resources
+ `-- broker.xml
+ `-- webapp
+ `-- WEB-INF
+ `-- web.xml
+</code></pre><h3 id="rest-configuration">REST Configuration</h3>
+<p>The Apache ActiveMQ Artemis 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
+<code>rest.messaging.config.file</code> to specify the name of the configuration
+file. Below is the format of the XML configuration file and the default
+values for each.</p>
+<pre><code><rest-messaging>
+ <server-in-vm-id>0</server-in-vm-id> <!-- deprecated, use "url" -->
+ <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> <!-- deprecated, use "url" -->
+ <url>vm://0</url>
+</rest-messaging>
+</code></pre><p>Let's give an explanation of each config option.</p>
+<ul>
+<li><p><code>server-in-vm-id</code>. The Apache ActiveMQ Artemis REST implementation was formerly hard-coded
+to use the in-vm transport to communicate with the embedded Apache ActiveMQ Artemis instance.
+This is the id of the embedded instance. It is "0" by default. Note: this is deprecated in
+favor of <code>url</code> which can be used to connect to an arbitrary instance of Apache ActiveMQ
+Artemis (including one over the network).</p>
+</li>
+<li><p><code>use-link-headers</code>. By default, all links (URLs) are published using
+custom headers. You can instead have the Apache ActiveMQ Artemis REST
+implementation publish links using the <a href="http://tools.ietf.org/html/draft-nottingham-http-link-header-10" target="_blank">Link Header
+specification</a>
+instead if you desire.</p>
+</li>
+<li><p><code>default-durable-send</code>. Whether a posted message should be persisted
+by default if the user does not specify a durable query parameter.</p>
+</li>
+<li><p><code>dups-ok</code>. If this is true, no duplicate detection protocol will be
+enforced for message posting.</p>
+</li>
+<li><p><code>topic-push-store-dir</code>. This must be a relative or absolute file
+system path. This is a directory where push registrations for topics
+are stored. See <a href="#message-push">Pushing Messages</a>.</p>
+</li>
+<li><p><code>queue-push-store-dir</code>. This must be a relative or absolute file
+system path. This is a directory where push registrations for queues
+are stored. See <a href="#message-push">Pushing Messages</a>.</p>
+</li>
+<li><p><code>producer-session-pool-size</code>. The REST implementation pools Apache ActiveMQ Artemis
+sessions for sending messages. This is the size of the pool. That
+number of sessions will be created at startup time.</p>
+</li>
+<li><p><code>producer-time-to-live</code>. Default time to live for posted messages.
+Default is no ttl.</p>
+</li>
+<li><p><code>session-timeout-task-interval</code>. 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.</p>
+</li>
+<li><p><code>consumer-session-timeout-seconds</code>. Timeout in seconds for pull
+consumers/subscriptions that remain idle for that amount of time.</p>
+</li>
+<li><p><code>consumer-window-size</code>. For consumers, this config option is the
+same as the Apache ActiveMQ Artemis one of the same name. It will be used by
+sessions created by the Apache ActiveMQ Artemis REST implementation.
+This is deprecated in favor of <code>url</code> as it can be specified as a URL
+parameter.</p>
+</li>
+<li><p><code>url</code>. The URL the Apache ActiveMQ Artemis REST implementation should use
+to connect to the Apache ActiveMQ Artemis instance. Default to "vm://0".</p>
+</li>
+</ul>
+<h2 id="apache-activemq-artemis-rest-interface-basics">Apache ActiveMQ Artemis REST Interface Basics</h2>
+<p>The Apache ActiveMQ Artemis 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 other 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.</p>
+<h3 id="queue-and-topic-resources">Queue and Topic Resources</h3>
+<p>To interact with a queue or topic you do a HEAD or GET request on the
+following relative URI pattern:</p>
+<pre><code>/queues/{name}
+/topics/{name}
+</code></pre><p>The base of the URI is the base URL of the WAR you deployed the Apache ActiveMQ Artemis
+REST server within as defined in the <a href="#install">Installation and
+Configuration</a> section of this document. Replace the <code>{name}</code>
+string within the above URI pattern with the name of the queue or topic
+you are interested in interacting with. Next, perform your HEAD or GET
+request on this URI. Here's what a request/response would look like.</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-create-with-id: http://example.com/queues/bar/create/{id}
+msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+msg-push-consumers: http://example.com/queues/bar/push-consumers
+</code></pre><blockquote>
+<p><strong>Note</strong></p>
+<p>You can use the "curl" utility to test this easily. Simply execute a
+command like this:</p>
+<pre><code>curl --head http://example.com/queues/bar
+</code></pre></blockquote>
+<p>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 Apache ActiveMQ Artemis REST interface evolves over time.</p>
+<h3 id="queue-resource-response-headers">Queue Resource Response Headers</h3>
+<p>Below is a list of response headers you should expect when interacting
+with a Queue resource.</p>
+<ul>
+<li><p><code>msg-create</code>. This is a URL you POST messages to. The semantics of
+this link are described in <a href="#posting-messages">Posting Messages</a>.</p>
+</li>
+<li><p><code>msg-create-with-id</code>. This is a URL <em>template</em> you can use to POST
+messages. The semantics of this link are described in <a href="#posting-messages">Posting
+Messages</a>.</p>
+</li>
+<li><p><code>msg-pull-consumers</code>. This is a URL for creating consumers that will
+pull from a queue. The semantics of this link are described in
+<a href="#message-pull">Consuming Messages via Pull</a>.</p>
+</li>
+<li><p><code>msg-push-consumers</code>. This is a URL for registering other URLs you
+want the Apache ActiveMQ Artemis REST server to push messages to. The semantics of
+this link are described in <a href="#message-push">Pushing Messages</a>.</p>
+</li>
+</ul>
+<h3 id="topic-resource-response-headers">Topic Resource Response Headers</h3>
+<p>Below is a list of response headers you should expect when interacting
+with a Topic resource.</p>
+<ul>
+<li><p><code>msg-create</code>. This is a URL you POST messages to. The semantics of
+this link are described in <a href="#posting-messages">Posting Messages</a>.</p>
+</li>
+<li><p><code>msg-create-with-id</code>. This is a URL <em>template</em> you can use to POST
+messages. The semantics of this link are described in <a href="#posting-messages">Posting
+Messages</a>.</p>
+</li>
+<li><p><code>msg-pull-subscriptions</code>. This is a URL for creating subscribers
+that will pull from a topic. The semantics of this link are
+described in <a href="#message-pull">Consuming Messages via Pull</a>.</p>
+</li>
+<li><p><code>msg-push-subscriptions</code>. This is a URL for registering other URLs
+you want the Apache ActiveMQ Artemis REST server to push messages to. The semantics
+of this link are described in <a href="#message-push">Pushing Messages</a>.</p>
+</li>
+</ul>
+<h2 id="posting-messages">Posting Messages</h2>
+<p>This chapter discusses the protocol for posting messages to a queue or a
+topic. In <a href="#basics">Apache ActiveMQ Artemis REST Interface Basics</a>, you saw that a
+queue or topic resource publishes variable custom headers that are links
+to other RESTful resources. The <code>msg-create</code> 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 <code>msg-create</code> header.
+The HTTP message contains whatever content you want to publish to the
+Apache ActiveMQ Artemis destination. Here's an example scenario:</p>
+<blockquote>
+<p><strong>Note</strong></p>
+<p>You can also post messages to the URL template found in
+<code>msg-create-with-id</code>, but this is a more advanced use-case involving
+duplicate detection that we will discuss later in this section.</p>
+</blockquote>
+<ol>
+<li><p>Obtain the starting <code>msg-create</code> header from the queue or topic
+resource.</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-create-with-id: http://example.com/queues/bar/create/{id}
+</code></pre></li>
+<li><p>Do a POST to the URL contained in the <code>msg-create</code> header.</p>
+<pre><code>POST /queues/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/bar/create
+</code></pre><blockquote>
+<p><strong>Note</strong></p>
+<p>You can use the "curl" utility to test this easily. Simply execute
+a command like this:</p>
+<pre><code>curl --verbose --data "123" http://example.com/queues/bar/create
+</code></pre></blockquote>
+<p>A successful response will return a 201 response code. Also notice
+that a <code>msg-create-next</code> response header is sent as well. You must
+use this URL to POST your next message.</p>
+</li>
+<li><p>POST your next message to the queue using the URL returned in the
+<code>msg-create-next</code> header.</p>
+<pre><code>POST /queues/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/bar/create
+</code></pre><p>Continue using the new <code>msg-create-next</code> header returned with each
+response.</p>
+</li>
+</ol>
+<blockquote>
+<p><strong>Warning</strong></p>
+<p>It is <em>VERY IMPORTANT</em> that you never re-use returned
+<code>msg-create-next</code> headers to post new messages. If the <code>dups-ok</code>
+configuration property is set to <code>false</code> 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 <code>msg-create-next</code> header,
+then just go back to the queue or topic resource to get the
+<code>msg-create</code> URL again.</p>
+</blockquote>
+<h3 id="duplicate-detection">Duplicate Detection</h3>
+<p>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 Apache ActiveMQ Artemis REST interface is
+configured to accept and post duplicate messages. You can change this by
+turning on duplicate message detection by setting the <code>dups-ok</code> config
+option to <code>false</code> as described in <a href="#basics">Apache ActiveMQ Artemis REST Interface
+Basics</a>. When you do this, the initial POST to the <code>msg-create</code>
+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:</p>
+<ol>
+<li><p>Obtain the starting <code>msg-create</code> header from the queue or topic
+resource.</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-create-with-id: http://example.com/queues/bar/create/{id}
+</code></pre></li>
+<li><p>Do a POST to the URL contained in the <code>msg-create</code> header.</p>
+<pre><code>POST /queues/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/bar/create/13582001787372
+</code></pre><p>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 <code>Location</code> header.</p>
+</li>
+<li><p>re-POST your message to the URL provided within the <code>Location</code>
+header.</p>
+<pre><code>POST /queues/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/bar/create/13582001787373
+</code></pre><p>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 <code>msg-create-next</code> header returned with each response.</p>
+</li>
+<li><p>POST any new message to the returned <code>msg-create-next</code> header.</p>
+<pre><code>POST /queues/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/bar/create/13582001787374
+</code></pre><p>If there ever is a network problem, just repost to the URL provided
+in the <code>msg-create-next</code> header.</p>
+</li>
+</ol>
+<p>How can this work? As you can see, with each successful response, the
+Apache ActiveMQ Artemis 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 Apache ActiveMQ Artemis's duplicate detection mechanism by setting the
+<code>DUPLICATE_DETECTION_ID</code> property of the JMS message that is actually
+posted to the system.</p>
+<p>If you happen to use the same ID more than once you'll see a message
+like this on the server:</p>
+<pre><code>WARN [org.apache.activemq.artemis.core.server] (Thread-3 (Apache ActiveMQ Artemis-remoting-threads-ActiveMQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) AMQ112098: Duplicate message detected - message will not be routed. Message information:
+ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _AMQ_DUPL_ID=42}]]@12835058
+</code></pre><p>An alternative to this approach is to use the <code>msg-create-with-id</code>
+header. This is not an invokable URL, but a URL template. The idea is
+that the client provides the <code>DUPLICATE_DETECTION_ID</code> and creates its
+own <code>create-next</code> URL. The <code>msg-create-with-id</code> header looks like this
+(you've see it in previous examples, but we haven't used it):</p>
+<pre><code>msg-create-with-id: http://example.com/queues/bar/create/{id}
+</code></pre><p>You see that it is a regular URL appended with a <code>{id}</code>. This <code>{id}</code> is
+a pattern matching substring. A client would generate its
+<code>DUPLICATE_DETECTION_ID</code> and replace <code>{id}</code> with that generated id, then
+POST to the new URL. The URL the client creates works exactly like a
+<code>create-next</code> URL described earlier. The response of this POST would
+also return a new <code>msg-create-next</code> header. The client can continue to
+generate its own DUPLICATE_DETECTION_ID, or use the new URL returned
+via the <code>msg-create-nex</code>t header.</p>
+<p>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
+<code>DUPLICATE_DETECTION_ID</code> once.</p>
+<h3 id="persistent-messages">Persistent Messages</h3>
+<p>By default, posted messages are not durable and will not be persisted in
+Apache ActiveMQ Artemis'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 <code>durable</code> to true when you post your messages to the URLs
+returned in the <code>msg-create</code>, <code>msg-create-with-id</code>, or <code>msg-create-next</code>
+headers. here's an example of that.</p>
+<pre><code>POST /queues/bar/create?durable=true
+Host: example.com
+Content-Type: application/xml
+
+<order>
+ <name>Bill</name>
+ <item>iPhone4</item>
+ <cost>$199.99</cost>
+</order>
+</code></pre><h3 id="ttl-expiration-and-priority">TTL, Expiration and Priority</h3>
+<p>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 <code>expiration</code> query parameter is a long specifying the time in
+milliseconds since epoch (a long date). The <code>ttl</code> query parameter is a
+time in milliseconds you want the message active. The <code>priority</code> is
+another query parameter with an integer value between 0 and 9 expressing
+the priority of the message. i.e.:</p>
+<pre><code>POST /queues/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>
+</code></pre><h2 id="consuming-messages-via-pull">Consuming Messages via Pull</h2>
+<p>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 Apache ActiveMQ Artemis through a REST
+interface.</p>
+<p>You create consumer resources by doing a simple POST to the URL
+published by the <code>msg-pull-consumers</code> response header if you are
+interacting with a queue, the <code>msg-pull-subscribers</code> response header if
+you're interacting with a topic. These headers are provided by the main
+queue or topic resource discussed in <a href="#basics">Apache ActiveMQ Artemis REST Interface
+Basics</a>. 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 (<code>application/x-www-form-urlencoded</code>) described below.</p>
+<ul>
+<li><p><code>autoAck</code>. A value of <code>true</code> or <code>false</code> can be given. This defaults
+to <code>true</code> if you do not pass this parameter.</p>
+</li>
+<li><p><code>durable</code>. A value of <code>true</code> or <code>false</code> can be given. This defaults
+to <code>false</code> 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.</p>
+</li>
+<li><p><code>name</code>. 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.</p>
+</li>
+<li><p><code>selector</code>. This is an optional JMS selector string. The Apache ActiveMQ Artemis
+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 '$'.</p>
+</li>
+<li><p><code>idle-timeout</code>. For a topic subscription, idle time in milliseconds
+in which the consumer connections will be closed if idle.</p>
+</li>
+<li><p><code>delete-when-idle</code>. Boolean value, If true, a topic subscription
+will be deleted (even if it is durable) when the idle timeout is
+reached.</p>
+</li>
+</ul>
+<blockquote>
+<p><strong>Note</strong></p>
+<p>If you have multiple pull-consumers active at the same time on the
+same destination be aware that unless the <code>consumer-window-size</code> is 0
+then one consumer might buffer messages while the other consumer gets
+none.</p>
+</blockquote>
+<h3 id="auto-acknowledge">Auto-Acknowledge</h3>
+<p>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.</p>
+<ul>
+<li><p><code>msg-pull-consumers</code>. The URL of a factory resource for creating
+queue consumer resources. You will pull from these created
+resources.</p>
+</li>
+<li><p><code>msg-pull-subscriptions</code>. The URL of a factory resource for creating
+topic subscription resources. You will pull from the created
+resources.</p>
+</li>
+<li><p><code>msg-consume-next</code>. The URL you will pull the next message from.
+This is returned with every response.</p>
+</li>
+<li><p><code>msg-consumer</code>. This is a URL pointing back to the consumer or
+subscription resource created for the client.</p>
+</li>
+</ul>
+<h4 id="creating-an-auto-ack-consumer-or-subscription">Creating an Auto-Ack Consumer or Subscription</h4>
+<p>Here is an example of creating an auto-acknowledged queue pull consumer.</p>
+<ol>
+<li><p>Find the pull-consumers URL by doing a HEAD or GET request to the
+base queue resource.</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+msg-push-consumers: http://example.com/queues/bar/push-consumers
+</code></pre></li>
+<li><p>Next do an empty POST to the URL returned in the
+<code>msg-pull-consumers</code> header.</p>
+<pre><code>POST /queues/bar/pull-consumers HTTP/1.1
+Host: example.com
+
+--- response ---
+HTTP/1.1 201 Created
+Location: http://example.com/queues/bar/pull-consumers/auto-ack/333
+msg-consume-next: http://example.com/queues/bar/pull-consumers/auto-ack/333/consume-next-1
+</code></pre><p>The <code>Location</code> 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.</p>
+</li>
+</ol>
+<p>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.</p>
+<ol>
+<li><p>Find the <code>pull-subscriptions</code> URL by doing a HEAD or GET request to
+the base topic resource</p>
+<pre><code>HEAD /topics/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/topics/foo/create
+msg-pull-subscriptions: http://example.com/topics/foo/pull-subscriptions
+msg-push-subscriptions: http://example.com/topics/foo/push-subscriptions
+</code></pre></li>
+<li><p>Next do a POST to the URL returned in the <code>msg-pull-subscriptions</code>
+header passing in a <code>true</code> value for the <code>durable</code> form parameter.</p>
+<pre><code>POST /topics/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/foo/pull-subscriptions/auto-ack/222
+msg-consume-next:
+http://example.com/topics/foo/pull-subscriptions/auto-ack/222/consume-next-1
+</code></pre><p>The <code>Location</code> 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.</p>
+</li>
+</ol>
+<h4 id="consuming-messages">Consuming Messages</h4>
+<p>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
+<code>msg-consume-next</code> 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.</p>
+<blockquote>
+<p><strong>Warning</strong></p>
+<p>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.</p>
+</blockquote>
+<p>Here's an example of pulling multiple messages from the consumer
+resource.</p>
+<ol>
+<li><p>Do a POST on the msg-consume-next URL that was returned with the
+consumer or subscription resource discussed earlier.</p>
+<pre><code>POST /queues/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/bar/pull-consumers/333/consume-next-2
+msg-consumer: http://example.com/queues/bar/pull-consumers/333
+
+<order>...</order>
+</code></pre><p>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.</p>
+</li>
+<li><p>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.</p>
+<pre><code>POST /queues/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/bar/pull-consumers/333/consume-next-2
+</code></pre><p>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 Apache ActiveMQ Artemis REST might be redirecting you or adding
+additional data to the URL after timeouts like this.</p>
+</li>
+<li><p>POST to the URL within the last <code>msg-consume-next</code> to get the next
+message.</p>
+<pre><code>POST /queues/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/bar/pull-consumers/333/consume-next-3
+
+<order>...</order>
+</code></pre></li>
+</ol>
+<h4 id="recovering-from-network-failures">Recovering From Network Failures</h4>
+<p>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.</p>
+<h4 id="recovering-from-client-or-server-crashes">Recovering From Client or Server Crashes</h4>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<h3 id="manual-acknowledgement">Manual Acknowledgement</h3>
+<p>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.</p>
+<ul>
+<li><p><code>msg-pull-consumers</code>. The URL of a factory resource for creating
+queue consumer resources. You will pull from these created resources</p>
+</li>
+<li><p><code>msg-pull-subscriptions</code>. The URL of a factory resource for creating
+topic subscription resources. You will pull from the created
+resources.</p>
+</li>
+<li><p><code>msg-acknowledge-next</code>. URL used to obtain the next message in the
+queue or topic subscription. It does not acknowledge the message
+though.</p>
+</li>
+<li><p><code>msg-acknowledgement</code>. URL used to acknowledge a message.</p>
+</li>
+<li><p><code>msg-consumer</code>. This is a URL pointing back to the consumer or
+subscription resource created for the client.</p>
+</li>
+</ul>
+<h4 id="creating-manually-acknowledged-consumers-or-subscriptions">Creating manually-acknowledged consumers or subscriptions</h4>
+<p>Here is an example of creating an auto-acknowledged queue pull consumer.</p>
+<ol>
+<li><p>Find the pull-consumers URL by doing a HEAD or GET request to the
+base queue resource.</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+msg-push-consumers: http://example.com/queues/bar/push-consumers
+</code></pre></li>
+<li><p>Next do a POST to the URL returned in the <code>msg-pull-consumers</code>
+header passing in a <code>false</code> value to the <code>autoAck</code> form parameter .</p>
+<pre><code>POST /queues/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/bar/pull-consumers/acknowledged/333
+msg-acknowledge-next: http://example.com/queues/bar/pull-consumers/acknowledged/333/acknowledge-next-1
+</code></pre><p>The <code>Location</code> 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.</p>
+</li>
+</ol>
+<p>Creating a manually-acknowledged consumer for a topic is pretty much
+the same. Here's an example of creating a durable manually-acknowledged
+topic pull subscription.</p>
+<ol>
+<li><p>Find the <code>pull-subscriptions</code> URL by doing a HEAD or GET request to
+the base topic resource</p>
+<pre><code>HEAD /topics/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/topics/foo/create
+msg-pull-subscriptions: http://example.com/topics/foo/pull-subscriptions
+msg-push-subscriptions: http://example.com/topics/foo/push-subscriptions
+</code></pre></li>
+<li><p>Next do a POST to the URL returned in the <code>msg-pull-subscriptions</code>
+header passing in a <code>true</code> value for the <code>durable</code> form parameter
+and a <code>false</code> value to the <code>autoAck</code> form parameter.</p>
+<pre><code>POST /topics/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/foo/pull-subscriptions/acknowledged/222
+msg-acknowledge-next:
+http://example.com/topics/foo/pull-subscriptions/acknowledged/222/consume-next-1
+</code></pre><p>The <code>Location</code> 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.</p>
+</li>
+</ol>
+<h4 id="consuming-and-acknowledging-a-message">Consuming and Acknowledging a Message</h4>
+<p>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
+<code>msg-acknowledge-next</code> 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
+<code>acknowledgement</code> header which you will use to acknowledge the message.</p>
+<p>Here's an example of pulling multiple messages from the consumer
+resource.</p>
+<ol>
+<li><p>Do a POST on the msg-acknowledge-next URL that was returned with the
+consumer or subscription resource discussed earlier.</p>
+<pre><code>POST /queues/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/bar/pull-consumers/333/acknowledgement/2
+msg-consumer: http://example.com/queues/bar/pull-consumers/333
+
+<order>...</order>
+</code></pre><p>The POST returns the message consumed from the queue. It also
+returns a<code>msg-acknowledgemen</code>t link. You will use this new link to
+acknowledge the message. Notice also a <code>msg-consumer</code> 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.</p>
+</li>
+<li><p>Acknowledge or unacknowledge the message by doing a POST to the URL
+contained in the <code>msg-acknowledgement</code> header. You must pass an
+<code>acknowledge</code> form parameter set to <code>true</code> or <code>false</code> depending on
+whether you want to acknowledge or unacknowledge the message on the
+server.</p>
+<pre><code>POST /queues/bar/pull-consumers/acknowledgement/2
+Host: example.com
+Content-Type: application/x-www-form-urlencoded
+
+acknowledge=true
+
+--- Response ---
+Http/1.1 204 Ok
+msg-acknowledge-next:
+http://example.com/queues/bar/pull-consumers/333/acknowledge-next-2
+</code></pre><p>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.</p>
+</li>
+</ol>
+<h4 id="recovering-from-network-failures">Recovering From Network Failures</h4>
+<p>If you experience a network failure and do not know if your post to a
+<code>msg-acknowledge-next</code> or <code>msg-acknowledgement</code> 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<code>msg-acknowledge-next</code>, 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 <code>msg-acknowledgement</code>. 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.</p>
+<h4 id="recovering-from-client-or-server-crashes">Recovering From Client or Server Crashes</h4>
+<p>If the server crashes and while you are doing a POST to the
+<code>msg-acknowledge-next</code> URL, just re-post. Everything should reconnect
+all right. On the other hand, if the server crashes while you are doing
+a POST to<code>msg-acknowledgement</code>, 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
+<code>msg-acknowledge-next</code> header to invoke on.</p>
+<p>As long as you have "bookmarked" the consumer resource URL (returned
+from <code>Location</code> header on a create, or the <code>msg-consumer</code> 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
+<code>msg-acknowledgement</code> header in the response. If the consumer resource
+is expecting you to pull for the next message, the
+<code>msg-acknowledge-next</code> 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.</p>
+<h4 id="blocking-pulls-with-accept-wait">Blocking Pulls with Accept-Wait</h4>
+<p>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 Apache ActiveMQ Artemis REST interface provides the
+<code>Accept-Wait</code> 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:</p>
+<pre><code>POST /queues/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/bar/pull-consumers/333/consume-next-3
+
+<order>...</order>
+</code></pre><p>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.</p>
+<h3 id="clean-up-your-consumers">Clean Up Your Consumers!</h3>
+<p>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 <code>consumer-session-timeout-seconds</code>
+configured from <a href="#configuration">REST configuration</a>, 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).</p>
+<h2 id="pushing-messages">Pushing Messages</h2>
+<p>You can configure the Apache ActiveMQ Artemis 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 Apache ActiveMQ Artemis REST server to load
+at boot time.</p>
+<h3 id="the-queue-push-subscription-xml">The Queue Push Subscription XML</h3>
+<p>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:</p>
+<pre><code><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>
+</code></pre><p>The <code>durable</code> 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<code>false</code>. If durable is set to true, an XML file for the push
+subscription will be created within the directory specified by the
+<code>queue-push-store-dir</code> config variable defined in Chapter 2
+(<code>topic-push-store-dir</code> for topics).</p>
+<p>The <code>selector</code> 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.</p>
+<p>The <code>maxRetries</code> element specifies how many times a the server will try
+to push a message to a URL if there is a connection failure.</p>
+<p>The <code>retryWaitMillis</code> element specifies how long to wait before
+performing a retry.</p>
+<p>The <code>disableOnFailure</code> 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 Apache ActiveMQ Artemis will
+take over.</p>
+<p>The <code>link</code> element specifies the basis of the interaction. The <code>href</code>
+attribute contains the URL you want to interact with. It is the only
+required attribute. The <code>type</code> attribute specifies the content-type of
+what the push URL is expecting. The <code>method</code> 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 <code>rel</code> attribute is very
+important and the value of it triggers different behavior. Here's the
+values a rel attribute can have:</p>
+<ul>
+<li><p><code>destination</code>. The href URL is assumed to be a queue or topic
+resource of another Apache ActiveMQ Artemis 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 Apache ActiveMQ Artemis REST endpoint reliably. Here's an example:</p>
+<pre><code><push-registration>
+ <link rel="destination" href="http://somewhere.com/queues/foo"/>
+</push-registration>
+</code></pre></li>
+<li><p><code>template</code>. 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:</p>
+<pre><code><push-registration>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
+</push-registration>
+</code></pre><p>In this example, the {id} sub-string is the one and only one URL
+parameter.</p>
+</li>
+<li><p><code>user defined</code>. 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:</p>
+<pre><code><push-registration>
+ <link href="http://somewhere.com" type="application/json" method="PUT"/>
+</push-registration>
+</code></pre></li>
+</ul>
+<h3 id="the-topic-push-subscription-xml">The Topic Push Subscription XML</h3>
+<p>The push XML for a topic is the same except the root element is
+push-topic-registration. (Also remember the <code>selector</code> element is
+optional). The rest of the document is the same. Here's an example of a
+template registration:</p>
+<pre><code><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>
+</code></pre><h3 id="creating-a-push-subscription-at-runtime">Creating a Push Subscription at Runtime</h3>
+<p>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:</p>
+<ol>
+<li><p>First do a HEAD request to the queue resource:</p>
+<pre><code>HEAD /queues/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/queues/bar/create
+msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+msg-push-consumers: http://example.com/queues/bar/push-consumers
+</code></pre></li>
+<li><p>Next POST your subscription XML to the URL returned from
+msg-push-consumers header</p>
+<pre><code>POST /queues/bar/push-consumers
+Host: example.com
+Content-Type: application/xml
+
+<push-registration>
+ <link rel="destination" href="http://somewhere.com/queues/foo"/>
+</push-registration>
+
+--- Response ---
+HTTP/1.1 201 Created
+Location: http://example.com/queues/bar/push-consumers/1-333-1212
+</code></pre><p>The Location header contains the URL for the created resource. If
+you want to unregister this, then do a HTTP DELETE on this URL.</p>
+</li>
+</ol>
+<p>Here's an example of creating a push registration for a topic:</p>
+<ol>
+<li><p>First do a HEAD request to the topic resource:</p>
+<pre><code>HEAD /topics/bar HTTP/1.1
+Host: example.com
+
+--- Response ---
+HTTP/1.1 200 Ok
+msg-create: http://example.com/topics/bar/create
+msg-pull-subscriptions: http://example.com/topics/bar/pull-subscriptions
+msg-push-subscriptions: http://example.com/topics/bar/push-subscriptions
+</code></pre></li>
+<li><p>Next POST your subscription XML to the URL returned from
+msg-push-subscriptions header</p>
+<pre><code>POST /topics/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/bar/push-subscriptions/1-333-1212
+</code></pre><p>The Location header contains the URL for the created resource. If
+you want to unregister this, then do a HTTP DELETE on this URL.</p>
+</li>
+</ol>
+<h3 id="creating-a-push-subscription-by-hand">Creating a Push Subscription by Hand</h3>
+<p>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.</p>
+<p>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:</p>
+<pre><code><push-registration id="111">
+ <destination>bar</destination>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
+</push-registration>
+</code></pre><p>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:</p>
+<pre><code><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>foo</topic>
+</push-topic-registration>
+</code></pre><h3 id="pushing-to-authenticated-servers">Pushing to Authenticated Servers</h3>
+<p>Push subscriptions only support BASIC and DIGEST authentication out of
+the box. Here is an example of adding BASIC authentication:</p>
+<pre><code><push-topic-registration>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
+ <authentication>
+ <basic-auth>
+ <username>guest</username>
+ <password>geheim</password>
+ </basic-auth>
+ </authentication>
+</push-topic registration>
+</code></pre><p>For DIGEST, just replace basic-auth with digest-auth.</p>
+<p>For other authentication mechanisms, you can register headers you want
+transmitted with each request. Use the header element with the name
+attribute representing the name of the header. Here's what custom
+headers might look like:</p>
+<pre><code><push-topic-registration>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
+ <header name="secret-header">jfdiwe3321</header>
+</push-topic registration>
+</code></pre><h2 id="creating-destinations">Creating Destinations</h2>
+<p>You can create a durable queue or topic through the REST interface.
+Currently you cannot create a temporary queue or topic. To create a
+queue you do a POST to the relative URL /queues with an XML
+representation of the queue. For example:</p>
+<pre><code>POST /queues
+Host: example.com
+Content-Type: application/activemq.xml
+
+<queue name="testQueue">
+ <durable>true</durable>
+</queue>
+
+--- Response ---
+HTTP/1.1 201 Created
+Location: http://example.com/queues/testQueue
+</code></pre><p>Notice that the Content-Type is application/activemq.xml.</p>
+<p>Here's what creating a topic would look like:</p>
+<pre><code>POST /topics
+Host: example.com
+Content-Type: application/activemq.xml
+
+<topic name="testTopic">
+</topic>
+
+--- Response ---
+HTTP/1.1 201 Created
+Location: http://example.com/topics/testTopic
+</code></pre><h2 id="securing-the-apache-activemq-artemis-rest-interface">Securing the Apache ActiveMQ Artemis REST Interface</h2>
+<h3 id="within-wildfly-application-server">Within Wildfly Application server</h3>
+<p>Securing the Apache ActiveMQ Artemis REST interface is very simple with the Wildfly
+Application Server. You turn on authentication for all URLs within your
+WAR's web.xml, and let the user Principal to propagate to Apache ActiveMQ Artemis. This
+only works if you are using the JAASSecurityManager with Apache ActiveMQ Artemis. See
+the Apache ActiveMQ Artemis documentation for more details.</p>
+<h3 id="security-in-other-environments">Security in other environments</h3>
+<p>To secure the Apache ActiveMQ Artemis REST interface in other environments you must
+role your own security by specifying security constraints with your
+web.xml for every path of every queue and topic you have deployed. Here
+is a list of URI patterns:</p>
+<table>
+<thead>
+<tr>
+<th>Post</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td> /queues</td>
+<td>secure the POST operation to secure queue creation</td>
+</tr>
+<tr>
+<td> /queues/{queue-name}/create/</td>
+<td>secure this URL pattern for producing messages.</td>
+</tr>
+<tr>
+<td> /queues/{queue-name}/pull-consumers/</td>
+<td>secure this URL pattern for pushing messages.</td>
+</tr>
+<tr>
+<td> /queues/{queue-name}/push-consumers/</td>
+<td>secure the POST operation to secure topic creation</td>
+</tr>
+<tr>
+<td> /topics</td>
+<td>secure the POST operation to secure topic creation</td>
+</tr>
+<tr>
+<td> /topics/{topic-name}</td>
+<td>secure the GET HEAD operation to getting information about the topic.</td>
+</tr>
+<tr>
+<td> /topics/{topic-name}/create/</td>
+<td>secure this URL pattern for producing messages</td>
+</tr>
+<tr>
+<td> /topics/{topic-name}/pull-subscriptions/</td>
+<td>secure this URL pattern for pulling messages</td>
+</tr>
+<tr>
+<td> /topics/{topic-name}/push-subscriptions/</td>
+<td>secure this URL pattern for pushing messages</td>
+</tr>
+</tbody>
+</table>
+<h2 id="mixing-jms-and-rest">Mixing JMS and REST</h2>
+<p>The Apache ActiveMQ Artemis REST interface supports mixing JMS and REST producers and
+consumers. You can send an ObjectMessage through a JMS Producer, and
+have a REST client consume it. You can have a REST client POST a message
[... 114 lines stripped ...]