[jboss-cvs] JBoss Messaging SVN: r6891 - in branches/Branch_1_4/docs/userguide/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 19 10:59:29 EDT 2009
Author: gaohoward
Date: 2009-05-19 10:59:28 -0400 (Tue, 19 May 2009)
New Revision: 6891
Added:
branches/Branch_1_4/docs/userguide/en/modules/ordering_group.xml
Modified:
branches/Branch_1_4/docs/userguide/en/master.xml
branches/Branch_1_4/docs/userguide/en/modules/installation.xml
branches/Branch_1_4/docs/userguide/en/modules/runningexamples.xml
Log:
added ordering-group chapter
Modified: branches/Branch_1_4/docs/userguide/en/master.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/master.xml 2009-05-19 14:53:24 UTC (rev 6890)
+++ branches/Branch_1_4/docs/userguide/en/master.xml 2009-05-19 14:59:28 UTC (rev 6891)
@@ -10,6 +10,7 @@
<!ENTITY c_configuration SYSTEM "modules/c_configuration.xml">
<!ENTITY recovery_config SYSTEM "modules/recovery_config.xml">
<!ENTITY bridge SYSTEM "modules/bridge.xml">
+<!ENTITY ordering_group SYSTEM "modules/ordering_group.xml">
]>
<book lang="en">
<bookinfo>
@@ -39,5 +40,5 @@
&bridge;
-
+ &ordering_group;
</book>
Modified: branches/Branch_1_4/docs/userguide/en/modules/installation.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/installation.xml 2009-05-19 14:53:24 UTC (rev 6890)
+++ branches/Branch_1_4/docs/userguide/en/modules/installation.xml 2009-05-19 14:59:28 UTC (rev 6891)
@@ -613,10 +613,10 @@
<listitem>
<para>
<note>
- JBoss Messaging 1.4.0.GA requires pecific versions
- of jboss-remoting.jar if used outside of JBoss 5. If you are installing JBoss Messaging 1.4.3.GA at JBoss 4.2+, you should use this version:
- <ulink url="http://repository.jboss.com/jboss/remoting/2.5.0.SP2/ ">Remoting 2.5.0.SP2</ulink>.
- If you are using JBoss5 you don't need to take any extra steps on the remoting installation.
+ JBoss Messaging 1.4.0 requires pecific versions
+ of jboss-remoting.jar if used outside of JBoss EAP 4.3. If you are installing JBoss Messaging with JBoss 4.2+, you should use this version:
+ <ulink url="http://repository.jboss.com/jboss/remoting/2.2.3/ ">Remoting 2.2.3</ulink>.
+ If you are using EAP you don't need to take any extra steps on the remoting installation.
</note>
</para>
</listitem>
@@ -915,13 +915,13 @@
<itemizedlist>
<listitem>
<para><note>
- This version of JBoss Messaging requires JBoss Remoting 2.2.2.SP12.
+ This version of JBoss Messaging requires JBoss Remoting 2.2.3.
If you are using EAP 4.3 you will have the required JAR available already.
Always use the version of JBoss Remoting that comes with the EAP 4.3.
If you're using a different version of Application Server you should download it.
The patched jar can be found at here
- [http://repository.jboss.com/jboss/remoting/2.2.2.SP12-brew/lib/].
+ [http://repository.jboss.com/jboss/remoting/2.2.3-brew/lib/].
Please download it and make sure this jar is on your classpath *before* jbossall-client.jar.
</note></para>
Added: branches/Branch_1_4/docs/userguide/en/modules/ordering_group.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/ordering_group.xml (rev 0)
+++ branches/Branch_1_4/docs/userguide/en/modules/ordering_group.xml 2009-05-19 14:59:28 UTC (rev 6891)
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ordering-group">
+ <title>Enabling JBoss Messaging Ordering Group</title>
+
+ <para>This section describes how to use JBoss Messaging ordering group feature to achieve strict message ordering.
+ </para>
+
+ <para>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.</para>
+
+ <para>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:</para>
+
+ <para>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.</para>
+
+ <itemizedlist>
+ <listitem>For CLIENT_ACKNOWLEDGE mode, the Message.acknowledge() method signals the completion state.</listitem>
+ <listitem>For AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE modes, the completion of the message is identified by either.
+
+ <para>1) successful returning from the MessageConsumer.receive() methods, or</para>
+ <para>2) successful returning from the onMessage() call of the MessageListener();</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>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.</para>
+
+ <para>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.
+</para>
+
+<section id="enable.ordering.group">
+ <title>How to Enable Message Ordering Group</title>
+
+<para>There are two ways to use message ordering group: through programming and through configuration.</para>
+
+ <itemizedlist>
+<listitem>The Programming Way</listitem>
+ </itemizedlist>
+
+<para>To make use of JBoss Messaging's ordering group feature, one has to obtain a JBossMessageProducer.</para>
+
+ <programlisting>
+ JBossMessageProducer producer = (JBossMessageProducer)session.createProducer(queue);
+ </programlisting>
+
+<para>JBossMessageProducer has two methods for starting/ending an ordering group.</para>
+
+ <programlisting>
+public void enableOrderingGroup(String ogrpName) throws JMSException
+ </programlisting>
+
+<para>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.</para>
+
+ <programlisting>
+public void disableOrderingGroup() throws JMSException
+ </programlisting>
+
+<para>Stop producing ordering group messages. Once called, the producer will stop sending out ordering group messages and return to its normal behavior.</para>
+
+ <itemizedlist>
+<listitem>The Configuration Way</listitem>
+ </itemizedlist>
+
+<para>Users can configure a JBoss Messaging connection factory to enable ordering group. Two new attributes are added to the factory service configuration file.</para>
+
+ <programlisting>
+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.
+ </programlisting>
+
+<para>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.</para>
+
+<para>Example:</para>
+
+ <programlisting>
+ <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>
+ </programlisting>
+
+<para>The good thing about this way is the user doesn't need to make any coding effort to get message ordering functionality.</para>
+
+</section>
+
+<section id="note.ordering.group">
+ <title>Notes and Limitations</title>
+
+ <itemizedlist>
+
+<listitem>Ordering group doesn't work with topics. Users requiring order groups have to user queues.</listitem>
+<listitem>Ordering group shouldn't be used together with message selectors and scheduled delivery.</listitem>
+<listitem>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.</listitem>
+<listitem>When using a ConnectionConsumer, ordering of the messages will be observed. However, it doesn't control which session will be receiving the next message.</listitem>
+<listitem>In case of Distributed Queue, user should use HASingleton to make sure ordering group works properly.</listitem>
+ </itemizedlist>
+
+</section>
+
+</chapter>
Modified: branches/Branch_1_4/docs/userguide/en/modules/runningexamples.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/runningexamples.xml 2009-05-19 14:53:24 UTC (rev 6890)
+++ branches/Branch_1_4/docs/userguide/en/modules/runningexamples.xml 2009-05-19 14:59:28 UTC (rev 6891)
@@ -104,6 +104,22 @@
message bridge in JBoss AS which then proceeds to move messages from a
source to a target queue</para>
</listitem>
+
+ <listitem>
+ <para>docs/example/servlet</para>
+
+ <para>This example demonstrates how to use servlet transport with JBoss Messaging.
+ It deploys a servlet and a ConnectionFactory that uses the servlet transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>docs/example/ordering-group</para>
+
+ <para>This example demonstrates using strict message ordering with JBoss Messaging.
+ It uses JBoss Messaging ordering group API to deliver strictly ordered messages, regardless of
+ their priorities.</para>
+ </listitem>
</itemizedlist></para>
<para>It is highly recommended that you familiarise yourself with the
@@ -122,4 +138,4 @@
ports settings as per ports-01 and ports-02. For each example, you can
always override the default ports it will try to connect to by editing
jndi.properties in the particular example directory</para>
-</chapter>
\ No newline at end of file
+</chapter>
More information about the jboss-cvs-commits
mailing list