161 lines
10 KiB
XML
161 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<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>
|
||
<listitem>
|
||
<para>Delayed redelivery.</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>Dead Letter Address.</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>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 id="undelivered-messages.delay">
|
||
<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">
|
||
<!-- default is 1.0 -->
|
||
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
|
||
<!-- default is 0 (no delay) -->
|
||
<redelivery-delay>5000</redelivery-delay>
|
||
<!-- default is redelivery-delay * 10 -->
|
||
<max-redelivery-delay>50000</max-redelivery-delay>
|
||
|
||
</address-setting></programlisting>
|
||
<para>If a <literal>redelivery-delay</literal> is specified, HornetQ 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>Other subsequent messages will be delivery regularly, only the cancelled message
|
||
will be sent asynchronously back to the queue after the delay.</para>
|
||
<para>You can specify a multiplier that will take effect on top of the redelivery-delay
|
||
with a max-redelivery-delay to be taken into account.</para>
|
||
<para>The max-redelivery-delay is defaulted to redelivery-delay * 10</para>
|
||
<para>Address wildcards can be used to configure redelivery delay for a set of addresses
|
||
(see <xref linkend="wildcard-syntax"/>), so you don't have to specify redelivery delay
|
||
individually for each address.</para>
|
||
</section>
|
||
<section>
|
||
<title>Example</title>
|
||
<para>See <xref linkend="examples.delayed-redelivery"/> for an example which shows how
|
||
delayed redelivery is configured and used with JMS.</para>
|
||
</section>
|
||
</section>
|
||
<section>
|
||
<title>Dead Letter Addresses</title>
|
||
<para>To prevent a client infinitely receiving the same undelivered message (regardless of
|
||
what is causing the unsuccessful deliveries), messaging systems define <emphasis
|
||
role="italic">dead letter addresses</emphasis>: after a specified unsuccessful delivery
|
||
attempts, the message is removed from the queue and send instead to a dead letter address. </para>
|
||
<para>Any such messages can then be diverted to queue(s) where they can later be perused by
|
||
the system administrator for action to be taken.</para>
|
||
<para>HornetQ's addresses can be assigned a dead letter address. Once the messages have been
|
||
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 id="undelivered-messages.configuring">
|
||
<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
|
||
properties:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>_HQ_ORIG_ADDRESS</literal></para>
|
||
<para>a String property containing the <emphasis>original address</emphasis> of
|
||
the dead letter message</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>_HQ_ORIG_QUEUE</literal></para>
|
||
<para>a String property containing the <emphasis>original queue</emphasis> of
|
||
the dead letter message</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section>
|
||
<title>Example</title>
|
||
<para>See <xref linkend="examples.dead-letter"/> for an example which 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, HornetQ 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, HornetQ 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>hornetq-configuration.xml</literal>:</para>
|
||
<programlisting>
|
||
<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery></programlisting>
|
||
</section>
|
||
</chapter>
|