<!--
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.
-->
<html>
<head>
<title>ActiveMQ Artemis JMS QueueRequestor Example</title>
<link rel="stylesheet" type="text/css" href="../common/common.css" />
<link rel="stylesheet" type="text/css" href="../common/prettify.css" />
<script type="text/javascript" src="../common/prettify.js"></script>
</head>
<body onload="prettyPrint()">
<h1>JMS QueueRequestor Example</h1>
<p>This example shows you how to use a <a href="http://java.sun.com/javaee/5/docs/api/javax/jms/QueueRequestor.html">QueueRequestor</a> with ActiveMQ Artemis.</p>
<p>JMS is mainly used to send messages asynchronously so that the producer of a message is not waiting for the result of the message consumption.
However, there are cases where it is necessary to have a synchronous behavior: the code sending a message requires a reply for this message
before continuing its execution.<br />
A QueueRequestor facilitates this use case by providing a simple request/reply abstraction on top of JMS.</p>
<p>The example consists in two classes:</p>
<dl>
<dt><code>TextReverserService</code></dt>
<dd>A JMS MessageListener which consumes text messages and sends replies containing the reversed text</dd>
<dt><code>QueueRequestorExample</code></dt>
<dd>A JMS Client which uses a QueueRequestor to send text requests to a queue and receive replies with the reversed text in a synchronous fashion</dd>
</dl>
<h2>Example step-by-step</h2>
<p><i>To run the example, simply type <code>mvn verify -Pexample</code> from this directory</i></p>
<ol>
<li>First we need to get an initial context so we can look-up the JMS connection factory from JNDI. This initial context will get it's properties from the <code>client-jndi.properties</code> file in the directory <code>../common/config</code></li>
<pre class="prettyprint">
<code>InitialContext initialContext = getContext();</code>
</pre>
<li>We look up the JMS queue from JNDI</li>
<pre class="prettyprint">
<code>Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");</code>
</pre>
<li>We look up JMS queue connection factory from JNDI</li>
<pre class="prettyprint">
<code>QueueConnectionFactory cf = (QueueConnectionFactory)initialContext.lookup("/ConnectionFactory");</code>
</pre>
<li>We create the TextReverserService which will consume messages from the queue</li>
<pre class="prettyprint">
<code> TextReverserService reverserService = new TextReverserService(cf, queue);</code>
</pre>
<li>We Create a JMS queue connection</li>
<pre class="prettyprint">
<code>connection = cf.createQueueConnection();</code>
</pre>
<li>We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started</li>
<pre class="prettyprint">
<code>connection.start();</code>
</pre>
<li>We create a JMS queue session. The session is created as non transacted and will auto acknowledge messages (this is mandatory to use it to create a QueueRequestor)</li>
<pre class="prettyprint">
<code>QueueSession session = connection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);</code>
</pre>
<li>We create a JMS QueueRequestor using the session and the queue</li>
<pre class="prettyprint">
<code>QueueRequestor queueRequestor = new QueueRequestor(session, queue);</code>
</pre>
<li>We create a JMS text message to send as a request</li>
<pre class="prettyprint">
<code>TextMessage request = session.createTextMessage("Hello, World!");</code>
</pre>
<li><p>We use the queue requestor to send the request and block until a reply is received.<br />
Using the queue requestor simplify request/reply use case by abstracting boilerplate JMS code
(creating a temporary queue, a consumer and a producer, setting the JMS ReplyTo header on the request,
sending the request with the producer, consuming the message from the consumer).
All this code is replaced by a single call to <code>QueueRequestor.request()</code> method.</p>
</li>
<pre class="prettyprint">
<code>TextMessage reply = (TextMessage)queueRequestor.request(request);</code>
</pre>
<li>The reply's text contains the reverse of the request's text</li>
<pre class="prettyprint">
<code>System.out.println("Send request: " + request.getText());
System.out.println("Received reply:" + reply.getText());</code>
</pre>
<li>We close the queue requestor to release all the JMS resources it created to provide request/reply mechanism</li>
<pre class="prettyprint">
<code>queueRequestor.close()</code>
</pre>
<li>We do the same for the text reverser service</li>
<pre class="prettyprint">
<code>reverserService.close()</code>
</pre>
<li>And finally, <b>always</b> remember to close your JMS connections and resources after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>
<pre class="prettyprint">
<code>finally
{
if (initialContext != null)
{
initialContext.close();
}
if (connection != null)
{
connection.close();
}
}</code>
</pre>
</ol>
</body>
</html>
22d54c5830