[jboss-jira] [JBoss JIRA] Commented: (JBMESSAGING-1416) Provide complete message ordering

[Howard Gao (JIRA)]

    [ https://jira.jboss.org/jira/browse/JBMESSAGING-1416?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12450788#action_12450788 ] 

Howard Gao commented on JBMESSAGING-1416:
-----------------------------------------

Hi all, I write up this summary for this task, expecting your input. Thanks.



1 Strict Message Ordering in JBM 1.4

JBM 1.4'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. 

For CLIENT_ACKNOWLEDGE mode, the Message.acknowledge() method signals the completion state. 
For AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE modes, the completion of the message is identified by either 

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.

2 How to Enable Message Ordering Group

There are two ways to use message ordering group: through programming and through configuration.

2.1 The Programming Way.

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.

[code]public void enableOrderingGroup(String ogrpName) throws JMSException[/code]

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.

[code]public void disableOrderingGroup() throws JMSException[/code]

Stop producing ordering group messages. Once called, the producer will stop sending out ordering group messages and return to its normal behavior.

2.2 The Configuration Way

Users can configure a JBoss Messaging connection factory to enable ordering group. Two new attributes are added to the factory service configuration file

[code]
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.
[/code]

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:
[code]
   <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>
[/code]

The good thing about this way is the user doesn't need to make any coding effort to get message ordering functionality.

3 Notes and Limitations

* Ordering group doesn't work with topics. Users requiring order groups have to user queues.
* Ordering group shouldn't be used together with message selectors and scheduled delivery.
* If a message is 'dead' (goes to DLQ) or expired (goes to ExpiryQueue), this message is considered completed and next message will be available for delivery.
* When using a ConnectionConsumer, ordering of the messages will be observed. However, it doesn't control which session will be receiving the next message.
* In case of Distributed Queue, user should use HASingleton to make sure ordering group works properly.



> Provide complete message ordering
> ---------------------------------
>
>                 Key: JBMESSAGING-1416
>                 URL: https://jira.jboss.org/jira/browse/JBMESSAGING-1416
>             Project: JBoss Messaging
>          Issue Type: Feature Request
>            Reporter: Tim Fox
>            Assignee: Howard Gao
>             Fix For: 1.4.0.SP3.CP07
>
>
> As per customer request we would like to introduce new functionality over and above the JMS ordering guarantees.
> The idea is that the user should be able to determine an "ordering group". This can be done by setting a reserved property on the message before sending.
> The ordering group can be pinned to the producer or just be some other arbitrary string.
> In order to guarantee strict ordering, even on rollback or in the presence of multiple consumers or with xa transactions, the queue needs to ensure that no more than one message with the value of ordering group is being delivered at any one time.
> When that message has been acked, or cancelled the next one can be delivered.
> This is of course will provide a performance penalty since we won't be able to do consumer buffering, but that's the price you pay if you want such a strict ordering guarantee.
> We can subclass our MessageQueue class to do this. The sub-classed class can maintain a map of ordering group-->boolean. Which will determine whether the queue is currently delivering any messages with that ordering group value. It will consult that map when delivering to decide whether it can deliver the next message.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira