You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by bu...@apache.org on 2015/02/11 06:21:34 UTC
svn commit: r939787 - in /websites/production/activemq/content:
cache/main.pageCache rest.html
Author: buildbot
Date: Wed Feb 11 05:21:33 2015
New Revision: 939787
Log:
Production update by buildbot for activemq
Modified:
websites/production/activemq/content/cache/main.pageCache
websites/production/activemq/content/rest.html
Modified: websites/production/activemq/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/activemq/content/rest.html
==============================================================================
--- websites/production/activemq/content/rest.html (original)
+++ websites/production/activemq/content/rest.html Wed Feb 11 05:21:33 2015
@@ -81,14 +81,24 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><p>ActiveMQ implements a RESTful API to messaging which allows any web capable device to publish or consume messages using a regular HTTP POST or GET.</p><p>If you are interested in messaging directly from web browsers you might wanna check out our <a shape="rect" href="ajax.html">Ajax</a> or <a shape="rect" href="websockets.html">WebSockets</a> support or try <a shape="rect" href="web-samples.html">running the REST examples</a></p><h2 id="REST-MappingofRESTtoJMS">Mapping of REST to JMS</h2><p>To publish a message use a HTTP POST. To consume a message use HTTP DELETE or GET.</p><p>ActiveMQ has a Servlet that takes care of the integration between HTTP and the ActiveMQ dispatcher.</p><p>You can map a URI to the servlet and then use the relative part of the URI as the topic or queue name. e.g. you could HTTP POST to</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[http://www.acme.com/queue/orders/input
+<div class="wiki-content maincontent"><p>ActiveMQ implements a RESTful API to messaging which allows any web capable device to publish or consume messages using a regular HTTP POST or GET.</p><p>If you are interested in messaging directly from web browsers you might wanna check out our <a shape="rect" href="ajax.html">Ajax</a> or <a shape="rect" href="websockets.html">WebSockets</a> support or try <a shape="rect" href="web-samples.html">running the REST examples</a></p><h2 id="REST-MappingofRESTtoJMS">Mapping of REST to JMS</h2><p>To publish a message use a HTTP POST. To consume a message use HTTP DELETE or GET.</p><p>ActiveMQ has a Servlet that takes care of the integration between HTTP and the ActiveMQ dispatcher.</p><p><span style="color: rgb(255,153,0);">NOTE: The example below requires servlet mapping on the URL. For posting without mapping, see examples further down.</span></p><p>You can map a URI to the servlet and then use the relative part of the URI as the topic or queue n
ame. e.g. you could HTTP POST to</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[http://www.acme.com/orders/input
]]></script>
-</div></div><p>which would publish the contents of the HTTP POST to the orders.input queue on JMS.</p><p>Similarly you could perform a HTTP DELETE GET on the above URL to read from the same queue. In this case we will map the MessageServlet from ActiveMQ to the URI</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>which would publish the contents of the HTTP POST to the orders.input queue on JMS. </p><p>Similarly you could perform a HTTP DELETE GET on the above URL to read from the same queue. In this case we will map the MessageServlet from ActiveMQ to the URI</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[http://www.acme.com/queue
]]></script>
-</div></div><p>and configure it to accept the URI as a queue destination. We can do similar things to support topic destinations too.</p><p>We can use the HTTP session to denote a unique publisher or consumer.</p><p>Note that strict REST requires that GET be a read only operation; so strictly speaking we should not use GET to allow folks to consume messages. Though we allow this as it simplifies HTTP/DHTML/Ajax integration somewhat.</p><p>For a more cleaner mapping of a simple transfer protocol to different languages, you might wanna take a look at <a shape="rect" href="stomp.html">Stomp</a>.</p><h2 id="REST-Defaultconfiguration">Default configuration</h2><p>Until version 5.8, REST API was part of the <a shape="rect" href="web-samples.html">Web Samples</a> and was mapped to <a shape="rect" class="external-link" href="http://localhost:8161/demo/message" rel="nofollow">http://localhost:8161/demo/message</a> url. From 5.8 onwards, the API is available by default at <a shape="rect" clas
s="external-link" href="http://localhost:8161/api/message" rel="nofollow">http://localhost:8161/api/message</a> url. Also, starting with 5.8, web server is secured by default (see <a shape="rect" href="web-console.html">Web Console</a> for more information), so have that in mind when trying to use it. Examples below will assume new api location and secured web server.</p><h3 id="REST-Producing">Producing</h3><p>You cam produce by sending a POST request to the server, like</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>and configure it to accept the URI as a queue destination. We can do similar things to support topic destinations too.</p><p>We can use the HTTP session to denote a unique publisher or consumer.</p><p>Note that strict REST requires that GET be a read only operation; so strictly speaking we should not use GET to allow folks to consume messages. Though we allow this as it simplifies HTTP/DHTML/Ajax integration somewhat.</p><p>For a more cleaner mapping of a simple transfer protocol to different languages, you might wish to take a look at <a shape="rect" href="stomp.html">Stomp</a>.</p><h2 id="REST-Defaultconfiguration">Default configuration</h2><p>Until version 5.8, REST API was part of the <a shape="rect" href="web-samples.html">Web Samples</a> and was mapped to <a shape="rect" class="external-link" href="http://localhost:8161/demo/message" rel="nofollow">http://localhost:8161/demo/message</a> url. From 5.8 onwards, the API is available by default at <a shape="rect" cl
ass="external-link" href="http://localhost:8161/api/message" rel="nofollow">http://localhost:8161/api/message</a> url. Also, starting with 5.8, web server is secured by default (see <a shape="rect" href="web-console.html">Web Console</a> for more information), so have that in mind when trying to use it. Examples below will assume new api location and secured web server.</p><h3 id="REST-Producing">Producing</h3><p>You can produce by sending a POST request to the server, like</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[curl -u admin:admin -d "body=message" http://localhost:8161/api/message/TEST?type=queue]]></script>
+</div></div><p> </p><p><span style="color: rgb(255,153,0);">NOTE: If no type parameter is specified, the default is to create a  topic. To change the default to queue, initialize  the servlet  with an init param in the <code>webapps/demo/WEB-INF/web.xml</code></span></p><p><span style="color: rgb(255,153,0);">As shown below:</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<servlet>
+ <servlet-name>MessageServlet</servlet-name>
+ <servlet-class>org.apache.activemq.web.MessageServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ <init-param>
+ <param-name>topic</param-name>
+ <param-value>false</param-value>
+ </init-param>
+</servlet>]]></script>
</div></div><h3 id="REST-Timeouts">Timeouts</h3><p>When reading from a queue we might not have any messages. We can use a timeout query parameter to indicate how long we are prepared to wait for a message to arrive. This allows us to poll or block until a message arrives.</p><p>Couple this with HTTP 1.1 keep-alive sockets and pipeline processing we can have efficient access to JMS over HTTP.</p><p>Obviously if your client is Java then using ActiveMQ's JMS API is the fastest and most efficient way to work with the message broker; however, if you are not using Java or prefer the simplicity of HTTP then it should be fairly efficient, especially if your HTTP client supports keep-alive sockets and pipeline processing.</p><h3 id="REST-Consuming">Consuming</h3><p>When consuming messages using the REST API, you have to keep session alive between GET requests, or you'll create a separate consumer for every request and due to prefetch limit your succeeding call will hang.</p><p>For example, y
ou can use <code>wget</code> to consume messages, like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[wget --user admin --password admin --save-cookies cookies.txt --load-cookies cookies.txt --keep-session-cookies http://localhost:8161/api/message/TEST1?type=queue
]]></script>