102 lines
5.7 KiB
XML
102 lines
5.7 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="message-expiry">
|
||
<title>Message Expiry</title>
|
||
<para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending
|
||
them.</para>
|
||
<para>HornetQ will not deliver a message to a consumer after it's time to live has been exceeded.
|
||
If the message hasn't been delivered by the time that time to live is reached the server can
|
||
discard it.</para>
|
||
<para>HornetQ's addresses can be assigned a expiry address so that, when messages are expired,
|
||
they are removed from the queue and sent to the expiry address. Many different queues can be
|
||
bound to an expiry address. These <emphasis>expired</emphasis> messages can later be consumed
|
||
for further inspection.</para>
|
||
<section>
|
||
<title>Message Expiry</title>
|
||
<para>Using HornetQ Core API, you can set an expiration time directly on the message:</para>
|
||
<programlisting>
|
||
// message will expire in 5000ms from now
|
||
message.setExpiration(System.currentTimeMillis() + 5000);</programlisting>
|
||
<para>JMS MessageProducer allows to set a TimeToLive for the messages it sent:</para>
|
||
<programlisting>
|
||
// messages sent by this producer will be retained for 5s (5000ms) before expiration
|
||
producer.setTimeToLive(5000);</programlisting>
|
||
<para>Expired messages which are consumed from an expiry 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
|
||
expired message </para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>_HQ_ORIG_QUEUE</literal></para>
|
||
<para>a String property containing the <emphasis>original queue</emphasis> of the
|
||
expired message </para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>_HQ_ACTUAL_EXPIRY</literal></para>
|
||
<para>a Long property containing the <emphasis>actual expiration time</emphasis> of the
|
||
expired message</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section id="message-expiry.configuring">
|
||
<title>Configuring Expiry Addresses</title>
|
||
<para>Expiry address are defined in the address-setting configuration:</para>
|
||
<programlisting>
|
||
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
|
||
<address-setting match="jms.queue.exampleQueue">
|
||
<expiry-address>jms.queue.expiryQueue</expiry-address>
|
||
</address-setting></programlisting>
|
||
<para>If messages are expired and no expiry address is specified, messages are simply removed
|
||
from the queue and dropped. Address wildcards can be used to configure expiry address for a
|
||
set of addresses (see <xref linkend="wildcard-syntax"/>).</para>
|
||
</section>
|
||
<section id="configuring.expiry.reaper">
|
||
<title>Configuring The Expiry Reaper Thread</title>
|
||
<para>A reaper thread will periodically inspect the queues to check if messages have
|
||
expired.</para>
|
||
<para>The reaper thread can be configured with the following properties in <literal
|
||
>hornetq-configuration.xml</literal></para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>message-expiry-scan-period</literal></para>
|
||
<para>How often the queues will be scanned to detect expired messages (in milliseconds,
|
||
default is 30000ms, set to <literal>-1</literal> to disable the reaper thread)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>message-expiry-thread-priority</literal></para>
|
||
<para>The reaper thread priority (it must be between 0 and 9, 9 being the highest
|
||
priority, default is 3)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section>
|
||
<title>Example</title>
|
||
<para>See <xref linkend="examples.expiry"/> for an example which shows how message expiry is
|
||
configured and used with JMS.</para>
|
||
</section>
|
||
</chapter>
|