[jboss-cvs] JBoss Messaging SVN: r6760 - in trunk: examples/jms/dead-letter and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed May 13 05:22:39 EDT 2009
Author: jmesnil
Date: 2009-05-13 05:22:39 -0400 (Wed, 13 May 2009)
New Revision: 6760
Modified:
trunk/docs/user-manual/en/modules/message-expiry.xml
trunk/docs/user-manual/en/modules/undelivered-messages.xml
trunk/examples/jms/dead-letter/readme.html
trunk/examples/jms/delayed-redelivery/readme.html
Log:
user manual
* undelivered messages chapter
* updated dead-letter & delayed-redelivery readmes
* fixed typos
Modified: trunk/docs/user-manual/en/modules/message-expiry.xml
===================================================================
--- trunk/docs/user-manual/en/modules/message-expiry.xml 2009-05-13 08:47:44 UTC (rev 6759)
+++ trunk/docs/user-manual/en/modules/message-expiry.xml 2009-05-13 09:22:39 UTC (rev 6760)
@@ -4,7 +4,7 @@
<para>Messages can be retained in the messaging system for a limited period of time before being
removed. JMS specification states that clients should not receive messages that have been
expired (but it does not guarantee this will not happen).</para>
- <para>JBoss Messaging's addresses can be assigned a expiry address that when messages are
+ <para>JBoss Messaging's addresses can be assigned a expiry address so that, when messages are
expired, they are removed from the queue and sent to the expiry address. These
<emphasis>expired</emphasis> messages can later be consumed for further inspection.</para>
<section>
Modified: trunk/docs/user-manual/en/modules/undelivered-messages.xml
===================================================================
--- trunk/docs/user-manual/en/modules/undelivered-messages.xml 2009-05-13 08:47:44 UTC (rev 6759)
+++ trunk/docs/user-manual/en/modules/undelivered-messages.xml 2009-05-13 09:22:39 UTC (rev 6760)
@@ -1,21 +1,95 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="undelivered-messages">
<title>Undelivered Messages</title>
- <para>blah</para>
-
+ <para>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back).
+ Such a message goes back to its queue ready to be redelivered.
+ However, this means it is possible for a message to be delivered
+ again and again without any success and remain in the queue, clogging the system.</para>
+ <para>There are 2 ways to deal with these undelivered messages:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>delayed redelivery</literal></para>
+ <para>It is possible to delay messages redelivery to let the client some time to recover
+ from transient failures and not overload its network or CPU resources</para>
+ </listitem>
+ <listitem>
+ <para><literal>dead letter address</literal></para>
+ <para>It is also possible to configure a dead letter address so that after a specified
+ number of unsuccessful deliveries, messages are removed from the queue and will not
+ be delivered again</para>
+ </listitem>
+ </itemizedlist>
+ <para>Both options can be combined for maximum flexibility.</para>
+
<section>
- <title>Message redelivery</title>
- <para></para>
+ <title>Delayed Redelivery</title>
+ <para>Delaying redelivery can often be useful in the case that clients regularly fail or rollback.
+ Without a delayed redelivery, the system can get into a "thrashing" state, with delivery being
+ attempted, the client rolling back, and delivery being re-attempted ad infinitum in quick
+ succession, consuming valuable CPU and network resources.</para>
+ <section>
+ <title>Configuring Delayed Redelivery</title>
+ <para>Delayed redelivery is defined in the address-setting configuration:</para>
+ <programlisting>
+ <!-- delay redelivery of messages for 5s -->
+ <address-setting match="jms.queue.exampleQueue">
+ <redelivery-delay>5000</redelivery-delay>
+ </address-setting>
+ </programlisting>
+ <para>If a <literal>redelivery-delay</literal> is specified, JBoss Messaging will wait this delay
+ before redelivering the messages</para>
+ <para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set to 0).</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html">Delayed Redelivery example</ulink> shows
+ how delayed redelivery is configured and used with JMS.</para>
+ </section>
</section>
<section>
- <title>Delayed redelivery</title>
- <para></para>
- </section>
-
- <section>
<title>Dead Letter Addresses</title>
- <para></para>
+ <para>To prevent a client to receive infinitely the same undelivered message (regardless of what is causing
+ the unsuccessful deliveries), messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the queue and send instead to a dead letter address.
+ </para>
+ <para>JBoss Messaging's addresses can be assigned a dead letter address. Once the messages have
+ be unsuccessfully delivered for a given number of attempts, they are removed from the queue
+ and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can later
+ be consumed for further inspection.</para>
+
+ <section>
+ <title>Configuring Dead Letter Addresses</title>
+ <para>Dead letter address is defined in the address-setting configuration:</para>
+ <programlisting>
+ <!-- undelivered messages in exampleQueue will be sent to the dead letter address deadLetterQueue
+ after 3 unsuccessful delivery attempts
+ -->
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ </address-setting>
+ </programlisting>
+ <para>If a <literal>dead-letter-address</literal> is not specified, messages will removed after <literal>max-delivery-attempts</literal> unsuccessful attempts.</para>
+ <para>By default, messages are redelivered 10 times at the maximum. Set <literal>max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
+ <para>For example, a dead letter can be set globally for a set of matching addresses and you can set <literal>max-delivery-attempts</literal>
+ to -1 for a specific address setting to allow infinite redeliveries only for this address.</para>
+ </section>
+ <section>
+ <title>Dead Letter Properties</title>
+ <para>Dead letter messages which are consumed from a dead letter address have the following property:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>_JBM_ORIG_DESTINATION</literal></para>
+ <para>a String property containing the <emphasis>original destination</emphasis> of the
+ dead letter message </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>The <ulink url="../../../../examples/jms/dead-letter/readme.html">Dead Letter example</ulink> shows
+ how dead letter is configured and used with JMS.</para>
+ </section>
</section>
</chapter>
Modified: trunk/examples/jms/dead-letter/readme.html
===================================================================
--- trunk/examples/jms/dead-letter/readme.html 2009-05-13 08:47:44 UTC (rev 6759)
+++ trunk/examples/jms/dead-letter/readme.html 2009-05-13 09:22:39 UTC (rev 6760)
@@ -8,18 +8,18 @@
<p>This example shows you how to define and deal with dead letter messages.</p>
<p>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back).
- Such a message goes back to the JMS destination ready to redelivered.
+ Such a message goes back to the JMS destination ready to be redelivered.
However, this means it is possible for a message to be delivered again and again without any success and remain in the destination, clogging the system.</p>
- <p>To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attemps, the message is removed from the destination
+ <p>To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the destination
and put instead in a <em>dead letter destination</em> where they can be consumed for further investigation.
<p>
- The example will show how to configure JBoss Messaging to send a message to a dead letter destination after 3 unsuccesful delivery attempts.<br />
+ The example will show how to configure JBoss Messaging to send a message to a dead letter destination after 3 unsuccessful delivery attempts.<br />
The example will send 1 message to a queue. We will deliver the message 3 times and rollback the session every time.<br />
On the 4th attempt, there won't be any message to consume: it will have been moved to a <em>dead letter queue</em>.<br />
We will then consume the message from this dead letter queue.
</p>
<h2>Example setup</h2>
- <p><em>Dead letter destinations</em> and <em>maximum delivery attempts</em> are defined in the queue settings configuration file <a href="server0/jbm-queues.xml">jbm-queues.xml</a>:</p>
+ <p><em>Dead letter destinations</em> and <em>maximum delivery attempts</em> are defined in the address settings configuration file <a href="server0/jbm-queues.xml">jbm-queues.xml</a>:</p>
<pre>
<code><address-settings match="jms.queue.exampleQueue">
<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
@@ -199,7 +199,7 @@
<h2>More information</h2>
<ul>
- <li>Dead letter address and delivery attempts are configured on a <a href="../../../docs/userguide/en/html/configuration.html#configuration.queues">queue-basis</a></li>
+ <li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#undelivered-messages">Undelivered Messages chapter</a></li>
</ul>
</body>
</html>
\ No newline at end of file
Modified: trunk/examples/jms/delayed-redelivery/readme.html
===================================================================
--- trunk/examples/jms/delayed-redelivery/readme.html 2009-05-13 08:47:44 UTC (rev 6759)
+++ trunk/examples/jms/delayed-redelivery/readme.html 2009-05-13 09:22:39 UTC (rev 6760)
@@ -18,7 +18,7 @@
matching on the address settings.</p>
<h2>Example setup</h2>
- <p>Redelivery delay is specified in the queue settings configuration file <a href="server0/jbm-queues.xml">jbm-queues.xml</a>:</p>
+ <p>Redelivery delay is specified in the address settings configuration file <a href="server0/jbm-queues.xml">jbm-queues.xml</a>:</p>
<p>In this example we set the redelivery delay to 5 seconds for the specific example queue. We could set redelivery delay on
on multiple queues by specifying a wild-card in the match, e.g. <code>match="jms.#"</code> would apply the settings
to all JMS queues and topics.</p>
@@ -26,7 +26,7 @@
after 5 seconds.</p>
<pre>
<code><address-settings match="jms.queue.exampleQueue">
- <redelivey-delay>5000</redelivey-delay>
+ <redelivery-delay>5000</redelivery-delay>
</address-settings>
</code>
</pre>
@@ -156,5 +156,11 @@
</pre>
</ol>
+ <h2>More information</h2>
+
+ <ul>
+ <li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#undelivered-messages">Undelivered Messages chapter</a></li>
+ </ul>
+
</body>
</html>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list