This is an automated email from the ASF dual-hosted git repository.
jbertram pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
The following commit(s) were added to refs/heads/main by this push:
new 5e51233df3 NO-JIRA message grouping doc updates for formatting &
clarify
5e51233df3 is described below
commit 5e51233df3548177d84fdd394d70946f7c72b372
Author: Justin Bertram <jbert...@apache.org>
AuthorDate: Tue Nov 14 14:21:51 2023 -0600
NO-JIRA message grouping doc updates for formatting & clarify
---
docs/user-manual/message-grouping.adoc | 61 ++++++++++++++++------------------
1 file changed, 28 insertions(+), 33 deletions(-)
diff --git a/docs/user-manual/message-grouping.adoc
b/docs/user-manual/message-grouping.adoc
index 1bb97f8ef7..b09055d0b7 100644
--- a/docs/user-manual/message-grouping.adoc
+++ b/docs/user-manual/message-grouping.adoc
@@ -19,8 +19,6 @@ This will ensure that all messages for a particular stock
will always be process
[NOTE]
====
-
-
Grouped messages can impact the concurrent processing of non-grouped messages
due to the underlying FIFO semantics of a queue.
For example, if there is a chunk of 100 grouped messages at the head of a
queue followed by 1,000 non-grouped messages then all the grouped messages will
need to be sent to the appropriate client (which is consuming those grouped
messages serially) before any of the non-grouped messages can be consumed.
The functional impact in this scenario is a temporary suspension of concurrent
message processing while all the grouped messages are processed.
@@ -70,12 +68,10 @@
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialCont
connectionFactory.myConnectionFactory=tcp://localhost:61616?groupID=Group-0
----
-[discrete]
-==== Closing a Message Group
+== Closing a Message Group
You generally don't need to close a message group, you just keep using it.
-
-However if you really do want to close a group you can add a negative sequence
number.
+However, if you really do want to close a group you can add a negative
sequence number.
Example:
@@ -88,18 +84,17 @@ message.setIntProperty("JMSXGroupSeq", -1);
producer.send(message);
----
-This then closes the message group so if another message is sent in the future
with the same message group ID it will be reassigned to a new consumer.
+This closes the message group so if another message is sent in the future with
the same message group ID it will be reassigned to a new consumer.
-[discrete]
-==== Notifying Consumer of Group Ownership change
+== Notifying Consumer of Group Ownership change
-ActiveMQ supports putting a boolean header, set on the first message sent to a
consumer for a particular message group.
+ActiveMQ supports putting a boolean header on the first message sent to a
consumer for a particular message group.
-To enable this, you must set a header key that the broker will use to set the
flag.
+To enable this you must set a header key that the broker will use to set the
flag.
In the examples we use `JMSXGroupFirstForConsumer` but it can be any header
key value you want.
-By setting `group-first-key` to `JMSXGroupFirstForConsumer` at the queue
level, every time a new group is assigned a consumer the header
`JMSXGroupFirstForConsumer` will be set to true on the first message.
+By setting `group-first-key` to `JMSXGroupFirstForConsumer` at the queue
level, every time a new group is assigned a consumer the header
`JMSXGroupFirstForConsumer` will be set to `true` on the first message.
[,xml]
----
@@ -110,7 +105,7 @@ By setting `group-first-key` to `JMSXGroupFirstForConsumer`
at the queue level,
</address>
----
-Or on auto-create when using the JMS Client by using address parameters when
creating the destination used by the consumer.
+Or on auto-create when using the core JMS client by using address parameters
when creating the destination used by the consumer.
[,java]
----
@@ -118,7 +113,7 @@ Queue queue =
session.createQueue("my.destination.name?group-first-key=JMSXGroup
Topic topic =
session.createTopic("my.destination.name?group-first-key=JMSXGroupFirstForConsumer");
----
-Also the default for all queues under and address can be defaulted using the
`address-setting` configuration:
+Also, the default for all queues under and address can be defaulted using the
`address-setting` configuration:
[,xml]
----
@@ -127,29 +122,30 @@ Also the default for all queues under and address can be
defaulted using the `a
</address-setting>
----
-By default this is null, and therefor OFF.
-
-[discrete]
-==== Rebalancing Message Groups
+By default, this is off.
-Sometimes after new consumers are added you can find that if you have long
lived groups, that they have no groups assigned, and thus are not being
utilised, this is because the long lived groups will already be assigned to
existing consumers.
+== Rebalancing Message Groups
-It is possibly to rebalance the groups.
+Sometimes after new consumers are added you can find that they have no groups
assigned, and thus are not being utilised.
+This is because all the groups are already assigned to existing consumers.
+However, it is possible to rebalance the groups so that all the consumers are
the queue are assigned one or more groups.
-*_note_* during the split moment of reset, a message to the original
associated consumer could be in flight at the same time, a new message for the
same group is dispatched to the new associated consumer.
+[NOTE]
+====
+At the exact moment of a reset a message to the originally associated consumer
could be in flight at the same time a new message for the same group is
dispatched to the new associated consumer.
+====
-[discrete]
-===== Manually
+=== Manually
-via the management API or managment console by invoking `resetAllGroups`
+Use the management API (e.g via the web console) by invoking `resetAllGroups`
on the associated queue.
-[discrete]
-===== Automatically
+=== Automatically
-By setting `group-rebalance` to `true` at the queue level, every time a
consumer is added it will trigger a rebalance/reset of the groups.
+By setting `group-rebalance` to `true` at the queue level every time a
consumer is added it will trigger a rebalance/reset of the groups.
-As noted above, when group rebalance is done, there is a risk you may have
inflight messages being processed, by default the broker will continue to
dispatch whilst rebalance is occuring.
-To ensure that inflight messages are processed before dispatch of new messages
post rebalance, to different consumers, you can set
`group-rebalance-pause-dispatch` to `true` which will cause the dispatch to
pause whilst rebalance occurs, until all inflight messages are processed.
+As noted above, when group rebalance is done there is a risk you may have
inflight messages being processed.
+By default, the broker will continue to dispatch whilst rebalance is occuring.
+To ensure that inflight messages are processed before dispatch of new messages
post rebalance, to different consumers, you can set
`group-rebalance-pause-dispatch` to `true` which will cause the dispatch to
pause whilst rebalance occurs until all inflight messages are processed.
[,xml]
----
@@ -160,7 +156,7 @@ To ensure that inflight messages are processed before
dispatch of new messages p
</address>
----
-Or on auto-create when using the JMS Client by using address parameters when
creating the destination used by the consumer.
+Or on auto-create when using the core JMS client by using address parameters
when creating the destination used by the consumer.
[,java]
----
@@ -168,7 +164,7 @@ Queue queue =
session.createQueue("my.destination.name?group-rebalance=true&grou
Topic topic =
session.createTopic("my.destination.name?group-rebalance=true&group-rebalance-pause-dispatch=true");
----
-Also the default for all queues under and address can be defaulted using the
`address-setting` configuration:
+Also, the default for all queues under and address can be defaulted using the
`address-setting` configuration:
[,xml]
----
@@ -181,8 +177,7 @@ Also the default for all queues under and address can be
defaulted using the `a
By default, `default-group-rebalance` is `false` meaning this is disabled/off.
By default, `default-group-rebalance-pause-dispatch` is `false` meaning this
is disabled/off.
-[discrete]
-==== Group Buckets
+== Group Buckets
For handling groups in a queue with bounded memory allowing better scaling of
groups, you can enable group buckets, essentially the group id is hashed into
a bucket instead of keeping track of every single group id.
