This section describes how to use JBoss Messaging ordering group feature to achieve strict message ordering.
JBoss Messaging's implementation of strict message ordering is called message ordering groups. Messages in one orddering group obey strict delivering order, which means that messages in an ordering group will be delivered exactly in the order of their arrival at the target queue (FIFO). Ordering groups are identified by their string names.
When ordering group is enabled, message priorities will not take any effect on the ordering of the messages. Message ordering groups obey the following rules:
Rule 1. Messages in the ordering group are delivered one at a time. Next message will not be delivered until the delivery of previous message is completed.
1) successful returning from the MessageConsumer.receive() methods, or
2) successful returning from the onMessage() call of the MessageListener();
If the message consumer is closed, the current message processing is deemed to be finished, even if the acknowledge is not called before consumer close.
Rule 2. In case of transactional receiving, the next message will not be delivered until the transaction that includes the receiving of the previous message has been committed. If the transaction is rolled back, the previous message will be cancelled back to the JMS server and thus available for the next delivery.
There are two ways to use message ordering group: through programming and through configuration.
To make use of JBoss Messaging's ordering group feature, one has to obtain a JBossMessageProducer.
JBossMessageProducer producer = (JBossMessageProducer)session.createProducer(queue);
JBossMessageProducer has two methods for starting/ending an ordering group.
public void enableOrderingGroup(String ogrpName) throws JMSException
Creating a ordering group with name ogrpName. Once called, the producer will send messages on behave of the ordering group. If null parameter is given, the name of the ordering group will be automatically generated. Calling this method more than once will always override the previous calls.
public void disableOrderingGroup() throws JMSException
Stop producing ordering group messages. Once called, the producer will stop sending out ordering group messages and return to its normal behavior.
Users can configure a JBoss Messaging connection factory to enable ordering group. Two new attributes are added to the factory service configuration file.
EnableOrderingGroup -- set this property to true to enable the ordering group. Default is false; and
DefaultOrderingGroupName -- the default name for the message ordering group. If absent, the group
name will be generated automatically.
Once configured to enable ordering group on a connection factory, all messages that are sent from any producers created from this connection factory become ordering group messages.
Example:
<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 good thing about this way is the user doesn't need to make any coding effort to get message ordering functionality.