mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-07 02:29:08 +00:00
3a4b421d2e
Markdown, which is currently used for user-facing documentation, is good for a lot of things. However, it's not great for the kind of complex documentation we have and our need to produce both multi-page HTML and single-page PDF output via Maven. Markdown lacks features which would make the documentation easier to read, easier to navigate, and just look better overall. The current tool-chain uses honkit and a tool called Calibre. Honkit is written in TypeScript and is installed via NPM. Calibre is a native tool so it must be installed via an OS-specific package manager. All this complexity makes building, releasing, uploading, etc. a pain. AsciiDoc is relatively simple like Markdown, but it has more features for presentation and navigation not to mention Java-based Maven tooling to generate both HTML and PDF. Migrating will improve both the appearance of the documentation as well as the processes to generate and upload it. This commit contains the following changes: - Convert all the Markdown for the User Manual, Migration Guide, and Hacking guide to AsciiDoc via kramdown [1]. - Update the `artemis-website` build to use AsciiDoctor Maven tooling. - Update `RELEASING.md` with simplified instructions. - Update Hacking Guide with simplified instructions. - Use AsciiDoc link syntax in Artemis Maven doc plugin. - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking Guide. All docs will be HTML only except for the User Manual which will have PDF. - Move all docs up out of their respective "en" directory. This was a hold-over from when we had docs in different languages. - Migration & Hacking Guides are now single-page HTML since they are relatively short. - Refactor README.md to simplify and remove redundant content. Benefits of the change: - Much simplified tooling. No more NPM packages or native tools. - Auto-generated table of contents for every chapter. - Auto-generated anchor links for every sub-section. - Overall more appealing presentation. - All docs will use the ActiveMQ favicon. - No more manual line-wrapping! AsciiDoc recommends one sentence per line and paragraphs are separated by a blank line. - AsciiDoctor plugins for IDEA are quite good. - Resulting HTML is less than *half* of the previous size. All previous links/bookmarks should continue to work. [1] https://github.com/asciidoctor/kramdown-asciidoc
148 lines
5.7 KiB
Plaintext
148 lines
5.7 KiB
Plaintext
= Last-Value Queues
|
|
:idprefix:
|
|
:idseparator: -
|
|
|
|
Last-Value queues are special queues which discard any messages when a newer message with the same value for a well-defined Last-Value property is put in the queue.
|
|
In other words, a Last-Value queue only retains the last value.
|
|
|
|
A typical example for Last-Value queue is for stock prices, where you are only interested by the latest value for a particular stock.
|
|
|
|
Messages sent to an Last-Value queue without the specified property will be delivered as normal and will never be "replaced".
|
|
|
|
== Configuration
|
|
|
|
[discrete]
|
|
==== Last Value Key Configuration
|
|
|
|
Last-Value queues can be statically configured in broker.xml via the `last-value-key`
|
|
|
|
[,xml]
|
|
----
|
|
<address name="foo.bar">
|
|
<multicast>
|
|
<queue name="orders1" last-value-key="reuters_code" />
|
|
</multicast>
|
|
</address>
|
|
----
|
|
|
|
Specified on creating a queue by using the CORE api specifying the parameter `lastValue` to `true`.
|
|
|
|
Or on auto-create when using the JMS Client by using address parameters when creating the destination used by the consumer.
|
|
|
|
[,java]
|
|
----
|
|
Queue queue = session.createQueue("my.destination.name?last-value-key=reuters_code");
|
|
Topic topic = session.createTopic("my.destination.name?last-value-key=reuters_code");
|
|
----
|
|
|
|
Address wildcards can be used to configure Last-Value queues for a set of addresses (see xref:wildcard-syntax.adoc#wildcard-syntax[here]).
|
|
|
|
[,xml]
|
|
----
|
|
<address-setting match="lastValueQueue">
|
|
<default-last-value-key>reuters_code</default-last-value-key>
|
|
</address-setting>
|
|
----
|
|
|
|
By default, `default-last-value-key` is `null`.
|
|
|
|
[discrete]
|
|
==== Legacy Last Value Configuration
|
|
|
|
Last-Value queues can also just be configured via the `last-value` boolean property, doing so it will default the last-value-key to `_AMQ_LVQ_NAME`.
|
|
|
|
[,xml]
|
|
----
|
|
<address name="foo.bar">
|
|
<multicast>
|
|
<queue name="orders1" last-value="true" />
|
|
</multicast>
|
|
</address>
|
|
----
|
|
|
|
Specified on creating a queue by using the CORE api specifying the parameter `lastValue` to `true`.
|
|
|
|
Or on auto-create when using the JMS Client by using address parameters when creating the destination used by the consumer.
|
|
|
|
[,java]
|
|
----
|
|
Queue queue = session.createQueue("my.destination.name?last-value=true");
|
|
Topic topic = session.createTopic("my.destination.name?last-value=true");
|
|
----
|
|
|
|
Also the default for all queues under and address can be defaulted using the `address-setting` configuration:
|
|
|
|
[,xml]
|
|
----
|
|
<address-setting match="lastValueQueue">
|
|
<default-last-value-queue>true</default-last-value-queue>
|
|
</address-setting>
|
|
----
|
|
|
|
By default, `default-last-value-queue` is false.
|
|
|
|
Note that `address-setting` `last-value-queue` config is deprecated, please use `default-last-value-queue` instead.
|
|
|
|
== Last-Value Property
|
|
|
|
The property name used to identify the last value is configurable at the queue level mentioned above.
|
|
|
|
If using the legacy setting to configure an LVQ then the default property `"_AMQ_LVQ_NAME"` is used (or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API).
|
|
|
|
For example, using the sample configuration
|
|
|
|
[,xml]
|
|
----
|
|
<address name="foo.bar">
|
|
<multicast>
|
|
<queue name="orders1" last-value-key="reuters_code" />
|
|
</multicast>
|
|
</address>
|
|
----
|
|
|
|
if two messages with the same value for the Last-Value property are sent to a Last-Value queue, only the latest message will be kept in the queue:
|
|
|
|
[,java]
|
|
----
|
|
// send 1st message with Last-Value property `reuters_code` set to `VOD`
|
|
TextMessage message = session.createTextMessage("1st message with Last-Value property set");
|
|
message.setStringProperty("reuters_code", "VOD");
|
|
producer.send(message);
|
|
|
|
// send 2nd message with Last-Value property `reuters_code` set to `VOD`
|
|
message = session.createTextMessage("2nd message with Last-Value property set");
|
|
message.setStringProperty("reuters_code", "VOD");
|
|
producer.send(message);
|
|
|
|
...
|
|
|
|
// only the 2nd message will be received: it is the latest with
|
|
// the Last-Value property set
|
|
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
|
|
System.out.format("Received message: %s\n", messageReceived.getText());
|
|
----
|
|
|
|
== Forcing all consumers to be non-destructive
|
|
|
|
It's common to combine last-value queues with xref:non-destructive-queues.adoc#non-destructive-queues[non-destructive] semantics.
|
|
|
|
== Clustering
|
|
|
|
The fundamental ideas behind last-value queues and clustering are at odds with each other.
|
|
|
|
Clustering was designed as a way to increase message throughput through horizontal scaling.
|
|
The messages in a clustered queue can be spread across _all_ nodes in the cluster.
|
|
This allows clients to be distributed across the cluster to leverage the computing resources all the nodes rather than being bottlenecked on a single node.
|
|
|
|
However, if you wanted to use a last-value queue in a cluster then in order to enforce last-value semantics all messages would be required to go to a queue on a _single_ node.
|
|
This would effectively _nullify_ the benefits of clustering.
|
|
Also, the arrival of messages on and and redistribution of those messages from nodes other than the node where the last-value semantics would be enforced would almost certainly impact which message is considered "last."
|
|
|
|
For these reasons last-value queues are not supported in a traditional cluster.
|
|
However, it would be possible to use a xref:connection-routers.adoc#connection-routers[connection router] in front of a cluster (or even a set of non-clustered brokers) to ensure all clients which need to use the same last-value queue are directed to the same node.
|
|
See the xref:connection-routers.adoc#connection-routers[connection router] for more details on configuration, etc.
|
|
|
|
== Example
|
|
|
|
See the xref:examples.adoc#last-value-queue[last-value queue example] which shows how last value queues are configured and used with JMS.
|