You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2012/12/24 18:00:40 UTC
svn commit: r1425665 -
/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml
Author: kwall
Date: Mon Dec 24 17:00:40 2012
New Revision: 1425665
URL: http://svn.apache.org/viewvc?rev=1425665&view=rev
Log:
QPID-4502: Apply review comments from Robbie Gemmell
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml
Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml?rev=1425665&r1=1425664&r2=1425665&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml Mon Dec 24 17:00:40 2012
@@ -29,23 +29,25 @@
<section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Introduction">
<title>Introduction</title>
- <para> Messages that cannot be delivered successfully to a consumer (for instance, because a
- consumer using a transcation sessions rolls-back the transaction) will automatically be returned
- to the queue and be subsequently redelivered. This is desirable behaviour that contributes to the
- ability of a system to withstand unexpected errors. However, this leaves open the possibility for
- a message to be repeatedily delivered (potentially indefinitely), consuming system resources and
- preventing the delivery of other messages. Such undeliverable messages are sometimes known as
- poison messages.</para>
+ <para> Messages that cannot be delivered successfully to a consumer (for instance, because the
+ client is using a transacted session and rolls-back the transaction) can be made available on
+ the queue again and then subsequently be redelivered, depending on the precise session
+ acknowledgement mode and messaging model used by the application. This is normally desirable
+ behaviour that contributes to the ability of a system to withstand unexpected errors. However, it
+ leaves open the possibility for a message to be repeatedly redelivered (potentially indefinitely),
+ consuming system resources and preventing the delivery of other messages. Such undeliverable
+ messages are sometimes known as poison messages.</para>
<para>For an example, consider a stock ticker application that has been designed to consume prices
contained within JMS TextMessages. What if inadvertently a BytesMessage is placed onto the queue?
- As the ticker application does not expect the BytesMessage, it processing with fail and
- rolls-back the transaction, however the default behavior of the Broker would mean that the
+ As the ticker application does not expect the BytesMessage, its processing might fail and cause it
+ to roll-back the transaction, however the default behavior of the Broker would mean that the
BytesMessage would be delivered over and over again, preventing the delivery of other legitimate
- messages, until an operator intervenes and removes the erroneous message. </para>
- <para>Qpid has a maximum delivery count and dead-letter queue (DLQ) features which can be used in
- concert to construct a system that automatically handle such a condition. These features are
+ messages, until an operator intervenes and removes the erroneous message from the queue. </para>
+ <para>Qpid has maximum delivery count and dead-letter queue (DLQ) features which can be used in
+ concert to construct a system that automatically handles such a condition. These features are
described in the following sections.</para>
</section>
+
<section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Maximum-Delivery-Count">
<title>Maximum Delivery Count</title>
<para> Maximum delivery count is a property of a queue. If a consumer application is unable to
@@ -54,8 +56,8 @@
<para> In order for a maximum delivery count to be enforced, the consuming client
<emphasis>must</emphasis> call <ulink url="&oracleJeeDocUrl;javax/jms/Session.html#rollback()"
>Session#rollback()</ulink> (or <ulink url="&oracleJeeDocUrl;javax/jms/Session.html#recover()"
- >Session#recover()</ulink> depending on the session's transaction mode). It is during the
- Broker's processing of Session#rollback() (or Session#recover()) that if a message has been seen
+ >Session#recover()</ulink> if the session is not transacted). It is during the Broker's
+ processing of Session#rollback() (or Session#recover()) that if a message has been seen
at least the maximum number of times then it will move the message to the DLQ or discard the
message.</para>
<para>If the consuming client fails in another manner, for instance, closes the connection, the
@@ -65,15 +67,16 @@
set the client system property <varname>qpid.reject.behaviour</varname> or connection or binding
URL option <varname>rejectbehaviour</varname> to the value <literal>system</literal>.</para>
<para>It is possible to determine the number of times a message has been sent to a consumer via
- the Management interfaces, but is not possible to determine this information from JMS.
+ the Management interfaces, but is not possible to determine this information from a message client.
Specifically, the optional JMS message header <property>JMSXDeliveryCount</property> is not
supported.</para>
<para>Maximum Delivery Count can be enabled via management (see <xref
linkend="Java-Broker-Configuring-And-Managing"/>) using the the queue declare property
<property>x-qpid-maximum-delivery-count</property> or via <link
- linkend="Java-Broker-Queues-Handling-Undeliverable-Messages-Configuration">configuration</link>
+ linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration</link>
as illustrated below.</para>
</section>
+
<section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Dead-Letter-Queues">
<title>Dead Letter Queues (DLQ)</title>
<para>A Dead Letter Queue (DLQ) acts as an destination for messages that have somehow exceeded the
@@ -82,10 +85,10 @@
receive the message (typically by exceeding a Maximum Delivery Count) then the message is moved
onto the DLQ and removed from the original queue. </para>
<para>The DLQ feature causes generation of a Dead Letter Exchange and a Dead Letter Queue. These
- are named convention queue_name_DLE and queue_name_DLQ.</para>
+ are named convention QueueName<emphasis>_DLE</emphasis> and QueueName<emphasis>_DLQ</emphasis>.</para>
<para>DLQs can be enabled via management (see <xref linkend="Java-Broker-Configuring-And-Managing"
/>) using the queue declare property <property>x-qpid-dlq-enabled</property> or via <link
- linkend="Java-Broker-Queues-Handling-Undeliverable-Messages-Configuration">configuration</link>
+ linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration</link>
as illustrated below.</para>
<caution>
<title>Avoid excessive queue depth</title>
@@ -96,6 +99,7 @@
depths should not be permitted to develop.</para>
</caution>
</section>
+
<section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">
<title>Configuration</title>
<para>In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org