[jboss-cvs] JBoss Messaging SVN: r6933 - trunk/docs/user-manual/en.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed May 20 10:31:57 EDT 2009
Author: ataylor
Date: 2009-05-20 10:31:57 -0400 (Wed, 20 May 2009)
New Revision: 6933
Modified:
trunk/docs/user-manual/en/undelivered-messages.xml
Log:
reformatted code and tables for undelivered message doc
Modified: trunk/docs/user-manual/en/undelivered-messages.xml
===================================================================
--- trunk/docs/user-manual/en/undelivered-messages.xml 2009-05-20 14:29:45 UTC (rev 6932)
+++ trunk/docs/user-manual/en/undelivered-messages.xml 2009-05-20 14:31:57 UTC (rev 6933)
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="undelivered-messages">
- <title>Message Redelivery and Undelivered Messages</title>
- <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>
+ <title>Message Redelivery and Undelivered Messages</title>
+ <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
@@ -15,107 +15,112 @@
<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>
+ 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>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>
+ </itemizedlist>
+ <para>Both options can be combined for maximum flexibility.</para>
+ <section>
+ <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>
- <para>Address wildcards can be used
- to configure redelivery delay for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
- </section>
- <section>
- <title>Example</title>
- <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html"><literal>delayed-redelivery</literal> example</ulink> shows
- how delayed redelivery is configured and used with JMS.</para>
- </section>
- </section>
-
- <section>
- <title>Dead Letter Addresses</title>
- <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
+ <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>
+ <para>Address wildcards can be used to configure redelivery delay for a set of addresses
+ (see <xref linkend="wildcard-syntax"/>).</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html"><literal
+ >delayed-redelivery</literal> example</ulink> shows how delayed redelivery is
+ configured and used with JMS.</para>
+ </section>
+ </section>
+ <section>
+ <title>Dead Letter Addresses</title>
+ <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>
- <para>Address wildcards can be used
- to configure dead letter settings for a set of addresses (see <xref linkend="wildcard-syntax" />).</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>
+ <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>
+ <para>Address wildcards can be used to configure dead letter settings for a set of
+ addresses (see <xref linkend="wildcard-syntax"/>).</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>
+ <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"><literal>dead-letter</literal> example</ulink> shows
- how dead letter is configured and used with JMS.</para>
- </section>
- </section>
-
- <section id="configuring.delivery.count.persistence">
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>The <ulink url="../../../../examples/jms/dead-letter/readme.html"><literal
+ >dead-letter</literal> example</ulink> shows how dead letter is configured and
+ used with JMS.</para>
+ </section>
+ </section>
+ <section id="configuring.delivery.count.persistence">
<title>Delivery Count Persistence</title>
- <para>In normal use, JBoss Messaging does not update delivery count <emphasis>persistently</emphasis>
- until a message is rolled back (i.e. the delivery count is not updated <emphasis>before</emphasis> the message
- is delivered to the consumer). In most messaging use cases, the messages are consumed, acknowledged and
- forgotten as soon as they are consumed. In these cases, updating the delivery count persistently
- before delivering the message would add an extra persistent step <emphasis>for each message delivered</emphasis>,
- implying a significant performance penalty.</para>
- <para>However, if the delivery count is not updated persistently before the message delivery happens, in the event of
- a server crash, messages might have been delivered but that will not have been reflected in the delivery count. During the recovery phase, the server will not have
- knowledge of that and will deliver the message with <literal>redelivered</literal> set to <literal>false</literal>
- while it should be <literal>true</literal>.
- </para>
- <para>As this behavior breaks strict JMS semantics, JBoss Messaging allows to persist delivery count
- before message delivery but disabled it by default for performance implications.</para>
- <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal>true</literal> in <literal>jbm-configuration.xml</literal>:</para>
+ <para>In normal use, JBoss Messaging does not update delivery count
+ <emphasis>persistently</emphasis> until a message is rolled back (i.e. the delivery
+ count is not updated <emphasis>before</emphasis> the message is delivered to the consumer).
+ In most messaging use cases, the messages are consumed, acknowledged and forgotten as soon
+ as they are consumed. In these cases, updating the delivery count persistently before
+ delivering the message would add an extra persistent step <emphasis>for each message
+ delivered</emphasis>, implying a significant performance penalty.</para>
+ <para>However, if the delivery count is not updated persistently before the message delivery
+ happens, in the event of a server crash, messages might have been delivered but that will
+ not have been reflected in the delivery count. During the recovery phase, the server will
+ not have knowledge of that and will deliver the message with <literal>redelivered</literal>
+ set to <literal>false</literal> while it should be <literal>true</literal>. </para>
+ <para>As this behavior breaks strict JMS semantics, JBoss Messaging allows to persist delivery
+ count before message delivery but disabled it by default for performance
+ implications.</para>
+ <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
+ >true</literal> in <literal>jbm-configuration.xml</literal>:</para>
<programlisting>
<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
</programlisting>
- </section>
-
-
+ </section>
</chapter>
More information about the jboss-cvs-commits
mailing list