From a2e63a4dc8e96cec80a77a494fa6c81564ff7d23 Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Sat, 22 Dec 2012 23:57:01 +0000 Subject: QPID-4502: [Java Broker] Document DLQ/Maximum Delivery Count features git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1425377 13f79535-47bb-0310-9956-ffa450edef68 --- ...ker-Runtime-Handling-Undeliverable-Messages.xml | 165 +++++++++++++++++++++ .../book/src/java-broker/Java-Broker-Runtime.xml | 1 + .../test/unit/client/MaxDeliveryCountTest.java | 6 +- 3 files changed, 170 insertions(+), 2 deletions(-) create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml new file mode 100644 index 0000000000..250fbd4a59 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml @@ -0,0 +1,165 @@ + + +%entities; +]> + + +
+ Handing Undeliverable Messages + +
+ 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. + 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 + 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 + described in the following sections. +
+
+ Maximum Delivery Count + Maximum delivery count is a property of a queue. If a consumer application is unable to + process a message more than the specified number of times, then the broker will either route the + message to a dead-letter queue (if one has been defined), or will discard the message. + 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 + 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 + message will not be re-routed and consumer application will see the same poison message again + once it reconnects. + If the consuming application is using AMQP 0-9-1, 0-9, or 0-8 protocols, it is necessary to + 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. + 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 + as illustrated below. +
+
+ Dead Letter Queues (DLQ) + A Dead Letter Queue (DLQ) acts as an destination for messages that have somehow exceeded the + normal bounds of processing and is utilised to prevent disruption to flow of other messages. When + a DLQ is enabled for a given queue if a consuming client indicates it no longer wishes the + 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. + DLQs can be enabled via management (see ) using the queue declare property x-qpid-dlq-enabled or via configuration + as illustrated below. + + Avoid excessive queue depth + Applications making use of DLQs should make provision for the frequent + examination of messages arriving on DLQs so that both corrective actions can be taken to resolve + the underlying cause and organise for their timely removal from the DLQ. Messages on DLQs + consume system resources in the same manner as messages on normal queues so excessive queue + depths should not be permitted to develop. + +
+
+ Configuration + In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at + the broker level with maximum delivery count set to 5, disabled at the virtualhost level for the + 'dev-only' virtualhost, and enabled specifically for the 'dev-only-main-queue' with maximum + delivery count overridden to 5. + As 'dev-only-main-queue' has its own configuration specified, this value overrides all + others and causes the features to be enabled for this queue. In contrast to this, + 'dev-only-other-queue' does not specify its own value and picks up the false value specified for + its parent virtualhost, causing the DLQ/Maximum Delivery Count features to be disabled for this + queue. Any such queue in the 'dev-only' virtualhost which does not specify its own configuration + value will have the DLQ/Maximum Delivery Count feature disabled. + The queue 'localhost-queue' has the DLQ/Maximum Delivery Count features enabled, as neither + the queue itself or the 'localhost' virtualhost specifies a configuration value and so the broker + level value of true is used. Any such queue in the 'localhost' virtualhost which does not specify + its own configuration value will have the features enabled. + + Enabling DLQs and maximum delivery count at broker level within config.xml + + ... + true + 5 + ... +]]> + + + Enabling DLQs and maximum delivery count at virtualhost and queue level within + virtualhosts.xml + + ... + + dev-only + + + false + 0 + + dev-only-main-queue + + true + 3 + + + + dev-only-other-queue + + + + + + localhost + + + + localhost-queue + + + + + ... +]]> + + +
+ + +
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml index 6b21fd15c2..2af775d2fc 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml @@ -26,4 +26,5 @@ + diff --git a/qpid/java/systests/src/main/java/org/apache/qpid/test/unit/client/MaxDeliveryCountTest.java b/qpid/java/systests/src/main/java/org/apache/qpid/test/unit/client/MaxDeliveryCountTest.java index bc1eead8b4..8c407d3def 100644 --- a/qpid/java/systests/src/main/java/org/apache/qpid/test/unit/client/MaxDeliveryCountTest.java +++ b/qpid/java/systests/src/main/java/org/apache/qpid/test/unit/client/MaxDeliveryCountTest.java @@ -85,8 +85,10 @@ public class MaxDeliveryCountTest extends QpidBrokerTestCase // Set client-side flag to allow the server to determine if messages // dead-lettered or requeued. - setTestClientSystemProperty(ClientProperties.REJECT_BEHAVIOUR_PROP_NAME, "server"); - + if (!isBroker010()) + { + setTestClientSystemProperty(ClientProperties.REJECT_BEHAVIOUR_PROP_NAME, "server"); + } super.setUp(); boolean durableSub = isDurSubTest(); -- cgit v1.2.1