You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by ma...@apache.org on 2026/07/23 17:37:25 UTC
(activemq-website) branch main updated: #2020 Add message expiry documentation and cross-links (#178)
This is an automated email from the ASF dual-hosted git repository.
mattrpav pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-website.git
The following commit(s) were added to refs/heads/main by this push:
new 7baccc25e #2020 Add message expiry documentation and cross-links (#178)
7baccc25e is described below
commit 7baccc25e0220938f254fdb1c0c952473af505a5
Author: mwashburn2 <13...@users.noreply.github.com>
AuthorDate: Thu Jul 23 13:37:20 2026 -0400
#2020 Add message expiry documentation and cross-links (#178)
* Add message expiry documentation and related links
* update variable name
---
.../how-do-i-set-the-message-expiration.md | 2 +
.../classic/documentation/message-expiry.md | 44 ++++++++++++++++++++++
.../classic/documentation/message-features.md | 1 +
src/components/classic/documentation/sitemap.md | 1 +
.../documentation/slow-consumer-handling.md | 11 +++++-
5 files changed, 58 insertions(+), 1 deletion(-)
diff --git a/src/components/classic/documentation/how-do-i-set-the-message-expiration.md b/src/components/classic/documentation/how-do-i-set-the-message-expiration.md
index 205562805..0baeb7eac 100644
--- a/src/components/classic/documentation/how-do-i-set-the-message-expiration.md
+++ b/src/components/classic/documentation/how-do-i-set-the-message-expiration.md
@@ -13,3 +13,5 @@ JMSExpiration on a message is set by the MessageProducer in JMS - either via
* [producer.setTimeToLive()](http://java.sun.com/j2ee/1.4/docs/api/javax/jms/MessageProducer.html#setTimeToLive(long))
* [producer.send(Destination, Message, int, int, long)](http://java.sun.com/j2ee/1.4/docs/api/javax/jms/MessageProducer.html#send(javax.jms.Destination,%20javax.jms.Message,%20int,%20int,%20long))
+For the end-to-end view of how TTL becomes `JMSExpiration`, how the broker enforces expiry, and why clock synchronization matters, see [Message Expiry](message-expiry).
+
diff --git a/src/components/classic/documentation/message-expiry.md b/src/components/classic/documentation/message-expiry.md
new file mode 100644
index 000000000..2f46a03d9
--- /dev/null
+++ b/src/components/classic/documentation/message-expiry.md
@@ -0,0 +1,44 @@
+---
+layout: default_md
+title: Message Expiry
+title-class: page-title-classic
+type: classic
+---
+
+[Features](features) > [Message Features](message-features) > [Message Expiry](message-expiry)
+
+
+Apache ActiveMQ Classic handles message expiry in two parts:
+
+1. **The client sets the expiration time when it sends the message.**
+2. **The broker checks that expiration time and discards expired messages.**
+
+When a JMS producer sets a time-to-live (TTL), ActiveMQ Classic converts that TTL into an absolute `JMSExpiration` value when the message is sent. A TTL of `0` means the message never expires.
+
+At the broker, expired messages can be removed in several places, including when a message arrives, while messages are being held for dispatch, and during periodic destination scans. Consumers may also filter expired messages before delivery.
+
+## Client-side expiry
+
+In JMS, message expiration is controlled by the producer:
+
+* [`MessageProducer.setTimeToLive(long)`](how-do-i-set-the-message-expiration)
+* [`MessageProducer.send(...)`](how-do-i-set-the-message-expiration)
+
+ActiveMQ Classic stores the TTL as an absolute expiration timestamp on the message. That timestamp is based on the sending machine's clock.
+
+## Broker-side expiry
+
+The broker checks the stored expiration timestamp against its own clock and removes expired messages as they are encountered. Because of that, expiry is not purely a client-side concept: the broker still has to enforce it.
+
+For that reason, the clocks on all machines involved — producers, brokers, and consumers — should be kept in sync. If the machines are not time-synchronized, a message may appear to expire early or late depending on which clock is ahead.
+
+## Consumer expiry checks
+
+The ActiveMQ Classic client also performs expiry checks before delivering messages to application code. This helps prevent expired messages from being consumed accidentally.
+
+## Related documentation
+
+* [How do I set the message expiration](how-do-i-set-the-message-expiration)
+* [Message Redelivery and DLQ Handling](message-redelivery-and-dlq-handling)
+* [Slow Consumer Handling](slow-consumer-handling)
+
diff --git a/src/components/classic/documentation/message-features.md b/src/components/classic/documentation/message-features.md
index 6015f404c..bc05d34cb 100644
--- a/src/components/classic/documentation/message-features.md
+++ b/src/components/classic/documentation/message-features.md
@@ -12,6 +12,7 @@ type: classic
* [Advisory Message](advisory-message)
* [Blob Messages](blob-messages)
* [Delay and Schedule Message Delivery](delay-and-schedule-message-delivery)
+* [Message Expiry](message-expiry)
* [JMS Streams](jms-streams)
* [Message Transformation](message-transformation)
* [ObjectMessage](objectmessage)
diff --git a/src/components/classic/documentation/sitemap.md b/src/components/classic/documentation/sitemap.md
index 08bdcb783..8b51f39da 100644
--- a/src/components/classic/documentation/sitemap.md
+++ b/src/components/classic/documentation/sitemap.md
@@ -317,6 +317,7 @@ Features
* [Advisory Message](advisory-message)
* [Blob Messages](blob-messages)
* [Delay and Schedule Message Delivery](delay-and-schedule-message-delivery)
+ * [Message Expiry](message-expiry)
* [JMS Streams](jms-streams)
* [Message Transformation](message-transformation)
* [ObjectMessage](objectmessage)
diff --git a/src/components/classic/documentation/slow-consumer-handling.md b/src/components/classic/documentation/slow-consumer-handling.md
index 291591acf..d7c7f0a2b 100644
--- a/src/components/classic/documentation/slow-consumer-handling.md
+++ b/src/components/classic/documentation/slow-consumer-handling.md
@@ -54,6 +54,16 @@ We have a `MessageEvictionStrategy` which is used to decide which message shoul
<oldestMessageEvictionStrategy/>
```
+By default, ActiveMQ will frist remove any expired messages from the slow-consumer pending buffer before evicting non-expired messages.
+
+If your messages do not use TTL or you do not want this behavior you can disable it with `expiryCheckEnabled="false"`:
+
+```
+<oldestMessageEvictionStrategy expiryCheckEnabled="false"/>
+```
+
+Messages will still be subject to expiry checks on the client. For the full client/broker expiry flow and the clock synchronization caveat, see [Message Expiry](message-expiry). The default is `expiryCheckEnabled="true"`.
+
However, you can write your own to use some application specific way of choosing messages for eviction. For example, if you are sending market data price updates you may wish to find an older price value, which might not be the oldest message.
Example:
@@ -140,4 +150,3 @@ Statistic|Definition
---|---
`discarded`|The count of how many messages have been discarded during the lifetime of the subscription due to it being a slow consumer
`matched`|The current number of messages matched and to be dispatched to the subscription as soon as some capacity is available in the prefetch buffer. So a non-zero value implies that the prefetch buffer is full for this subscription
-
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@activemq.apache.org
For additional commands, e-mail: commits-help@activemq.apache.org
For further information, visit: https://activemq.apache.org/contact