Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

Chapter 9. Enabling JBoss Messaging Ordering Group

This section describes how to use the JBoss Messaging ordering group feature to achieve strict message ordering.
Message ordering groups is the JBoss Messaging implementation of strict message ordering. When the ordering group feature is enabled, message priorities no longer have an influence on the order that the messages are delivered. Messages in a particular ordering group will be delivered in the exact order that they arrive at the target queue (FIFO).
Ordering groups are identified by their string names and obey the following rules:
Rule One

The messages that form a part of an ordering group are delivered one at a time. The next message will not be delivered until the delivery of a previous message is completed. Message delivery completion is signaled by various means, depending on the acknowledge mode settings;

  • The CLIENT_ACKNOWLEDGE mode results in the Message.acknowledge() method signaling the completion state.
  • The AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE modes result in the completion of the message being identified by either of the following;
    • a successful return from one of the MessageConsumer.receive() methods, or
    • a successful return from the onMessage() call of the MessageListener().

Note

If the message consumer is closed, the message being processed at the time of its closure will be deemed as completed. This is regardless of whether an *_ACKNOWLEGE is called prior to the closure of the consumer.
Rule Two

In the case of the transactional receipt of messages, the next message will not be delivered until the transaction has been committed which includes the acknowledgment of the receipt of the current message. If the transaction is rolled back, the message will be canceled, sent back to the JMS server and made available for the next delivery.

9.1. How to Enable Message Ordering Group

JBoss Messaging ordering group may be enabled by one of two means. Either using the API or by making configuration changes.

9.1.1. Enabling with the API

To make use of JBoss Messaging's ordering group feature, it is necessary to create a JBossMessageProducer as demonstrated in the following code sample: 
JBossMessageProducer producer=(JBossMessageProducer)session.createProducer(queue);
Once created, JBossMessageProducer provides two methods for starting and ending an ordering group.
enableOrderingGroup()

The following code sample demonstrates how to create an ordering group with the name ogrpName. 

 public void enableOrderingGroup(String ogrpName) throws JMSException
Once called, the producer will send messages on behalf of the ordering group. If a null parameter is supplied, the name of the ordering group will be automatically generated. Calling this method more than once will override any previous method calls.
disableOrderingGroup()

The following code samples demonstrates how to stop producing ordering group messages. 

public void disableOrderingGroup() throws JMSException
Once called, the producer will stop sending out ordering group messages and resume its default behavior.

9.1.2. Configuration Changes

Users can configure a JBoss Messaging connection factory to enable the ordering group feature. To achieve this, two new attributes are added to the factory service configuration file. These are:
  • EnableOrderingGroup;
    • set this property to true to enable the ordering group feature. The default value for this property is false.
  • DefaultOrderingGroupName;
    • the default name for the message ordering group. The group name will be generated automatically if this attribute is missing.

Note

Once configured to enable the ordering group feature on a connection factory, all messages that are sent from any producers created from the connection factory become ordering group messages.
The following factory service configuration file sample demonstrates how to enable the ordering group feature: 
<mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory";
  name="jboss.messaging.connectionfactory:service=ConnectionFactory";
  xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
  <depends optional-attribute-name="ServerPeer">
    jboss.messaging:service=ServerPeer
  </depends>
  <depends optional-attribute-name="Connector">
    jboss.messaging:service=Connector,transport=bisocket
  </depends>
  <depends>
    jboss.messaging:service=PostOffice
  </depends>

  <attribute name="JNDIBindings">
    <bindings>
    <binding>/MyConnectionFactory</binding>
    <binding>/XAConnectionFactory</binding>
    <binding>java:/MyConnectionFactory</binding>
    <binding>java:/XAConnectionFactory</binding>
    </bindings>
  </attribute>
    
  <!-- This are the two properties -->
  <attribute name="EnableOrderingGroup">true</attribute>
  <attribute name="DefaultOrderingGroupName">MyOrderingGroup</attribute>
</mbean>
The advantage of enabling the ordering group feature by making configuration changes is the ease with which message ordering functionality can be achieved without the need for code changes.