From fef2efd3a971b9c8a93f3c3cffd6ba8542cdc54b Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Mon, 24 Dec 2012 17:00:40 +0000 Subject: QPID-4502: Apply review comments from Robbie Gemmell git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1425665 13f79535-47bb-0310-9956-ffa450edef68 --- ...ker-Runtime-Handling-Undeliverable-Messages.xml | 40 ++++++++++++---------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml b/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml index 250fbd4a59..40c0e44629 100644 --- a/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml +++ b/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml @@ -29,23 +29,25 @@
Introduction - 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. + 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. 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. - 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. + 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.
+
Maximum Delivery Count Maximum delivery count is a property of a queue. If a consumer application is unable to @@ -54,8 +56,8 @@ In order for a maximum delivery count to be enforced, the consuming client must call Session#rollback() (or Session#recover() 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() 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. If the consuming client fails in another manner, for instance, closes the connection, the @@ -65,15 +67,16 @@ set the client system property qpid.reject.behaviour or connection or binding URL option rejectbehaviour to the value system. 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 JMSXDeliveryCount is not supported. Maximum Delivery Count can be enabled via management (see ) using the the queue declare property x-qpid-maximum-delivery-count or via configuration + linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration as illustrated below.
+
Dead Letter Queues (DLQ) 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. 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. + are named convention QueueName_DLE and QueueName_DLQ. DLQs can be enabled via management (see ) using the queue declare property x-qpid-dlq-enabled or via configuration + linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration as illustrated below. Avoid excessive queue depth @@ -96,6 +99,7 @@ depths should not be permitted to develop.
+
Configuration In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at -- cgit v1.2.1