Chapter 16. Configuring Message Expiry

Sent messages can be set to expire on the server if they are not delivered to a consumer after a specified amount of time. These expired messages can later be consumed for further inspection.

Set Message Expiry Using the Core API

Using the core API, you can set an expiration time on a message using the setExpiration method.

// The message will expire 5 seconds from now
message.setExpiration(System.currentTimeMillis() + 5000);

Set Message Expiry Using JMS

You can set the time to live for the JMS MessageProducer to use when sending messages. You specify this value, in milliseconds, using the setTimeToLive method.

// Messages sent by this producer will be retained for 5 seconds before expiring

You can also specify the message expiry on a per-message basis by setting the time to live on the producer’s send method.

// The last parameter of the send method is the time to live, in milliseconds
producer.send(message, DeliveryMode.PERSISTENT, 0, 5000)

Expired messages that are consumed from an expiry address have the following properties.


    A String property containing the original address of the expired message.


    A Long property containing the actual expiration time of the expired message.

16.1. Expiry Address

You can specify where to send expired messages by setting an expiry address. If a message expires and no expiry address is specified, the message is removed from the queue and dropped.

You can set an expiry-address for an address-setting using the management CLI. In the below example, expired messages in the jms.queue.exampleQueue queue will be sent to the jms.queue.expiryQueue expiry address.


16.2. Expiry Reaper Thread

A reaper thread periodically inspects the queues to check whether messages have expired. You can set the scan period and thread priority for the reaper thread using the management CLI.

Set the scan period for the expiry reaper thread, which is how often, in milliseconds, the queues will be scanned to detect expired messages. The default is 30000. You can set this to -1 to disable the reaper thread.


Set the thread priority for the expiry reaper thread. Possible values are from 0 to 9, with 9 being the highest priority. The default is 3.