20.8.11. Set Message Expiry

Introduction

Sent messages can be set to expire on server if they're not delivered to consumer after specified amount of time (milliseconds). Using Java Messaging Service (JMS) or HornetQ Core API, the expiration time can be set directly on the message. For example:

// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
JMS MessageProducer includes a TimeToLive parameter which controls message expiry for the messages it sends:
// messages sent by this producer will be retained for 5s (5000ms) before expiration           
producer.setTimeToLive(5000);
Expired messages which are consumed from an expiry address have the following properties:
  • _HQ_ORIG_ADDRESS
A string property containing the original address of the expired message.
  • _HQ_ACTUAL_EXPIRY
A long property containing the actual expiration time of the expired message.
Besides setting the time-to-live parameter on the JMS producer, you can also set it on a per-message basis. You can achieve this by adding TTL parameter to producer's send method when sending the message.
producer.send(message, DeliveryMode.PERSISTENT, 0, 5000)
Where, the last parameter is message specific TTL.
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">
   <expiry-address>jms.queue.expiryQueue</expiry-address>
</address-setting>
If the messages are expired and no expiry address is specified, the messages are removed from the queue and dropped.
Configuring Expiry Reaper Thread

A reaper thread periodically inspects the queues to validate if messages have expired.

  • message-expiry-scan-period
How often the queues will be scanned to detect expired messages (in milliseconds, default is 30000ms, set to -1 to disable the reaper thread).
  • message-expiry-thread-priority
The reaper thread priority. It must be between 0 and 9, 9 being the highest priority, default is 3.