Chapter 21. Message Expiry

Messages can be set with an optional time to live when sending them. Such messages will be retained in the messaging system until their time to live is reached.

JBoss Messaging'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 expired messages can later be consumed for further inspection.

21.1. Message Expiry

Using JBoss Messaging Core API, you can set an expiration time directly on the message:

// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);         

JMS MessageProducer allows to set a TimeToLive for the messages it sent:

// messages sent by this producer will be retained for 5s (5000ms) before expiration           

Expired messages which are consumed from an expiry address have the following properties:


    a String property containing the original destination of the expired message


    a Long property containing the actual expiration time of the expired message

21.2. Configuring Expiry Addresses

Expiry address are defined in the address-setting configuration:

<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
<address-setting match="jms.queue.exampleQueue">

If messages are expired and no expiry address is specified, messages are simply removed from the queue. Address wildcards can be used to configure expiry address for a set of addresses (see Chapter 11, Understanding the JBoss Messaging Wildcard Syntax).

21.3. Configuring The Expiry Reaper Thread

A reaper thread is periodically inspecting the queues to check if messages have expired.

The reaper thread can be configured with the following properties in jbm-configuration.xml

  • message-expiry-scan-period

    How often the queues will be scanned to detect expired messages (in milliseconds, default is 30000ms)

  • message-expiry-thread-priority

    The reaper thread priority (it must be between 0 and 9, 9 being the highest priority, default is 3)

21.4. Example

See Section 9.1.26, “Message Expiration” for an example which shows how message expiry is configured and used with JMS.