107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# Message Expiry
|
|
|
|
Messages can be set with an optional *time to live* when sending them.
|
|
|
|
Apache ActiveMQ Artemis 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.
|
|
|
|
Apache ActiveMQ Artemis's addresses can be assigned an 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.
|
|
|
|
## Core API
|
|
|
|
Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly
|
|
on the message:
|
|
|
|
```java
|
|
// message will expire in 5000ms from now
|
|
message.setExpiration(System.currentTimeMillis() + 5000);
|
|
```
|
|
|
|
JMS MessageProducer allows to set a TimeToLive for the messages it sent:
|
|
|
|
```java
|
|
// 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:
|
|
|
|
- `_AMQ_ORIG_ADDRESS`
|
|
|
|
a String property containing the *original address* of the expired
|
|
message
|
|
|
|
- `_AMQ_ORIG_QUEUE`
|
|
|
|
a String property containing the *original queue* of the expired
|
|
message
|
|
|
|
- `_AMQ_ACTUAL_EXPIRY`
|
|
|
|
a Long property containing the *actual expiration time* of the
|
|
expired message
|
|
|
|
## Configuring Expiry Delay
|
|
|
|
Default Expiry delay can be configured in the address-setting configuration:
|
|
|
|
```xml
|
|
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
|
|
<address-setting match="exampleQueue">
|
|
<expiry-delay>10</expiry-delay>
|
|
</address-setting>
|
|
```
|
|
|
|
`expiry-delay` defines the expiration time in milliseconds that will be used for messages
|
|
which are using the default expiration time (i.e. 0).
|
|
|
|
For example, if `expiry-delay` is set to "10" and a message which is using the default
|
|
expiration time (i.e.10) arrives then its expiration time of "0" will be changed to "10."
|
|
However, if a message which is using an expiration time of "20" arrives then its expiration
|
|
time will remain unchanged. Setting `expiry-delay` to "-1" will disable this feature.
|
|
|
|
The default is "-1".
|
|
|
|
## Configuring Expiry Addresses
|
|
|
|
Expiry address are defined in the address-setting configuration:
|
|
|
|
```xml
|
|
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
|
|
<address-setting match="exampleQueue">
|
|
<expiry-address>expiryQueue</expiry-address>
|
|
</address-setting>
|
|
```
|
|
|
|
If messages are expired and no expiry address is specified, messages are simply
|
|
removed from the queue and dropped. Address [wildcards](wildcard-syntax.md) can
|
|
be used to configure expiry address for a set of addresses.
|
|
|
|
## Configuring The Expiry Reaper Thread
|
|
|
|
A reaper thread will periodically inspect the queues to check if messages have
|
|
expired.
|
|
|
|
The reaper thread can be configured with the following properties in
|
|
`broker.xml`
|
|
|
|
- `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 1 and 10, 10 being the highest
|
|
priority, default is 3)
|
|
|
|
## Example
|
|
|
|
See the [Message Expiration Example](examples.md#message-expiration) which
|
|
shows how message expiry is configured and used with JMS.
|