[jboss-cvs] JBossAS SVN: r95013 - projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Oct 16 04:20:06 EDT 2009
Author: benlc
Date: 2009-10-16 04:20:06 -0400 (Fri, 16 Oct 2009)
New Revision: 95013
Added:
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Ordering_Group.xml
Modified:
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml
Log:
'committing JBoss Messaging 1.4.3 (1.4.6 update)'
Modified: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml 2009-10-16 08:18:36 UTC (rev 95012)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml 2009-10-16 08:20:06 UTC (rev 95013)
@@ -271,7 +271,22 @@
</para>
</warning>
</section>
+
+ <section id="conf.serverpeer.attributes.suckerconnectionretryTimes">
+ <title>SuckerConnectionRetryTimes</title>
+ <para>
+ This is the maximum number of times a sucker's connection is permitted to retry in the event of a failure. The default value is <literal>-1</literal> which represents "retry indefinately".
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.suckerconnectionretryinterval">
+ <title>SuckerConnectionRetryInterval</title>
+
+ <para>This is the interval in milliseconds between each retry of the failed sucker's
+ connection. The default value is <literal>5000</literal>.</para>
+ </section>
+
<section id="conf.serverpeer.attributes.stricttck">
<title>StrictTCK</title>
@@ -296,8 +311,8 @@
</para>
</section>
- <section id="conf.serverpeer.attributes.messagecounterstatistics">
- <title>MessageCountersStatistics</title>
+ <section id="conf.serverpeer.attributes.messagestatistics">
+ <title>MessageStatistics</title>
<para>
Statistics about each message counter for each queue.
@@ -1822,9 +1837,9 @@
<section id="conf.connectionfactory.attributes.slowconsumers">
<title>SlowConsumers</title>
-
- <para>
- If a slow consumer maintains a large buffer, it may prevent faster consumers receiving the buffered messages. Setting <varname>SlowConsumers</varname> to <literal>true</literal> is equivalent to setting <varname>PrefetchSize</varname> to <literal>1</literal>.
+
+ <para>
+ If a slow consumer maintains a large buffer, it may prevent faster consumers receiving the buffered messages. Totally disabling buffering is not possible, however, setting <varname>SlowConsumers</varname> to <literal>true</literal> is equivalent to setting <varname>PrefetchSize</varname> to <literal>1</literal> which is the lowest possible value available.
</para>
</section>
@@ -1917,6 +1932,22 @@
Specifies the remoting connector used by the connection factory. Different connection factories can use different connectors, so you can deploy one connection factory that uses the HTTP transport to communicate with the server, and another that uses the bisocket transport to communicate.
</para>
</section>
+
+ <section id="conf.connectionfactory.attributes.enableorderinggroup">
+ <title>EnableOrderingGroup</title>
+
+ <para>
+ This parameter controls whether strict message ordering is enabled on the <literal>ConnectionFactory</literal>. If set to <literal>true</literal>, the messages sent from producers created from this connection factory become ordering group messages. The default value for this pameter is <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.defaultorderinggroupname">
+ <title>DefaultOrderingGroupName</title>
+
+ <para>
+ This is the default name for the message ordering group which will take effect if the <literal>EnableOrderingGroup</literal> parameter is set to <literal>true</literal> . If this attribute is missing, the group name will be generated automatically.
+ </para>
+ </section>
</section>
<!-- End conf.connectionfactory.attributes -->
Modified: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml 2009-10-16 08:18:36 UTC (rev 95012)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml 2009-10-16 08:20:06 UTC (rev 95013)
@@ -82,7 +82,12 @@
<para>HTTP transport, for use with firewalls that allow only HTTP traffic;
</para>
</listitem>
+
+ <listitem>
+ <para>servlet transport to allow messaging through a dedicated servlet;</para>
+ </listitem>
+
<listitem>
<para>SSL transport;</para>
</listitem>
@@ -98,6 +103,12 @@
<listitem>
<para>the automatic paging of messages to storage, which lets you use very large queues that would be too large to fit entirely within system memory.</para>
</listitem>
+
+ <listitem>
+ <para>
+ strict message ordering, which results in messages belonging to a particular message group being delivered according to the order of their arrival at the target queue.
+ </para>
+ </listitem>
</itemizedlist>
<para>JBoss Messaging also includes the following clustering features:</para>
@@ -194,4 +205,26 @@
</para>
</important>
</section>
+
+ <section id="properties">
+ <title>System Properties used by JBoss Messaging</title>
+
+ <section id="properties.supportBytesId">
+ <title>support.bytesId</title>
+
+ <para>
+ This system property controls the default behavior when constructing a <literal>JBossMessage</literal> object from a foreign message object. If this property is set to true, the <literal>JBossMessage</literal> constructor will try to extract the native byte[] correlation ID from the foreign message headers. If set to false, it will use the normal string type <literal>JMSCorrelationID</literal>. This property will default to <literal>true</literal> if not set or when set to something other than <literal>true</literal> or <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="properties.retainOldxabehaviour">
+ <title>retain.oldxabehaviour</title>
+
+ <para>
+ This system property controls the type of exception thrown by a JMS XAResource in the event that the prepare is called after the connection is broken. If this property is not defined, an <literal>XAException</literal> with a <literal>XA_RBCOMMFAIL</literal> error code will be thrown. Otherwise an <literal>XAException</literal> with an <literal>XA_RETRY</literal> error code will be thrown. It should be noted that JBoss Messaging does not define this property by default.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
Modified: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml 2009-10-16 08:18:36 UTC (rev 95012)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml 2009-10-16 08:20:06 UTC (rev 95013)
@@ -14,6 +14,7 @@
<!-- Chapter below commented out as applicable to EAP4.3 and not EAP5.0 -->
<!-- <xi:include href="Recovery_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
<xi:include href="Bridge.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Ordering_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Ordering_Group.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Ordering_Group.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Ordering_Group.xml 2009-10-16 08:20:06 UTC (rev 95013)
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="orderinggroup">
+ <title>Enabling JBoss Messaging Ordering Group</title>
+
+ <para>
+ This section describes how to use the JBoss Messaging ordering group feature to achieve strict message ordering.
+ </para>
+
+ <para>
+ 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).
+ </para>
+
+ <para>
+ Ordering groups are identified by their string names and obey the following rules:
+ </para>
+
+ <para>
+ Rule 1. 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.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>CLIENT_ACKNOWLEDGE</literal> mode results in the <classname>Message</classname>.<methodname>acknowledge()</methodname> method signals the completion state.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>AUTO_ACKNOWLEDGE</literal> and <literal>DUPS_OK_ACKNOWLEDGE</literal> modes result in the completion of the message being identified by either of the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ a successful return from the <classname>MessageConsumer</classname>.<methodname>receive()</methodname> method, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a successful return from the <methodname>onMessage()</methodname> call of the <literal>MessageListener()</literal>;
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <note><title>Note</title>
+ <para>
+ If the message consumer is closed, the current message being processed will be deemed as completed regardless of whether the an <literal>ACKNOWLEGE</literal> is called prior to closing the consumer.
+ </para>
+ </note>
+ <!-- not sure about this. Cannot find in code. -->
+
+ <para>
+ Rule 2. 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 cancelled, sent back to the JMS server and made available for the next delivery.
+ </para>
+
+ <section id="enable.ordering.group">
+ <title>How to Enable Message Ordering Group</title>
+
+ <para>
+ JBoss Messaging ordering groups may be enabled by using the API or by making configuration changes.
+ </para>
+
+ <formalpara><title>API Implementation</title>
+
+ <para>
+ To make use of JBoss Messaging's ordering group feature, one has to obtain a <classname>JBossMessageProducer</classname>.
+ </para>
+ </formalpara>
+
+ <programlisting>
+ JBossMessageProducer producer = (JBossMessageProducer)session.createProducer(queue);
+ </programlisting>
+
+<para>JBossMessageProducer provides two methods for starting and ending an ordering group. The are, respectively:</para>
+
+ <programlisting>
+public void enableOrderingGroup(String ogrpName) throws JMSException
+ </programlisting>
+
+<para>
+ This code example creates an ordering group with the name <literal>ogrpName</literal>. Once called, the producer will send messages on behalf of the ordering group. If a <literal>null</literal> 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.
+</para>
+
+ <programlisting>
+public void disableOrderingGroup() throws JMSException
+ </programlisting>
+
+<para>
+ This code example demonstrates how to stop producing ordering group messages. Once called, the producer will stop sending out ordering group messages and return to its default behavior.
+</para>
+
+ <formalpara><title>Configuration Implementation</title>
+
+<para>
+ 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:
+</para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>EnableOrderingGroup;</literal>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ set this property to <literal>true</literal> to enable the ordering group feature. The default is false.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>DefaultOrderingGroupName;</literal>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the default name for the message ordering group. The group name will be generated automatically if this attribute is missing.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ </itemizedlist>
+
+<note><title>Note</title>
+<para>
+ 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.
+</para>
+</note>
+<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 advantage of a configuration implementation is the ease with which message ordering functionality can be achieved without the need for sode changes. LEAVE OUT?
+ </para>
+
+</section>
+
+<section id="note.ordering.group">
+ <title>Notes and Limitations</title>
+ <para>
+ The following points should be noted in regard to ordering group functionality:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Queues must be used for use with the ordering group feature as it will not work with topics.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Ordering group should not be used in conjunction with message selectors and scheduled delivery.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A message is considered completed and the next message will be available for delivery if the original message is dead or has expired. A dead message is moved to the DLQ whereas an expired message is moved to the ExpiryQueue.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When using a <literal>ConnectionConsumer</literal>, the ordering of the messages will be observed. However, the <literal>ConnectionConsumer</literal> does not control which session will receive the next message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the case of a Distributed Queue, the user should use <literal>HASingleton</literal> to ensure that ordering group functions correctly.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+</section>
+</chapter>
Modified: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml 2009-10-16 08:18:36 UTC (rev 95012)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml 2009-10-16 08:20:06 UTC (rev 95013)
@@ -119,7 +119,27 @@
</para>
</listitem>
</varlistentry>
+
<varlistentry>
+ <term><filename>/doc/examples/jboss-messaging-examples/servlet/</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates how to use servlet transport with JBoss Messaging. It deploys a servlet and a <literal>ConnectionFactory</literal> that uses the servlet transport.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>/doc/examples/jboss-messaging-examples/ordering-group/</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates the use of strict message ordering. It uses the JBoss Messaging ordering group API to deliver strictly ordered messages, regardless of the message priority.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
<term><filename>/doc/examples/jboss-messaging-examples/bridge/</filename></term>
<listitem>
<para>
More information about the jboss-cvs-commits
mailing list