<!--
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 JMS Automatic Reattach 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 Reattach Example</h1>
<p>This example demonstrates how ActiveMQ connections can be configured to be resilient to
temporary network failures.</p>
<p>In the case of a network failure being detected, either as a result of a failure to read/write to the connection,
or the failure of a pong to arrive back from the server in good time after a ping is sent, instead of
failing the connection immediately and notifying any user ExceptionListener objects, ActiveMQ
can be configured to automatically retry the connection, and reattach to the server when it becomes
available again across the network.</p>
<p>When the client reattaches to the server it will be able to resume using its sessions and connections
where it left off</p>
<p>This is different to client reconnect as the sessions, consumers etc still exist on the server. With reconnect
The client recreates its sessions and consumers as needed.</p>
<p>This example starts a single server, connects to it and performs some JMS operations. We then
simulate failure of the network connection by temporarily stopping the network acceptor on the server.
(This is done by sending management messages, but that is not central to the purpose of the example).</p>
<p>We then wait a few seconds, then restart the acceptor. The client reattaches and the session resumes
as if nothing happened.</p>
<p>The JMS Connection Factory is configured to reattach automatically by specifying the various reconnect
related attributes in the <code>activemq-jms.xml</code> file.</p>
<p>For more details on how to configure this and for clustering in general
please consult the ActiveMQ user manual.</p>
<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>Create an initial context to perform the JNDI lookup.</li>
<pre class="prettyprint">
<code>initialContext = getContext(0);</code>
</pre>
<li>Perform a lookup on the queue</li>
<pre class="prettyprint">
<code>Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");</code>
</pre>
<li>Perform a lookup on the Connection Factory</li>
<pre class="prettyprint">
<code>ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");</code>
</pre>
<li>We create a JMS connection</li>
<pre class="prettyprint">
<code>connection = cf.createConnection();</code>
</pre>
<li>We create a JMS session. </li>
<pre class="prettyprint">
<code>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</code>
</pre>
<li>We create a JMS message producer.</li>
<pre class="prettyprint">
<code>MessageProducer messageProducer = session.createProducer(topic);</code>
</pre>
<li>We create a JMS text message that we are going to send.</li>
<pre class="prettyprint">
<code>TextMessage message = session.createTextMessage("This is a text message");</code>
</pre>
<li>We send message to the queue</li>
<pre class="prettyprint">
<code>messageProducer.send(message);</code>
</pre>
<li>We create a JMS Message Consumer to receive the message.</li>
<pre class="prettyprint">
<code>MessageConsumer messageConsumer = session.createConsumer(queue);</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>To simulate a temporary problem on the network, we stop the remoting acceptor on the
server which will cause all client connections to fail.</li>
<pre class="prettyprint">
<code>stopAcceptor(initialContext);</code>
</pre>
<li>We wait 10 seconds, before restarting the acceptor. During this period the client will be retrying
to connect. When the acceptor is restarted it will be successful in reconnecting.</li>
<pre class="prettyprint">
<code>
Thread.sleep(10000);
startAcceptor(initialContext);
</code>
</pre>
<li>We receive the message after reattachment! Note that no exceptions were received by the client.</li>
<pre class="prettyprint">
<code>
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
</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>
070f641f0d