NO-JIRA message grouping doc updates for formatting & clarify

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,15 +105,15 @@ 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]
 ----
 Queue queue = session.createQueue("my.destination.name?group-first-key=JMSXGroupFirstForConsumer");
 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,15 +156,15 @@ 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]
 ----
 Queue queue = session.createQueue("my.destination.name?group-rebalance=true&group-rebalance-pause-dispatch=true");
 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.