[jboss-cvs] JBoss Messaging SVN: r6909 - in trunk/docs/user-manual: en and 1 other directory.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Wed May 20 04:58:22 EDT 2009


Author: ataylor
Date: 2009-05-20 04:58:22 -0400 (Wed, 20 May 2009)
New Revision: 6909

Added:
   trunk/docs/user-manual/en/appserver-integration.xml
   trunk/docs/user-manual/en/architecture.xml
   trunk/docs/user-manual/en/client-reconnection.xml
   trunk/docs/user-manual/en/clusters.xml
   trunk/docs/user-manual/en/command-buffering.xml
   trunk/docs/user-manual/en/configuration-index.xml
   trunk/docs/user-manual/en/configuring-transports.xml
   trunk/docs/user-manual/en/connection-ttl.xml
   trunk/docs/user-manual/en/core-bridges.xml
   trunk/docs/user-manual/en/diverts.xml
   trunk/docs/user-manual/en/duplicate-detection.xml
   trunk/docs/user-manual/en/embedding-jbm.xml
   trunk/docs/user-manual/en/examples.xml
   trunk/docs/user-manual/en/filter-expressions.xml
   trunk/docs/user-manual/en/flow-control.xml
   trunk/docs/user-manual/en/ha.xml
   trunk/docs/user-manual/en/intercepting-operations.xml
   trunk/docs/user-manual/en/interoperability.xml
   trunk/docs/user-manual/en/jms-core-mapping.xml
   trunk/docs/user-manual/en/large-messages.xml
   trunk/docs/user-manual/en/last-value-queues.xml
   trunk/docs/user-manual/en/logging.xml
   trunk/docs/user-manual/en/management.xml
   trunk/docs/user-manual/en/message-expiry.xml
   trunk/docs/user-manual/en/message-grouping.xml
   trunk/docs/user-manual/en/messaging-concepts.xml
   trunk/docs/user-manual/en/paging.xml
   trunk/docs/user-manual/en/perf-tuning.xml
   trunk/docs/user-manual/en/persistence.xml
   trunk/docs/user-manual/en/pre-acknowledge.xml
   trunk/docs/user-manual/en/preface.xml
   trunk/docs/user-manual/en/project-info.xml
   trunk/docs/user-manual/en/queue-attributes.xml
   trunk/docs/user-manual/en/scheduled-messages.xml
   trunk/docs/user-manual/en/security.xml
   trunk/docs/user-manual/en/send-guarantees.xml
   trunk/docs/user-manual/en/thread-pooling.xml
   trunk/docs/user-manual/en/undelivered-messages.xml
   trunk/docs/user-manual/en/using-core.xml
   trunk/docs/user-manual/en/using-jms.xml
   trunk/docs/user-manual/en/using-server.xml
   trunk/docs/user-manual/en/wildcard-syntax.xml
Removed:
   trunk/docs/user-manual/en/modules/
Modified:
   trunk/docs/user-manual/en/master.xml
   trunk/docs/user-manual/user-manual.xpr
Log:
moved user manual chapters

Copied: trunk/docs/user-manual/en/appserver-integration.xml (from rev 6908, trunk/docs/user-manual/en/modules/appserver-integration.xml)
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/appserver-integration.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,705 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="appserver-integration">
+    <title>Application Server Integration and JavaEE</title>
+    <para>JBM is fully integrated with the JBoss Application Server version 5.1. For details on
+        installing JBM in the AS refer to Quick Start guide.</para>
+    <para>This section explains the basics behind configuring the different JEE components in the
+        AS.</para>
+    <section>
+        <title>Using and Configuring the JCA Adapter</title>
+        <para>The Java Connector Architecture (JCA) Adapter is what allows JBM to be integrated with
+            JEE components such as MDB's and EJB's. It configures how components such as MDB's
+            consume messages from the JBM server and also how components can send messages.</para>
+        <para>The JBM JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
+            configuration of the Adapter is found in this archive under <literal
+                >META-INF/ra.xml</literal>.</para>
+        <para>The configuration will look something like the following:</para>
+        <programlisting>&lt;resourceadapter>
+      &lt;resourceadapter-class>org.jboss.messaging.ra.JBMResourceAdapter&lt;/resourceadapter-class>
+      &lt;config-property>
+         &lt;description>The transport type&lt;/description>
+         &lt;config-property-name>ConnectorClassName&lt;/config-property-name>
+         &lt;config-property-type>java.lang.String&lt;/config-property-type>
+         &lt;config-property-value>org.jboss.messaging.core.remoting.impl.invm.InVMConnectorFactory&lt;/config-property-value>
+      &lt;/config-property>
+      &lt;config-property>
+         &lt;description>The transport configuration. These values must be in the form of key=val;key=val;&lt;/description>
+         &lt;config-property-name>ConnectionParameters&lt;/config-property-name>
+         &lt;config-property-type>java.lang.String&lt;/config-property-type>
+         &lt;config-property-value>jbm.remoting.invm.serverid=0&lt;/config-property-value>
+      &lt;/config-property>
+       &lt;config-property>
+        &lt;description>Use XA methods to obtain connections?&lt;/description>
+        &lt;config-property-name>UseXA&lt;/config-property-name>
+        &lt;config-property-type>java.lang.Boolean&lt;/config-property-type>
+        &lt;config-property-value>true&lt;/config-property-value>
+      &lt;/config-property>
+
+      &lt;outbound-resourceadapter>
+         &lt;connection-definition>
+            &lt;managedconnectionfactory-class>org.jboss.messaging.ra.JBMManagedConnectionFactory&lt;/managedconnectionfactory-class>
+
+            &lt;config-property>
+               &lt;description>The default session type&lt;/description>
+               &lt;config-property-name>SessionDefaultType&lt;/config-property-name>
+               &lt;config-property-type>java.lang.String&lt;/config-property-type>
+               &lt;config-property-value>javax.jms.Queue&lt;/config-property-value>
+            &lt;/config-property>
+            &lt;config-property>
+               &lt;description>Try to obtain a lock within specified number of seconds; less than or equal to 0 disable this functionality&lt;/description>
+               &lt;config-property-name>UseTryLock&lt;/config-property-name>
+               &lt;config-property-type>java.lang.Integer&lt;/config-property-type>
+               &lt;config-property-value>0&lt;/config-property-value>
+            &lt;/config-property>
+
+            &lt;connectionfactory-interface>org.jboss.messaging.ra.JBMConnectionFactory&lt;/connectionfactory-interface>
+            &lt;connectionfactory-impl-class>org.jboss.messaging.ra.JBMConnectionFactoryImpl&lt;/connectionfactory-impl-class>
+            &lt;connection-interface>javax.jms.Session&lt;/connection-interface>
+            &lt;connection-impl-class>org.jboss.messaging.ra.JBMSession&lt;/connection-impl-class>
+         &lt;/connection-definition>
+         &lt;transaction-support>XATransaction&lt;/transaction-support>
+         &lt;authentication-mechanism>
+            &lt;authentication-mechanism-type>BasicPassword&lt;/authentication-mechanism-type>
+            &lt;credential-interface>javax.resource.spi.security.PasswordCredential&lt;/credential-interface>
+         &lt;/authentication-mechanism>
+         &lt;reauthentication-support>false&lt;/reauthentication-support>
+      &lt;/outbound-resourceadapter>
+
+      &lt;inbound-resourceadapter>
+         &lt;messageadapter>
+            &lt;messagelistener>
+               &lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type>
+               &lt;activationspec>
+                  &lt;activationspec-class>org.jboss.messaging.ra.inflow.JBMActivationSpec&lt;/activationspec-class>
+                  &lt;required-config-property>
+                      &lt;config-property-name>destination&lt;/config-property-name>
+                  &lt;/required-config-property>
+               &lt;/activationspec>
+            &lt;/messagelistener>
+         &lt;/messageadapter>
+      &lt;/inbound-resourceadapter>
+
+   &lt;/resourceadapter></programlisting>
+        <para>There are 3 main parts to this configuration.</para>
+        <orderedlist>
+            <listitem>
+                <para>A set of global properties for the Adapter</para>
+            </listitem>
+            <listitem>
+                <para>The configuration for the outbound part of the adapter. This is used for
+                    creating JMS resources within EE components</para>
+            </listitem>
+            <listitem>
+                <para>The configuration of the inbound part of the adapter. This is used for
+                    controlling the consumption of messages via MDB's.</para>
+            </listitem>
+        </orderedlist>
+        <section>
+            <title>Adapter Global properties</title>
+            <para>The first element you see is <literal>resourceadapter-class</literal> which should
+                be left unchanged. This is the JBM resource adapter class.</para>
+            <para>After that there is a list of configuration properties. This will be where most of
+                the configuration is done. The first 2 configure the transport used by the adapter
+                and the rest configure the connection itself.</para>
+            <para>The following table explains what each property is for.</para>
+            <table frame="topbot" border="2">
+                <title>Global Configuration Properties</title>
+                <tgroup cols="3">
+                    <colspec colname="c1" colnum="1" colwidth="0.55*"/>
+                    <colspec colname="c2" colnum="2" colwidth="0.31*"/>
+                    <colspec colname="c3" colnum="3" colwidth="2.14*"/>
+                    <thead>
+                        <row>
+                            <entry>Property Name</entry>
+                            <entry>Property Type</entry>
+                            <entry>Property Description</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>ConnectorClassName</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The Connector class name see <xref
+                                    linkend="configuring-transports"/> for info on available
+                                connectors</entry>
+                        </row>
+                        <row>
+                            <entry>ConnectionParameters</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The transport configuration. These values must be in the form of
+                                key=val;key=val; and will be specific to the connector used</entry>
+                        </row>
+                        <row>
+                            <entry>UseXA</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>True will enable XA transactions</entry>
+                        </row>
+                        <row>
+                            <entry>UserName</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The user name to use when making a connection </entry>
+                        </row>
+                        <row>
+                            <entry>Password</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The password to use when making a connection</entry>
+                        </row>
+                        <row>
+                            <entry>BackUpTransportType</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The back up transport to use on failure.</entry>
+                        </row>
+                        <row>
+                            <entry>TransportConfiguration</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The back up transport configuration</entry>
+                        </row>
+                        <row>
+                            <entry>DiscoveryGroupAddress</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The discovery group address to use to autodetect a server</entry>
+                        </row>
+                        <row>
+                            <entry>DiscoveryGroupPort</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The port to use for discovery</entry>
+                        </row>
+                        <row>
+                            <entry>DiscoveryRefreshTimeout</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>The timeout, in milli seconds, to refresh.</entry>
+                        </row>
+                        <row>
+                            <entry>DiscoveryInitialWaitTimeout</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>The initial time to wait for discovery.</entry>
+                        </row>
+                        <row>
+                            <entry>LoadBalancingPolicyClassName</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The load balancing policy class to use.</entry>
+                        </row>
+                        <row>
+                            <entry>PingPeriod</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>The period, in milliseconds, to ping the server for
+                                failure.</entry>
+                        </row>
+                        <row>
+                            <entry>ConnectionTTL</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>The time to live for the connection.</entry>
+                        </row>
+                        <row>
+                            <entry>CallTimeout</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>the call timeout, in milli seconds, for each packet sent.</entry>
+                        </row>
+                        <row>
+                            <entry>DupsOKBatchSize</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The batch size of message acks to use if Dups ok is used.</entry>
+                        </row>
+                        <row>
+                            <entry>TransactionBatchSize</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The batch size to use for sending messages  within a
+                                transaction</entry>
+                        </row>
+                        <row>
+                            <entry>ConsumerWindowSize</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The window size for the consumers internal buffer.</entry>
+                        </row>
+                        <row>
+                            <entry>ConsumerMaxRate</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The max rate a consumer can receive.</entry>
+                        </row>
+                        <row>
+                            <entry>ProducerWindowSize</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The window size for the sending of messages.</entry>
+                        </row>
+                        <row>
+                            <entry>ProducerMaxRate</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The max rate a producer can send messages.</entry>
+                        </row>
+                        <row>
+                            <entry>MinLargeMessageSize</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The size a message can be, in bytes, before it is sent as a multi
+                                part large message.</entry>
+                        </row>
+                        <row>
+                            <entry>BlockOnAcknowledge</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>If true then block on acknowledge of messages.</entry>
+                        </row>
+                        <row>
+                            <entry>BlockOnNonPersistentSend</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>If true then block when sending non persistent messages</entry>
+                        </row>
+                        <row>
+                            <entry>BlockOnPersistentSend</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>If true then block when sending persistent messages</entry>
+                        </row>
+                        <row>
+                            <entry>AutoGroup</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>If true then auto group messages</entry>
+                        </row>
+                        <row>
+                            <entry>MaxConnections</entry>
+                            <entry>java.lang.Integer</entry>
+                            <entry>The max number of connections.</entry>
+                        </row>
+                        <row>
+                            <entry>PreAcknowledge</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>Whether to pre acknowledge messages before sending to
+                                consumer</entry>
+                        </row>
+                        <row>
+                            <entry>RetryInterval</entry>
+                            <entry>java.lang.Long</entry>
+                            <entry>How long to wait , in milli seconds, before retrying a failed
+                                connection</entry>
+                        </row>
+                        <row>
+                            <entry>RetryIntervalMultiplier</entry>
+                            <entry>java.lang.Double</entry>
+                            <entry>Used for calculating the retry interval</entry>
+                        </row>
+                        <row>
+                            <entry>FailoverOnServerShutdown</entry>
+                            <entry>java.lang.Boolean</entry>
+                            <entry>If true client will reconnect to another server if
+                                available</entry>
+                        </row>
+                        <row>
+                            <entry>ClientID</entry>
+                            <entry>java.lang.String</entry>
+                            <entry>The client ID of the connection</entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </section>
+        <section>
+            <title>Adapter Outbound configuration</title>
+            <para>The outbound configuration should remain unchanged as they define Connection
+                Factories that are used by EE components. These Connection Factories can be defined
+                inside a configuration file that matches the name <literal>*-ds.xml</literal>.
+                You'll find a default <literal>jms-ds.xml</literal> configuration under the <literal
+                    >messaging.sar</literal> directory in the Jboss AS deployment. the connection
+                factories defined in the config file inherit their properties from the main <literal
+                    >ra.xml</literal> config but can also be overridden, the following example show
+                how to define one.</para>
+            <programlisting>&lt;tx-connection-factory>
+      &lt;jndi-name>RemoteJmsXA&lt;/jndi-name>
+      &lt;xa-transaction/>
+      &lt;rar-name>jms-ra.rar&lt;/rar-name>
+      &lt;connection-definition>org.jboss.messaging.ra.JBMConnectionFactory&lt;/connection-definition>
+      &lt;config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic&lt;/config-property>
+      &lt;config-property name="ConnectorClassName" type="java.lang.String">org.jboss.messaging.integration.transports.netty.NettyConnectorFactory&lt;/config-property>
+      &lt;config-property name="ConnectionParameters" type="java.lang.String">jbm.remoting.netty.port=5445&lt;/config-property>
+      &lt;max-pool-size>20&lt;/max-pool-size>
+&lt;/tx-connection-factory></programlisting>
+            <para>In this example the connection factory will be bound to JNDI with the name
+                    <literal>RemoteJmsXA</literal> and can be looked up in the usual way using JNDI
+                or defined within the EJB or MDB as such:</para>
+            <programlisting>@Resource(mappedName="java:RemoteJmsXA")
+private ConnectionFactory connectionFactory;</programlisting>
+            <para>The <literal>config-property</literal> elements are what over rides those in the
+                    <literal>ra.xml</literal> config.</para>
+        </section>
+        <section>
+            <title>Adapter Inbound configuration</title>
+            <para>The inbound configuration should again remain unchanged. This controls what
+                forwards messages onto MDB's. It is possible to override properties on the MDB by
+                adding an activation config to the MDB itself. This could be used to configure the
+                MDB to consume from a different server. The next section demonstrates over riding
+                the configuration.</para>
+        </section>
+    </section>
+    <section>
+        <title>Using JBM with MDBs in JBoss AS</title>
+        <para>Once the JCA Connector is configured, as shown previously, the MDB's can be configured
+            to consume messages from the MDB server.</para>
+        <para>This is best done by using the <literal>MessageDriven</literal> tag on the MDB itself.
+            The following shows an example.</para>
+        <programlisting>@MessageDriven(name = "MessageMDBExample",
+               activationConfig =
+                     {
+                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
+                        @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge"),
+                        @ActivationConfigProperty(propertyName = "ConnectorClassName", propertyValue = "org.jboss.messaging.integration.transports.netty.NettyConnectorFactory"),
+                        @ActivationConfigProperty(propertyName = "ConnectionParameters", propertyValue = "jbm.remoting.netty.port=5545")
+                     })
+public class MDBRemoteExample implements MessageListener
+{
+   public void onMessage(Message message)
+   {
+      try
+      {
+         //Step 9. We know the client is sending a text message so we cast
+         TextMessage tm = (TextMessage)message;
+
+         //Step 10. get the text from the message.
+         String text = tm.getText();
+
+         System.out.println("message " + text + " received");
+         
+      }
+      catch (Exception e)
+      {
+         e.printStackTrace();
+      }
+   }
+}</programlisting>
+        <para>In this example we have configured the MDB to consume from the queue named <literal
+                >queue/testQueue</literal>. It is also possible to override properties for the
+            inbound resource adapter here is well. Here the MDB is configured to connect to a
+            different server.</para>
+        <para>It is alsp possible to define these properties in the <literal>web.xml</literal>
+            confid file. Refer to the JBoss AS documentation on how to do this.</para>
+    </section>
+    <section>
+        <title>High Availability JNDI (HAJNDI)</title>
+        <para>When using JBM in a clustered environment you will need to use the HAJNDI. This will
+            round robin look ups for connection factories and give load balanced connections.</para>
+        <para>To use it use the following properties when connecting to JNDI.</para>
+        <programlisting>Hashtable&lt;String, String> jndiParameters = new Hashtable&lt;String, String>();
+jndiParameters.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
+jndiParameters.put("java.naming.factory.url.pkgs=", "org.jboss.naming:org.jnp.interfaces");
+
+initialContext = new InitialContext(jndiParameters);</programlisting>
+        <para>For more information visit <ulink
+                url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html"
+            /></para>
+    </section>
+    <section>
+        <title>The JMS Bridge</title>
+        <para>The JMS bridge allows different JMS servers from different JMS providers to be
+            'bridged' together. A bridge will have a source destination from which it receives
+            messages and a target destination to which it sends messages.</para>
+        <para>The bridge is deployed by the JBoss Micro Container via a beans configuration file.
+            This would typically be deployed inside the JBoss Application Server and the following
+            example shows an example of a beans file that bridges 2 JBM servers although here they
+            are actually the same server. </para>
+        <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?>
+
+&lt;deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+       &lt;bean name="JMSBridge" class="org.jboss.messaging.jms.bridge.impl.JMSBridgeImpl">
+           &lt;!-- JBoss Messaging must be started before the bridge -->
+           &lt;depends>MessagingServer&lt;/depends>
+           &lt;constructor>
+               &lt;!-- Source ConnectionFactory Factory -->
+               &lt;parameter>
+                   &lt;inject bean="SourceCFF"/>
+               &lt;/parameter>
+               &lt;!-- Target ConnectionFactory Factory -->
+               &lt;parameter>
+                   &lt;inject bean="TargetCFF"/>
+               &lt;/parameter>
+               &lt;!-- Source DestinationFactory -->
+               &lt;parameter>
+                   &lt;inject bean="SourceDestinationFactory"/>
+               &lt;/parameter>
+               &lt;!-- Target DestinationFactory -->
+               &lt;parameter>
+                   &lt;inject bean="TargetDestinationFactory"/>
+               &lt;/parameter>
+               &lt;!-- Source username (no username here) -->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- Source password (no password here)-->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- Target username (no username here)-->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- Target password (no password here)-->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- Selector -->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- Interval to retry in case of failure (in ms) -->
+               &lt;parameter>5000&lt;/parameter>
+               &lt;!-- Maximum number of retries to connect to the source and target -->
+               &lt;parameter>10&lt;/parameter>
+               &lt;!-- Quality of service -->
+               &lt;parameter>ONCE_AND_ONLY_ONCE&lt;/parameter>
+               &lt;!-- Maximum batch size -->
+               &lt;parameter>1&lt;/parameter>
+               &lt;!-- Maximum batch time (-1 means infinite) -->
+               &lt;parameter>-1&lt;/parameter>
+               &lt;!-- Subscription name (no subscription name here)-->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- client ID  (no client ID here)-->
+               &lt;parameter>&lt;null />&lt;/parameter>
+               &lt;!-- concatenate JMS messageID to the target's message header -->
+               &lt;parameter>true&lt;/parameter>
+           &lt;/constructor>
+           &lt;property name="transactionManager">
+               &lt;inject bean="RealTransactionManager"/>
+           &lt;/property>
+       &lt;/bean>
+
+       &lt;!-- SourceCFF describes the ConnectionFactory used to connect to the source destination -->
+       &lt;bean name="SourceCFF" class="org.jboss.messaging.jms.bridge.impl.JNDIConnectionFactoryFactory">
+           &lt;constructor>
+               &lt;parameter>
+                   &lt;inject bean="JNDI" />
+               &lt;/parameter>
+               &lt;parameter>/ConnectionFactory&lt;/parameter>
+           &lt;/constructor>  
+       &lt;/bean>
+
+       &lt;!-- TargetCFF describes the ConnectionFactory used to connect to the target destination -->
+       &lt;bean name="TargetCFF" class="org.jboss.messaging.jms.bridge.impl.JNDIConnectionFactoryFactory">
+           &lt;constructor>
+               &lt;parameter>
+                   &lt;inject bean="JNDI" />
+               &lt;/parameter>
+               &lt;parameter>/ConnectionFactory&lt;/parameter>
+           &lt;/constructor>  
+       &lt;/bean>
+
+       &lt;!-- SourceDestinationFactory describes the Destination used as the source -->
+       &lt;bean name="SourceDestinationFactory" class="org.jboss.messaging.jms.bridge.impl.JNDIDestinationFactory">
+           &lt;constructor>
+               &lt;parameter>
+                   &lt;inject bean="JNDI" />
+               &lt;/parameter>
+               &lt;parameter>/queue/source&lt;/parameter>
+           &lt;/constructor>  
+       &lt;/bean>
+
+       &lt;!-- TargetDestinationFactory describes the Destination used as the target -->
+       &lt;bean name="TargetDestinationFactory" class="org.jboss.messaging.jms.bridge.impl.JNDIDestinationFactory">
+           &lt;constructor>
+               &lt;parameter>
+                   &lt;inject bean="JNDI" />
+               &lt;/parameter>
+               &lt;parameter>/queue/target&lt;/parameter>
+           &lt;/constructor>  
+       &lt;/bean>
+       
+       &lt;!-- JNDI is a Hashtable containing the JNDI properties required -->
+       &lt;!-- to connect to the sources and targets JMS resrouces         -->       
+      &lt;bean name="JNDI" class="java.util.Hashtable">
+         &lt;constructor class="java.util.Map">
+            &lt;map class="java.util.Hashtable" keyClass="java.lang.String"
+                                             valueClass="java.lang.String">
+               &lt;entry>
+                  &lt;key>java.naming.factory.initial&lt;/key>
+                  &lt;value>org.jnp.interfaces.NamingContextFactory&lt;/value>
+               &lt;/entry>
+               &lt;entry>
+                  &lt;key>java.naming.provider.url&lt;/key>
+                  &lt;value>jnp://localhost:1099&lt;/value>
+               &lt;/entry>
+               &lt;entry>
+                  &lt;key>java.naming.factory.url.pkgs&lt;/key>
+                  &lt;value>org.jboss.naming:org.jnp.interfaces"&lt;/value>
+               &lt;/entry>
+            &lt;/map>
+         &lt;/constructor>
+      &lt;/bean>
+
+&lt;/deployment></programlisting>
+        <para>The main bean deployed is the <literal>JMSBridge</literal> bean. A description of each
+            of its constructor parameters in order follows:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Source Connection Factory Factory - This injects the <literal
+                        >SourceCFF</literal> bean that is the connection factory defined later in
+                    the beans file.</para>
+            </listitem>
+            <listitem>
+                <para>Target Connection Factory Factory - This injects the <literal
+                        >TargetCFF</literal> bean that is the connection factory defined later in
+                    the beans file.</para>
+            </listitem>
+            <listitem>
+                <para>Source Destination Factory Factory - This injects the <literal
+                        >SourceDestinationFactory</literal> bean that is used to create or lookup
+                    the sourcedestination.</para>
+            </listitem>
+            <listitem>
+                <para>Target Destination Factory Factory - This injects the <literal
+                        >TargetDestinationFactory</literal> bean that is used to create or lookup
+                    the target destination.</para>
+            </listitem>
+            <listitem>
+                <para>Source User Name - the user name to use for the source connection.</para>
+            </listitem>
+            <listitem>
+                <para>Source Password - The password to use for the source connection.</para>
+            </listitem>
+            <listitem>
+                <para>Target User Name - The user name to use for the target connection.</para>
+            </listitem>
+            <listitem>
+                <para>Target Password - The password to use for thetarget connection.</para>
+            </listitem>
+            <listitem>
+                <para>Retry Interval - Interval to retry in case of failure (in ms). </para>
+            </listitem>
+            <listitem>
+                <para>Retries - Maximum number of retries to connect to the source and
+                    target.</para>
+            </listitem>
+            <listitem>
+                <para>Quality of Service - Either 'QOS_AT_MOST_ONCE', 'QOS_DUPLICATES_OK' or
+                    'QOS_DUPLICATES_OK'. These are explained shortly.</para>
+            </listitem>
+            <listitem>
+                <para>Batch Size - When using transactions how many messages to send per
+                    batch.</para>
+            </listitem>
+            <listitem>
+                <para>Batch Time - The maximum time to wait before committing a transaction anyway
+                    (in MS).</para>
+            </listitem>
+            <listitem>
+                <para>Subscription Name - The name of the subscription if using a durable subscriber
+                    with the source connection.</para>
+            </listitem>
+            <listitem>
+                <para>Client ID - The client ID to use for the source connection. Needed when
+                    subscription name is provided.</para>
+            </listitem>
+            <listitem>
+                <para>Concatenate Message ID - If this is set the message ID from the received
+                    message will be concatenated as message header <literal
+                        >JBM_BRIDGE_MSG_ID_LIST</literal>. This is because it will change once the
+                    bridge forwards it. When passing through multiple bridges each ID is
+                    concatenated to the list.</para>
+                <note>
+                    <para>when you receive the message you can send back a response using the
+                        correlation id of the first message id, so when the original sender gets it
+                        back it will be able to correlate it. </para>
+                </note>
+            </listitem>
+        </itemizedlist>
+        <section>
+            <title>Source and Target Connection Factories</title>
+            <para>The source and target connection factory factories are used to create the
+                connection factory used to create the connection for the source or target
+                server.</para>
+            <para>In this example we have used the default provided by JBM that look up the
+                connection factory using JNDI. For other Application Servers or JMS providers a new
+                implementation may have to be provided. This can easily be done by implementing the
+                interface <literal
+                >org.jboss.messaging.jms.bridge.ConnectionFactoryFactory</literal>.</para>
+        </section>
+        <section>
+            <title>Source and Target Destination Factories</title>
+            <para>Again, similarly, these are used to create or lookup up the destinations. To
+                provid a new implementation simple implement <literal
+                    >org.jboss.messaging.jms.bridge.DestinationFactory</literal> interface.</para>
+        </section>
+        <section>
+            <title>Quality Of Service</title>
+            <para>The quality of service modes used by the bridge are described here in more
+                detail.</para>
+            <section>
+                <title>QOS_AT_MOST_ONCE</title>
+                <para>With this QoS mode messages will reach the destination from the source at most
+                    once. The messages are consumed from the source and acknowledged before sending
+                    to the destination. Therefore there is a possibility that if failure occurs
+                    between removing them from the source and them arriving at the destination they
+                    could be lost. Hence delivery will occur at most once. This mode is available
+                    for both persistent and non persistent messages.</para>
+            </section>
+            <section>
+                <title>QOS_DUPLICATES_OK</title>
+                <para>With this QoS mode, the messages are consumed from the source and then
+                    acknowledged after they have been successfully sent to the destination.
+                    Therefore there is a possibility that if failure occurs after sending to the
+                    destination but before acknowledging them, they could be sent again when the
+                    system recovers. I.e. the destination might receive duplicates after a failure.
+                    This mode is available for both persistent and non persistent messages.</para>
+            </section>
+            <section>
+                <title>QOS_ONCE_AND_ONLY_ONCE</title>
+                <para>This QoS mode ensures messages will reach the destination from the source once
+                    and only once. (Sometimes this mode is known as "exactly once"). If both the
+                    source and the destination are on the same JBoss Messaging server instance then
+                    this can be achieved by sending and acknowledging the messages in the same local
+                    transaction. If the source and destination are on different servers this is
+                    achieved by enlisting the sending and consuming sessions in a JTA transaction.
+                    The JTA transaction is controlled by JBoss Transactions JTA * implementation
+                    which is a fully recovering transaction manager, thus providing a very high
+                    degree of durability. If JTA is required then both supplied connection factories
+                    need to be XAConnectionFactory implementations. This mode is only available for
+                    persistent messages. This is likely to be the slowest mode since it requires
+                    extra persistence for the transaction logging.</para>
+                <note>
+                    <para>For a specific application it may possible to provide once and only once
+                        semantics without using the QOS_ONCE_AND_ONLY_ONCE QoS level. This can be
+                        done by using the QOS_DUPLICATES_OK mode and then checking for duplicates at
+                        the destination and discarding them. Some JMS servers provide automatic
+                        duplicate message detection functionality, or this may be possible to
+                        implement on the application level by maintaining a cache of received
+                        message ids on disk and comparing received messages to them. The cache would
+                        only be valid for a certain period of time so this approach is not as
+                        watertight as using QOS_ONCE_AND_ONLY_ONCE but may be a good choice
+                        depending on your specific application.</para>
+                </note>
+            </section>
+            
+            <section>
+               <title>Example</title>
+               <para>The <literal>javaee/jms-bridge</literal> example shows
+                  how to configure and use a JMS Bridge to send messages to the source destination
+                  and consume them from the target destination.</para>
+            </section>
+            
+        </section>
+   </section>
+     
+   <section id="xa-recovery">
+      <title>XA Recovery</title>
+      <para><emphasis>XA recovery</emphasis> deals with system or application failures to ensure that 
+          of a transaction are applied consistently to all resources affected by the transaction,
+          even if any of the application processes or the machine hosting them crash or 
+          lose network connectivity. For more information on XA Recovery, refer to 
+          <ulink url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss Transactions</ulink>.</para>
+         
+      <para>When JBoss Messaging is integrated with JBoss AS, it can take advantage of JBoss Transactions
+         to provide recovery of messaging resources. If messages are involved in a XA transaction, in the
+         event of a server crash, the recovery manager will ensure that the transactions are recovered
+         and the messages will either be committed or rolled back (depending on the transaction outcome)
+         when the server is restarted.</para>
+      
+      <section>
+         <title>XA Recovery Configuration</title>
+         <para>To enable JBoss Messaging's XA Recovery, the following property must be added to
+            the <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal> of JBoss AS profiles:</para>
+         <programlisting>
+   &lt;properties depends="arjuna" name="jta"&gt;
+      ...
+                     
+      &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1"
+               value="org.jboss.messaging.jms.server.recovery.MessagingXAResourceRecovery;java:/XAConnectionFactory"/&gt;
+   &lt;/properties&gt;
+         </programlisting>
+      
+         <para>This informs the recovery manager that it can recovers JBoss Messaging XA 
+            Resources using the <literal>XAConnectionFactory</literal> bound to <literal>java:/XAConnectionFactory</literal> in JNDI.
+            A ConnectionFactory must have been configured with this JNDI name in <literal>jbm-jms.xml</literal> (see <xref linkend="using-jms.server.configuration" />).</para>
+      </section>
+      
+      <section>
+         <title>Example</title>
+         <para>The <literal>javaee/xarecovery</literal> example shows
+            how to configure XA Recovery and recover messages after a server crash.</para>
+      </section>
+      
+   </section>         
+</chapter>

Copied: trunk/docs/user-manual/en/architecture.xml (from rev 6908, trunk/docs/user-manual/en/modules/architecture.xml)
===================================================================
--- trunk/docs/user-manual/en/architecture.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/architecture.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="architecture">
+    <title>Architecture</title>
+    <para>In this section we will discuss the JBoss Messaging high level architecture and
+        concepts.</para>
+    <section>
+        <title>Core Architecture</title>
+        <para>JBoss Messaging core is designed simply as set of Plain Old Java Objects
+            (POJOs).</para>
+        <para>We've also designed it to have as few dependencies on external jars as possible. In
+            fact, JBoss Messaging core has <emphasis role="italic">zero</emphasis> dependencies on
+            any jars other than the standard JDK classes!</para>
+        <para>This allows JBoss Messaging to be easily embedded in your own project, or instantiated
+            in any dependency injection framework such as JBoss Microcontainer or Spring.</para>
+        <para>A JBoss Messaging server has its own high performance persistent journal, which it
+            uses for message and other persistence.</para>
+        <para>Using a high performance journal allows outrageous persistence message performance,
+            something not achievable when using a relational database for persistence.</para>
+        <para>JBoss Messaging clients, potential on different physical machines interact with the
+            JBoss Messaging server. JBoss Messaging currently provides two APIs for messaging at the
+            client side:</para>
+        <para>
+            <orderedlist>
+                <listitem>
+                    <para>Core client API. This is a simple intuitive Java API that allows the full
+                        set of messaging functionality without some of the complexities of
+                        JMS.</para>
+                </listitem>
+                <listitem>
+                    <para>JMS client API. The standard JMS classes are available at the client
+                        side.</para>
+                </listitem>
+            </orderedlist>
+        </para>
+        <para>JMS semantics are implemented in a thin JMS facade layer on the client side.</para>
+        <para>The JBoss Messaging server does not speak JMS and in fact does not know anything about
+            JMS, it's a protocol agnostic messaging server designed to be used with multiple
+            different protocols.</para>
+        <para>When a user uses the JMS API on the client side, all JMS interactions are translated
+            into operations on the JBoss Messaging core client API before being transferred over the
+            wire using the JBoss Messaging wire format.</para>
+        <para>The server always just deals with core API interactions.</para>
+        <para>A schematic illustrating this relationship is shown in figure 3.1 below:</para>
+        <para/>
+        <para>
+            <graphic fileref="images/architecture1.jpg" align="center"/>
+        </para>
+        <para>Figure 3.1 shows two user applications interacting with a JBoss Mesaging server. User
+            Application 1 is using the JMS API, while User Application 2 is using the core client
+            API directly.</para>
+        <para>You can see from the diagram that the JMS API is implemented by a thin facade layer on
+            the client side.</para>
+    </section>
+    <section>
+        <title>JBoss Messaging embedded in your own application</title>
+        <para>JBoss Messaging core is designed as a set of simple POJOs so if you have an
+            application that requires messaging functionality internally but you don't want to
+            expose that as a messaging server you can directly instantiate and embed messaging
+            servers in your own application.</para>
+        <para>Here's a real code example demonstrating just how easy that is:</para>
+        <para><code> Server server = new MessagingServer(); </code></para>
+    </section>
+    <section>
+        <title>JBoss Messaging integrated with a JEE application server</title>
+        <para>JBoss Messaging provides its own fully functional Java Connector Architecture (JCA)
+            adaptor which enables it to be integrated easily into any JEE compliant application
+            server or servlet engine.</para>
+        <para>JEE application servers provide Message Driven Beans (MDBs), which are a special type
+            of Enterprise Java Beans (EJBs) which can process messages from sources such as JMS
+            systems or mail systems.</para>
+        <para>Probably the most common use of an MDB is to consume messages from a JMS messaging
+            system.</para>
+        <para>According to the JEE specification, a JEE application server uses a JCA adapter to
+            integrate with a JMS messaging system so it can consume messages for MDBs.</para>
+        <para>The JCA adapter is not only used by the JEE application server for <emphasis
+                role="italic">consuming</emphasis> messages via MDBs, it is also used when sending
+            message to the JMS messaging system e.g. from inside an EJB or servlet.</para>
+        <para>When integrating with a JMS messaging system from inside a JEE application server it
+            is always recommended that this is done via the JCA adaptor.</para>
+        <para>The application server's JCA service provides extra functionality such as connection
+            pooling and automatic transaction enlistment, which are desirable when using messaging,
+            say, from inside an EJB. It is possible to talk to a JMS messaging system directly from
+            an EJB, MDB or servlet without going through a JCA adapter, but this is not recommended
+            since you will not be able to take advantage of the JCA features.</para>
+        <para>Figure 3.2 belows shows a JEE application server integrating with a JBoss Messaging
+            server via the JBoss Messaging JCA adaptor. Note that all communication between EJB
+            session or entiry beans and Message Driven beans go through the adaptor and not directly
+            to JBoss Messaging.</para>
+        <para>The large arrow with the prohibited sign shows an EJB session bean talking directly to
+            the JBoss Messaging server. This is not recommended as you'll most likely end up
+            creating a new connection and session every time you want to interact from the EJB,
+            which is an anti-pattern.</para>
+        <para/>
+        <para>
+            <graphic fileref="images/architecture2.jpg"/>
+        </para>
+    </section>
+    <section>
+        <title>JBoss Messaging stand-alone server</title>
+        <para>JBoss Messaging can also be deployed as a stand-alone server. This means a fully
+            independent messaging server not dependent on a JEE application server.</para>
+        <para>The standard stand-alone messaging server configuration comprises a core messaging
+            server, a JMS service and a JNDI service.</para>
+        <para>The role of the JMS Service is to deploy any JMS Queues, Topics and ConnectionFactorys
+            from any server side jbm-jms.xml config files. It also provides a simple management API
+            for creating and destroying Queues, Topics and ConnectionFactorys which can be accessed
+            via JMX or the connection. It is a separate service to the JBoss Messaging core server,
+            since the core server is JMS agnostic. If you don't want to deploy any JMS Queues,
+            Topics and ConnectionFactorys via server side xml config and don't require a JMS
+            management API on the server side then you can disable this service.</para>
+        <para>We also include a JNDI server since JNDI is a common requirement when using JMS to
+            lookup Queues, Topics and ConnectionFactorys. If you do not require JNDI then this
+            service can be disabled. JBoss Messaging allows you to programmatically create JMS and
+            Core objects directly on the client side as opposed to looking them up from JNDI, so a
+            JNDI server is not always a requirement.</para>
+        <para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and
+            enforce dependencies between the components. JBoss Microcontainer is a very lightweight
+            POJO bootstrapper.</para>
+        <para>[TODO]  need to add mbean server, jndi server etc to diagram</para>
+        <para>The stand-alone server architecture is shown in figure 3.3 below:</para>
+        <para/>
+        <para>
+            <graphic fileref="images/architecture3.jpg"/>
+        </para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/client-reconnection.xml (from rev 6908, trunk/docs/user-manual/en/modules/client-reconnection.xml)
===================================================================
--- trunk/docs/user-manual/en/client-reconnection.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/client-reconnection.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="client-reconnection">
+    <title>Client Reconnection</title>
+    <para>JBoss Messaging clients can be configured to automatically reconnect to the server in the event that a failure is detected in the connection
+    between the client and the server. If the client successfully reconnects, and the server still has a record of the clients session (i.e. the
+    server was not restarted) then the client will transparently re-attach to the session and it will be able to resume as if nothing had happened.</para>
+    <para>Client reconnnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.</para>
+    <para>Client reconnection is configured using the following parameters:</para>
+    <itemizedlist>
+        <listitem>
+            <para><literal>retry-interval</literal>. This optional parameter determines the
+                period in milliseconds between subsequent reconnection attempts, if the
+                connection to the target server has failed. The default value is <literal
+                    >2000</literal>milliseconds.</para>
+        </listitem>
+        <listitem>
+            <para><literal>retry-interval-multiplier</literal>. This optional parameter
+                determines determines a multiplier to apply to the time since the last retry to
+                compute the time to the next retry.</para>
+            <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
+                between retry attempts.</para>
+            <para>Let's take an example:</para>
+            <para>If we set <literal>retry-interval</literal>to <literal>1000</literal> ms and
+                we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
+                then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
+                ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
+                subsequent reconnection attempts.</para>
+            <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
+                spaced at equal intervals.</para>
+        </listitem>
+        <listitem>
+            <para><literal>reconnect-attempts</literal>. This optional parameter determines the
+                total number of reconnect attempts the bridge will make before giving up and
+                shutting down. A value of <literal>-1</literal> signifies an unlimited number of
+                attempts. The default value is <literal>-1</literal>.</para>
+        </listitem>
+    </itemizedlist>
+    <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS connection factory instances directly into JNDI, then
+    you can specify these parameters in the xml configuration in <literal>jbm-jms.xml</literal>, for example:</para>
+    <programlisting>
+        &lt;connection-factory name="ConnectionFactory"&gt;
+        &lt;connector-ref connector-name="netty"/&gt;
+        &lt;entries&gt;
+        &lt;entry name="ConnectionFactory"/&gt;
+        &lt;entry name="XAConnectionFactory"/&gt;
+        &lt;/entries&gt;
+        &lt;retry-interval&gt;1000&lt;/retry-interval&gt;
+        &lt;retry-interval-multiplier&gt;1.5&lt;/retry-interval-multiplier&gt;
+        &lt;reconnect-attempts&gt;1000&lt;/reconnect-attempts&gt;
+        &lt;/connection-factory&gt;          
+    </programlisting>
+    <para>If you're using JMS, but instantiating your JMS connection factory directly, you can specify the params using the appopriate setter methods
+    on the <literal>JBossConnectionFactory</literal> immediately after creating it.</para>
+    <para>If you're using the core API and instantiating the <literal>ClientSessionFactory</literal> instance directly you can also specify the params using the appopriate setter methods
+        on the <literal>ClientSessionFactory</literal> immediately after creating it.</para>
+    <para>If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or
+    it has timed out, then the client won't be able to re-attach, and any ExceptionListener or FailureListener instances registered on the connection
+    or session will be called.</para>
+    
+    
+    
+    </chapter>
\ No newline at end of file

Copied: trunk/docs/user-manual/en/clusters.xml (from rev 6908, trunk/docs/user-manual/en/modules/clusters.xml)
===================================================================
--- trunk/docs/user-manual/en/clusters.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/clusters.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,673 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="clusters">
+    <title>Clusters</title>
+    <para>In this chapter we discuss the concepts behind JBoss Messaging clusters, and how to
+        configure them.</para>
+    <section>
+        <title>Clusters Overview</title>
+        <para>JBoss Messaging clusters allow groups of JBoss Messaging servers to be grouped
+            together in order to share message processing load. Each active node in the cluster is
+            an active JBoss Messaging server which manages its own messages and handles its own
+            connections.</para>
+        <para>The cluster is formed by each node declaring <emphasis>cluster connections</emphasis>
+            to other nodes in the core configuration file <literal>jbm-configuration.xml</literal>.
+            When a node forms a cluster connection to another node, internally it creates a core
+            bridge (LINK) connection between it and the other node, this is done transparently
+            behind the scenes - you don't have to declare an explicit bridge for each node. These
+            cluster connections allow messages to flow between the nodes of the cluster to balance
+            load.</para>
+        <para>Nodes can be connected together to form a cluster in many different topologies, we
+            will discuss a couple of the more common topologies later in this chapter.</para>
+        <para>We'll also discuss client side load balancing, where we can balance client connections
+            across the nodes of the cluster, and we'll consider message redistribution where JBoss
+            Messaging will redistribute messages between nodes to avoid starvation.</para>
+        <para>Another important part of clustering is <emphasis>server discovery</emphasis> where
+            servers can broadcast their connection details so clients or other servers can connect
+            to them with the minimum of configuration.</para>
+    </section>
+    <section>
+        <title>Server discovery</title>
+        <para>Server discovery is a mechanism by which servers can broadcast their connection
+            settings across the network. This is useful for two purposes:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Discovery by messaging clients. A messaging client wants to be able to connect
+                    to the servers of the cluster without having specific knowledge of which servers
+                    in the cluster are up at any one time. Messaging clients
+                        <emphasis>can</emphasis> be initialised with an explicit list of the servers
+                    in a cluster, but this is not flexible or maintainable as servers are added or
+                    removed from the cluster.</para>
+            </listitem>
+            <listitem>
+                <para>Discovery by other servers. Servers in a cluster want to be able to create
+                    cluster connections to each other without having prior knowledge of all the
+                    other servers in the cluster. </para>
+            </listitem>
+        </itemizedlist>
+        <para>Server discovery uses <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol"
+                >UDP</ulink> multicast to broadcast server connection settings. If UDP is disabled
+            on your network you won't be able to use this, and will have to specify servers
+            explicitly when setting up a cluster or using a messaging client.</para>
+        <section id="clusters.broadcast-groups">
+            <title>Broadcast Groups</title>
+            <para>A broadcast group is the means by which a server broadcasts connectors over the
+                network. A connector defines a way in which a client (or other server) can make
+                connections to the server. For more information on what a connector is please see
+                chapter [LINK].</para>
+            <para>The broadcast group takes a set of connector pairs, each connector pair containing
+                connection settings for a live and (optional) backup server and broadcasts them on
+                the network. It also defines the UDP address and port settings. </para>
+            <para>Broadcast groups are defined in the server configuration file <literal
+                    >jbm-configuration.xml</literal>. There can be many broadcast groups per JBoss
+                Messaging server. All broadcast groups must be defined in a <literal
+                    >broadcast-groups</literal> element.</para>
+            <para>Let's take a look at an example broadcast group from <literal
+                    >jbm-configuration.xml</literal>:</para>
+            <programlisting>&lt;broadcast-groups>
+   &lt;broadcast-group name="my-broadcast-group">
+      &lt;local-bind-port>54321&lt;/local-bind-port>
+      &lt;group-address>231.7.7.7&lt;/group-address>
+      &lt;group-port>9876&lt;/group-port>
+      &lt;broadcast-period>1000&lt;/broadcast-period>
+      &lt;connector-ref connector-name="netty-connector" backup-connector-name="backup-connector"/>
+   &lt;/broadcast-group>
+&lt;/broadcast-groups></programlisting>
+            <para>Some of the broadcast group parameters are optional and you'll normally use the
+                defaults, but we specify them all in the above example for clarity. Let's discuss
+                each one in turn:</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>name</literal> attribute. Each broadcast group in the server must
+                        have a unique name. </para>
+                </listitem>
+                <listitem>
+                    <para><literal>local-bind-address</literal>. TODO. This is the local bind
+                        address that the datagram socket is bound to. If you have multiple network
+                        interfaces on your server, you would specify which one you wish to use for
+                        broadcasts by setting this property. If this property is not specified then
+                        TODO TODO</para>
+                </listitem>
+                <listitem>
+                    <para><literal>local-bind-port</literal>. If you want to specify a local port to
+                        which the datagram socket is bound you can specify it here. Normally you
+                        would just use the default value of <literal>-1</literal> which signifies
+                        that an anonymous port should be used.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>group-address</literal>. This is the multicast address to which
+                        the data will be broadcast. It is a class D IP address in the range
+                        224.0.0.0 to 239.255.255.255, inclusive. The address 224.0.0.0 is reserved
+                        and is not available for use. This parameter is mandatory.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>group-port</literal>. This is the UDP port number used for
+                        broadcasting. This parameter is mandatory.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>broadcast-period</literal>. This is the period in milliseconds
+                        between consecutive broadcasts. This parameter is optional, the default
+                        value is <literal>1000</literal> milliseconds.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>connector-ref</literal>. This specifies the connector and
+                        optional backup connector that will be broadcast. Please see section [LINK]
+                        for more information on connectors. The connector to be broadcast is
+                        specified by the <literal>connector-name</literal> attribute, and the backup
+                        connector to be broadcast is specified by the <literal
+                            >backup-connector</literal> attribute. The <literal
+                            >backup-connector</literal> attribute is optional.</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section id="clusters.discovery-groups">
+            <title>Discovery Groups</title>
+            <para>While the broadcast group defines who connector information is broadcast from a
+                server, a discovery group defines how connector information is received from a
+                multicast address.</para>
+            <para>A discovery group maintains a list of connector pairs - one for each broadcast by
+                a different server. As it receives broadcasts on the multicast group address from a
+                particular server it updates its entry in the list for that server.</para>
+            <para>If it has not received a broadcast from a particular server for a length of time
+                it will remove that server's entry from its list.</para>
+            <para>Discovery groups are used in two places in JBoss Messaging:</para>
+            <itemizedlist>
+                <listitem>
+                    <para>By cluster connections so they know what other servers in the cluster they
+                        should make connections to.</para>
+                </listitem>
+                <listitem>
+                    <para>By messaging clients so they can discovery what servers in the cluster
+                        that they can connect to.</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section>
+            <title>Defining Discovery Groups on the Server</title>
+            <para>For cluster connections, discovery groups are defined in the server side
+                configuration file <literal>jbm-configuration.xml</literal>. All discovery groups
+                must be defined inside a <literal>discovery-groups</literal> element. There can be
+                many discovery groups defined by JBoss Messaging server. Let's look at an
+                example:</para>
+            <programlisting>&lt;discovery-groups>
+   &lt;discovery-group name="my-discovery-group">
+      &lt;group-address>231.7.7.7&lt;/group-address>
+      &lt;group-port>9876&lt;/group-port>
+      &lt;refresh-timeout>10000&lt;/refresh-timeout>
+   &lt;/discovery-group>
+&lt;/discovery-groups></programlisting>
+            <para>We'll consider each parameter of the discovery group:</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>name</literal> attribute. Each discovery group must have a unique
+                        name per server.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>group-address</literal>. This is the multicast ip address of the
+                        group to listen on. It should match the <literal>group-address</literal> in
+                        the broadcast group that you wish to listen from. This parameter is
+                        mandatory.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>group-port</literal>. This is the UDP port of the multicast
+                        group. It should match the <literal>group-port</literal> in the broadcast
+                        group that you wish to listen from. This parameter is mandatory.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>refresh-timeout</literal>. This is the period the discovery group
+                        waits after receiving the last broadcast from a particular server before
+                        removing that servers connector pair entry from its list. You would normally
+                        set this to a value significantly higher than the <literal
+                            >broadcast-period</literal> on the broadcast group otherwise servers
+                        might intermittently disappear from the list even though they are still
+                        broadcasting due to slight differences in timing. This parameter is
+                        optional, the default value is <literal>10000</literal> milliseconds (10
+                        seconds).</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section id="clusters-discovery.groups.clientside">
+            <title>Discovery Groups on the Client Side</title>
+            <para>Let's discuss how to configure a JBoss Messaging client to use discovery to
+                discover a list of servers to which it can connect. The way to do this differs
+                depending on whether you're using JMS or the core API.</para>
+            <section>
+                <title>Configuring client discovery using JMS</title>
+                <para>If you're using JMS and you're also using the JMS Service on the server to
+                    load your JMS connection factory instances into JNDI, then you can specify which
+                    discovery group to use for your JMS connection factory in the server side xml
+                    configuration <literal>jbm-jms.xml</literal>. Let's take a look at an
+                    example:</para>
+                <programlisting>&lt;connection-factory name="ConnectionFactory">
+   &lt;discovery-group-ref discovery-group-name="my-discovery-group"/>
+    &lt;entries>
+       &lt;entry name="ConnectionFactory"/>
+    &lt;/entries>
+&lt;/connection-factory></programlisting>
+                <para>The element <literal>discovery-group-ref</literal> specifies the name of a
+                    discovery group defined in <literal>jbm-configuration.xml</literal>.</para>
+                <para>When this connection factory is downloaded from JNDI by a client application
+                    and JMS connections are created from it, those connections will be load-balanced
+                    across the list of servers that the discovery group maintains by listening on
+                    the multicast address specified in the discovery group configuration. For more
+                    information on client side connection load balancing please see [LINK].</para>
+                <para>If you're using JMS, but you're not using JNDI to lookup a connection factory
+                    - you're instantiating the JMS connection factory directly then you can specify
+                    the discovery group parameters directly when creating the JMS connection
+                    factory. Here's an
+                    example:<programlisting>final String groupAddress = "231.7.7.7";
+
+final int groupPort = 9876;
+
+ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(groupAddress, groupPort);
+
+Connection jmsConnection1 = jmsConnectionFactory.createConnection();
+
+Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting></para>
+                <para>The <literal>refresh-timeout</literal> can be set directly on the connection
+                    factory by using the setter method <literal>setDiscoveryRefreshTimeout() if you
+                        want to change the default value.</literal></para>
+                <para>There is also a further parameter settable on the connection factory using the
+                    setter method <literal>setInitialWaitTimeout()</literal>. If the connection
+                    factory is used immediately after creation then it may not have had enough time
+                    to received broadcasts from all the nodes in the cluster. On first usage, the
+                    connection factory will make sure it waits this long since creation before
+                    creating the first connection. The default value for this parameter is <literal
+                        >2000</literal> milliseconds.</para>
+            </section>
+            <section>
+                <title>Configuring client discovery using Core</title>
+                <para>If you're using the core API to directly instantiate <literal
+                        >ClientSessionFactory</literal> instances, then you can specify the
+                    discovery group parameters directly when creating the session factory. Here's an
+                    example:final String groupAddress = "231.7.7.7"; final int groupPort = 9876;
+                    SessionFactory factory = new ClientSessionFactoryImpl(groupAddress, groupPort);
+                    ClientSession session1 = factory.createClientSession(...); ClientSession
+                    session2 = factory.createClientSession(...); </para>
+                <para>The <literal>refresh-timeout</literal> can be set directly on the session
+                    factory by using the setter method <literal>setDiscoveryRefreshTimeout() if you
+                        want to change the default value.</literal></para>
+                <para>There is also a further parameter settable on the session factory using the
+                    setter method <literal>setInitialWaitTimeout()</literal>. If the session factory
+                    is used immediately after creation then it may not have had enough time to
+                    received broadcasts from all the nodes in the cluster. On first usage, the
+                    session factory will make sure it waits this long since creation before creating
+                    the first session. The default value for this parameter is <literal
+                        >2000</literal> milliseconds.</para>
+            </section>
+        </section>
+    </section>
+    <section>
+        <title>Server-Side Message Load Balancing</title>
+        <para>If cluster connections are defined between nodes of a cluster, then JBoss Messaging
+            will load balance messages arriving from at a particular node from a client.</para>
+        <para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a
+            symmetric cluster [LINK]. We have a queue called <literal>OrderQueue</literal> deployed
+            on each node of the cluster.</para>
+        <para>We have client Ca connected to node A, sending orders to the server. We have also have
+            order processor clients Pa, Pb, Pc, and Pd connected to each of the nodes A, B, C, D. If
+            no cluster connection was defined on node A, then as order messages arrive on node A
+            they will all end up in the <literal>OrderQueue</literal> on node A, so will only get
+            consumed by the order processor client attached to node A, Pa.</para>
+        <para>If we define a cluster connection on node A, then as order messages arrive on node A
+            instead of all of them going into the local <literal>OrderQueue</literal> instance, they
+            are distributed in a round-robin fashion between all the nodes of the cluster. The
+            messages are forwarded from the receiving node to other nodes of the cluster. This is
+            all done on the server side, the client maintains a single connection to node A.</para>
+        <para>For example, messages arriving on node A might be distributed in the following order
+            between the nodes: B, D, C, A, B, D, C, A, B, D. The exact order depends on the order
+            the nodes started up, but the algorithm used is round robin.</para>
+        <para>JBoss Messaging cluster connections can be configured to always blindly load balance
+            messages in a round robin fashion irrespective of whether there are any matching
+            consumers on other nodes, but they can be a bit cleverer than that and also be
+            configured to only distribute to other nodes if they have matching consumers. We'll look
+            at both these cases in turn with some examples, but first we'll discuss configuring
+            cluster connections in general.</para>
+        <section id="clusters.cluster-connections">
+            <title>Configuring Cluster Connections</title>
+            <para>Cluster Connections group servers into clusters so that messages can be load
+                balanced between the nodes of the cluster. Let's take a look at a typical cluster
+                connection. Cluster connections are always defined in <literal
+                    >jbm-configuration.xml</literal> inside a <literal>cluster-connection</literal>
+                element. There can be zero or more cluster connections defined per JBoss Messaging
+                server.</para>
+            <programlisting>
+&lt;cluster-connections&gt;
+    &lt;cluster-connection name="my-cluster"&gt;
+        &lt;address&gt;jms&lt;/address&gt;
+        &lt;retry-interval&gt;500&lt;/retry-interval&gt;
+        &lt;use-duplicate-detection&gt;true&lt;/use-duplicate-detection&gt;
+        &lt;forward-when-no-consumers&gt;false&lt;/forward-when-no-consumers&gt;
+        &lt;max-hops&gt;1&lt;/max-hops&gt;
+        &lt;discovery-group-ref discovery-group-name="my-discovery-group"/&gt;
+    &lt;/cluster-connection&gt;
+&lt;/cluster-connections&gt;                
+            </programlisting>
+            <para>In the above cluster connection all parameters have been explicitly specified. In
+                practice you might use the defaults for some.</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>address</literal>. Each cluster connection only applies to
+                        messages sent to an address that starts with this value.</para>
+                    <para>In this case, this cluster connection will load balance messages sent to
+                        address that start with <literal>jms</literal>. This cluster connection,
+                        will, in effect apply to all JMS Queue and topic subscriptions since they
+                        map to core queues that start with the substring "jms"</para>
+                    <para>The address can be any value and you can have many cluster connections
+                        with different values of <literal>address</literal>, simultaneously
+                        balancing messages for those addresses, potentially to different clusters of
+                        servers. By having multiple cluster connections on different addresses a
+                        single JBoss Messaging Server can effectively take part in multiple clusters
+                        simultaneously.</para>
+                    <para>By careful not to have multiple cluster connections with overlapping
+                        values of <literal>address</literal>, e.g. "europe" and "europe.news" since
+                        this could result in the same messages being distributed between more than
+                        one cluster connection, possibly resulting in duplicate deliveries. </para>
+                    <para>This parameter is mandatory.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>retry-interval</literal>. We mentioned before that, internally,
+                        cluster connections cause bridges to be created between the nodes of the
+                        cluster. If the cluster connection is created and the target node has not
+                        been started, or say, is being rebooted, then the cluster connections from
+                        other nodes will retry connecting to the target until it comes back up, in
+                        the same way as a bridge does.</para>
+                    <para>This parameter determines the interval in milliseconds between retry
+                        attempts. It has the same meaning as the <literal>retry-interval</literal>
+                        on a bridge [LINK].</para>
+                    <para>This parameter is optional and its default value is <literal>500</literal>
+                        milliseconds.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>use-duplicate-detection</literal>. Internally cluster connections
+                        use bridges to link the nodes, and bridges can be configured to add a
+                        duplicate id property in each message that is forwarded. If the target node
+                        of the bridge crashes and then recovers, messages might be resent from the
+                        source node. By enabling duplicate detection any duplicate messages will be
+                        filtered out and ignored on receipt at the target node.</para>
+                    <para>This parameter has the same meaning as <literal
+                            >use-duplicate-detection</literal> on a bridge. For more information on
+                        duplicate detection please see chapter [LINK].</para>
+                    <para>This parameter is optional and has a default value of <literal
+                            >true</literal>.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>forward-when-no-consumers</literal>. This parameter determines
+                        whether messages will be distributed round robin between other nodes of the
+                        cluster <emphasis>irrespective</emphasis> of whether there are matching or
+                        indeed any consumers on other nodes. </para>
+                    <para>If this is set to <literal>true</literal> then each incoming message will
+                        be round robin'd even though the same queues on the other nodes of the
+                        cluster may have no consumers at all, or they may have consumers that have
+                        non matching message filters (selectors). Note that JBoss Messaging will
+                            <emphasis>not</emphasis> forward messages to other nodes if there are no
+                            <emphasis>queues</emphasis> of the same name on the other nodes, even if
+                        this parameter is set to <literal>true</literal>.</para>
+                    <para>If this is set to <literal>false</literal> then JBoss Messaging will only
+                        forward messages to other nodes of the cluster if the address to which they
+                        are being forwarded has queues which have consumers, and if those consumers
+                        have message filters (selectors) at least one of those selectors must match
+                        the message.</para>
+                    <para>This parameter is optional, the default value is <literal
+                        >false</literal>.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>max-hops</literal>. When a cluster connection decides the set of
+                        nodes to which it might load balance a message, those nodes do not have to
+                        be directly connected to it via a cluster connection. JBoss Messaging can be
+                        configured to also load balance messages to nodes which might be connected
+                        to it only indirectly with other JBoss Messaging servers as intermediates in
+                        a chain.</para>
+                    <para>This allows JBoss Messaging to be configured in more complex topologies
+                        and still provide message load balancing. We'll discuss this more later in
+                        this chapter.</para>
+                    <para>The default value for this parameter is <literal>1</literal>, which means
+                        messages are only load balanced to other JBoss Messaging serves which are
+                        directly connected to this server. This parameter is optional.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>discovery-group-ref</literal>. This parameter determines which
+                        discovery group is used to obtain the list of other servers in the cluster
+                        that this cluster connection will make connections to. For more information
+                        on discovery groups please see section [LINK].</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+    </section>
+    <section id="clusters.client.loadbalancing">
+        <title>Client-Side Load balancing</title>
+        <para>With JBoss Messaging client-side connection load balancing, subsequent client
+            connections created using a single factory can be made to different nodes of the
+            cluster. This allows connections to spread smoothly across the nodes of a cluster and
+            not be "clumped" on any particular node.</para>
+        <para>The load balancing policy to be used by the client factory is configurable. JBoss
+            Messaging provides two out-of-the-box load balancing policies and you can also implement
+            your own and use that.</para>
+        <para>The out-of-the-box policies are</para>
+        <itemizedlist>
+            <listitem>
+                <para>Round Robin. With this policy the first node is chosen randomly then each
+                    subsequent node is chosen sequentially in the same order.</para>
+                <para>For example nodes might be chosen in the order B, C, D, A, B, C, D, A, B or D,
+                    A, B, C, A, B, C, D, A or C, D, A, B, C, D, A, B, C, D, A.</para>
+            </listitem>
+            <listitem>
+                <para>Random. With this policy each node is chosen randomly.</para>
+            </listitem>
+        </itemizedlist>
+        <para>You can also implement your own policy by implementing the interface <literal
+                >org.jboss.messaging.core.client.ConnectionLoadBalancingPolicy</literal></para>
+        <para>Specifying which load balancing policy to use differs whether you are using JMS or the
+            core API. If you don't specify a policy then the default will be used which is <literal
+                >org.jboss.messaging.core.client.impl.RoundRobinConnectionLoadBalancingPolicy</literal>.</para>
+        <para>If you're using JMS, and you're using JNDI on the server to put your JMS connection
+            factories into JNDI, then you can specify the load balancing policy directly in the
+                <literal>jbm-jms.xml</literal> configuration file on the server as follows:
+            <programlisting>
+&lt;connection-factory name="ConnectionFactory"&gt;
+    &lt;discovery-group-ref discovery-group-name="my-discovery-group"/&gt;
+    &lt;entries&gt;
+        &lt;entry name="ConnectionFactory"/&gt;
+    &lt;/entries&gt;
+            &lt;connection-load-balancing-policy-class-name&gt;org.jboss.messaging.core.client.impl.RandomConnectionLoadBalancingPolicy&lt;/connection-load-balancing-policy-class-name&gt;
+&lt;/connection-factory&gt;            
+        </programlisting>
+            The above example would deploy a JMS connection factory that uses the random connection
+            load balancing policy. </para>
+        <para>If you're using JMS but you're instantiating your connection factory directly on the
+            client side then you can set the load balancing policy using the setter on the <literal
+                >JBossConnectionFactory</literal> before using it:
+            <programlisting>
+ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(...);
+jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+        </programlisting></para>
+        <para>If you're using the core API, you can set the load balancing policy directly on the
+                <literal>ClientSessionFactory</literal> instance you are using:
+            <programlisting>
+ClientSessionFactory factory = new ClientSessionFactoryImpl(...);
+factory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+            </programlisting></para>
+        <para>The set of servers over which the factory load balances can be determined in one of
+            two ways:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Specifying servers explicitly TODO TODO</para>
+            </listitem>
+            <listitem>
+                <para>Using discovery. Please see section [LINK] for an explanation on how to
+                    configure clients to use server discovery for discovering the list of servers to
+                    connect to.</para>
+            </listitem>
+        </itemizedlist>
+        <para/>
+    </section>
+    <section>
+        <title>Specifying Members of a Cluster Explicitly</title>
+        <para>Sometimes UDP is not enabled on a network so it's not possible to use UDP server
+            discovery for clients to discover the list of servers in the cluster, or for servers to
+            discover what other servers are in the cluster.</para>
+        <para>In this case, the list of servers in the cluster can be specified explicitly on each
+            node and on the client side. Let's look at how we do this:</para>
+        <section>
+            <title>Specify List of Servers on the Client Side</title>
+            <para>This differs depending on whether you're using JMS or the Core API</para>
+            <section>
+                <title>Specifying List of Servers using JMS</title>
+                <para>If you're using JMS, and you're using the JMS Service to load your JMS
+                    connection factory instances directly into JNDI on the server, then you can
+                    specify the list of servers in the server side configuration file <literal
+                        >jbm-jms.xml</literal>. Let's take a look at an example:</para>
+                <programlisting>&lt;connection-factory name="ConnectionFactory">
+   &lt;connector-ref connector-name="my-connector1" backup-connector-name="my-backup-connector1"/>
+   &lt;connector-ref connector-name="my-connector2" backup-connector-name="my-backup-connector2"/>
+   &lt;connector-ref connector-name="my-connector3" backup-connector-name="my-backup-connector3"/>
+   &lt;entries>
+      &lt;entry name="ConnectionFactory"/>
+   &lt;/entries>
+&lt;/connection-factory></programlisting>
+                <para>The <literal>connection-factory</literal> element can contain zero or more
+                        <literal>connector-ref</literal> elements, each one of which specifies a
+                        <literal>connector-name</literal> attribute and an optional <literal
+                        >backup-connector-name</literal> attribute. The <literal
+                        >connector-name</literal> attribute references a connector defined in
+                        <literal>jbm-configuration.xml</literal> which will be used as a live
+                    connector. The <literal>backup-connector-name</literal> is optional, and if
+                    specified it also references a connector defined in <literal
+                        >jbm-configuration.xml</literal>. For more information on connectors please
+                    see chapter [LINK].</para>
+                <para>The connection factory thus maintains a list of [connector, backup connector]
+                    pairs, these pairs are then used by the client connection load balancing policy
+                    on the client side when creating connections to the cluster.</para>
+                <para>If you're using JMS but you're not using JNDI then you can also specify the
+                    list of [connector, backup connector] pairs directly when instantiating the
+                        <literal>JBossConnectionFactory</literal>, here's an
+                    example:<programlisting>List&lt;Pair&lt;TransportConfiguration, TransportConfiguration>> serverList = new ArrayList&lt;Pair&lt;TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC2, backupTC2));
+
+ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(serverList);
+
+Connection jmsConnection1 = jmsConnectionFactory.createConnection();
+
+Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting></para>
+                <para>In the above snippet we create a list of pairs of <literal
+                        >TransportConfiguration</literal> objects. Each <literal
+                        >TransportConfiguration</literal> object contains knowledge of how to make a
+                    connection to a specific server. For more information on this please see the
+                    chapter on connectors [LINK].</para>
+                <para>A <literal>JBossConnectionFactory</literal> instance is then created passing
+                    the list of servers in the constructor. Any connections subsequently created by
+                    this factory will create connections according to the client connection load
+                    balancing policy applied to that list of servers.</para>
+            </section>
+            <section>
+                <title>Specifying List of Servers using the Core API</title>
+                <para>If you're using the Core API you can also specify the list of servers directly
+                    when creating the <literal>ClientSessionFactory</literal> instance. Here's an
+                    example:</para>
+                <programlisting>List&lt;Pair&lt;TransportConfiguration, TransportConfiguration>> serverList = new ArrayList&lt;Pair&lt;TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair&lt;TransportConfiguration, TransportConfiguration>(liveTC2, backupTC2));
+
+ClientSessionFactory factory = new ClientSessionFactoryImpl(serverList);
+
+ClientSession sesison1 = factory.createClientSession(...);
+
+ClientSession session2 = factory.createClientSession(...);</programlisting>
+                <para>In the above snippet we create a list of pairs of <literal
+                        >TransportConfiguration</literal> objects. Each <literal
+                        >TransportConfiguration</literal> object contains knowledge of how to make a
+                    connection to a specific server. For more information on this please see the
+                    chapter on connectors [LINK].</para>
+                <para>A <literal>ClientSessionFactoryImpl</literal> instance is then created passing
+                    the list of servers in the constructor. Any sessions subsequently created by
+                    this factory will create sessions according to the client connection load
+                    balancing policy applied to that list of servers.</para>
+            </section>
+        </section>
+        <section>
+            <title>Specifying List of Servers to form a Cluster</title>
+            <para>Let's take a look at an example where each cluster connection is defined for a
+                symmetric cluster, but we're not using discovery for each node to discover its
+                neighbours, instead we'll configure each cluster connection to have explicit
+                knowledge of all the other nodes in the cluster.</para>
+            <para>Here's an example cluster connection definition showing that:</para>
+            <programlisting>&lt;cluster-connections&gt;
+    &lt;cluster-connection name="my-explicit-cluster"&gt;
+        &lt;address&gt;jms&lt;/address&gt;
+        &lt;connector-ref connector-name="my-connector1" backup-connector-name="my-backup-connector1"/>
+        &lt;connector-ref connector-name="my-connector2" backup-connector-name="my-backup-connector2"/>
+        &lt;connector-ref connector-name="my-connector3" backup-connector-name="my-backup-connector3"/>
+    &lt;/cluster-connection&gt;
+&lt;/cluster-connections&gt;</programlisting>
+            <para>The <literal>cluster-connection</literal> element can contain zero or more
+                    <literal>connector-ref</literal> elements, each one of which specifies a
+                    <literal>connector-name</literal> attribute and an optional <literal
+                    >backup-connector-name</literal> attribute. The <literal
+                    >connector-name</literal> attribute references a connector defined in <literal
+                    >jbm-configuration.xml</literal> which will be used as a live connector. The
+                    <literal>backup-connector-name</literal> is optional, and if specified it also
+                references a connector defined in <literal>jbm-configuration.xml</literal>. For more
+                information on connectors please see chapter [LINK].</para>
+        </section>
+    </section>
+    <section>
+        <title>Message Redistribution</title>
+        <para>Another important part of clustering is message redistribution. Earlier we learned how
+            server side message load balancing round robins messages across the cluster. If <literal
+                >forward-when-no-consumers</literal> is false, then messages won't be forwarded to
+            nodes which don't have matching consumers, this is great and ensures that messages don't
+            arrive on a queue which has no consumers to consume them, however there is a situation
+            it doesn't solve: What happens if the consumers on a queue close after the messages have
+            been sent to the node? If there are no consumers on the queue the message won't get
+            consumed and we have a <emphasis>starvation</emphasis> situation.</para>
+        <para>This is where message redistribution comes in. With message redistribution JBoss
+            Messaging can be configured to automatically <emphasis>redistribute</emphasis> messages
+            from queues which have no consumers back to other nodes in the cluster which do have
+            matching consumers.</para>
+        <para>Message redistribution can be configured to kick in immediately after the last consumer
+            on a queue is closed, or to wait a configurable delay after the last consumer on a queue
+            is closed before redistributing. By default message redistribution is disabled.</para>
+        <para>Message redistribution can be configured on a per address basis, by specifying the
+            redistribution delay in the address settings, for more information on configuring
+            address settings please see the chapter [LINK].</para>
+        <para>Here's an address settings snippet from <literal>jbm-configuration.xml</literal>
+            showing how message redistribution is enabled for a set of queues:</para>
+        <programlisting>&lt;address-settings>     
+   &lt;address-setting match="jms.#">
+      &lt;redistribution-delay>0&lt;/redistribution-delay>
+   &lt;/address-setting>
+ &lt;/address-settings></programlisting>
+        <para>The above <literal>address-settings</literal> block would set a <literal
+                >redistribution-delay</literal> of <literal>0</literal> for any queue which is bound
+            to an address that starts with "jms.". All JMS queues and topic subscriptions are bound
+            to addresses that start with "jms.", so the above would enable instant (no delay)
+            redistribution for all JMS queues and topic subscriptions.</para>
+        <para>The attribute <literal>match</literal> can be an exact match or it can be a string
+            that conforms to the JBoss Messaging wildcard syntax. <xref linkend="wildcard-syntax"
+            /></para>
+        <para>The element <literal>redistribution-delay</literal> defines the delay in milliseconds
+            after the last consumer is closed on a queue before redistributing messages from that
+            queue to other nodes of the cluster which do have matching consumers. A delay of zero
+            means the messages will be immediately redistributed. A value of <literal>-1</literal>
+            signifies that messages will never be redistributed. The default value is <literal
+                >-1</literal>.</para>
+        <para>It often makes sense to introduce a delay before redistributing as it's a common case
+            that a consumer closes but another one quickly is created on the same queue, in such a
+            case you probably don't want to redistribute immediately since the new consumer will
+            arrive shortly.</para>
+    </section>
+    <section>
+        <title>Cluster topologies</title>
+        <para>JBoss Messaging clusters can be connected together in many different topologies, let's
+            consider the two most common ones here</para>
+        <section>
+            <title>Symmetric cluster</title>
+            <para>A symmetric cluster is probably the most common cluster topology, and you'll be
+                familiar with if you've had experience of JBoss Application Server
+                clustering.</para>
+            <para>With a symmetric cluster every node in the cluster is connected to every other
+                node in the cluster. In other words every node in the cluster is no more than one
+                hop away from every other node.</para>
+            <para>To form a symmetric cluster every node in the cluster defines a cluster connection
+                with the attribute <literal>max-hops</literal> set to <literal>1</literal>.
+                Typically the cluster connection will use server discovery [LINK] in order to know
+                what other servers in the cluster it should connect to, although it is possible to
+                explicitly define each target server too in the cluster connection if, for example,
+                UDP is not available on your network.</para>
+            <para>With a symmetric cluster each node knows about all the queues that exist on all the
+                other nodes and what consumers they have. With this knowledge it can determine how
+                to load balance and redistribute messages around the nodes.</para>
+            <para>DIAGRAM</para>
+        </section>
+        <section>
+            <title>Chain cluster</title>
+            <para>With a chain cluster, each node in the cluster is not connected to every node in
+                the cluster directly, instead the nodes form a chain with a node on each end of the
+                chain and all other nodes just connecting to the previous and next nodes in the
+                chain.</para>
+            <para>An example of this would be a three node chain consisting of nodes A, B and C. Node
+                A is hosted in one network and has many producer clients connected to it sending
+                order messages. Due to corporate policy, the order consumer clients need to be
+                hosted in a different network, and that network is only accessible via a third
+                network. In this setup node B acts as a mediator with no producers or consumers on
+                it. Any order messages arriving on node A will be forwarded to node B, which will in
+                turn forward them to node C where they can get consumed. Node A does not need to
+                directly connect to C, but all the nodes can still act as a part of the
+                cluster.</para>
+            <para>To set up a cluster in this way, node A would define a cluster connection that
+                connects to node B, and node B would define a cluster connection that connects to
+                node C. In this case we only want cluster connections in one direction since we're
+                only moving messages from node A->B->C and never from C->B->A.</para>
+            <para>For this topology we would set <literal>max-hops</literal> to <literal
+                >2</literal>. With a value of <literal>2</literal> the knowledge of what queues and
+                consumers that exist on node C would be propagated from node C to node B to node A.
+                Node A would then know to distribute messages to node B when they arrive, even
+                though node B has no consumers itself, it would know that a further hop away is node
+                C which does have consumers.</para>
+        </section>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/command-buffering.xml (from rev 6908, trunk/docs/user-manual/en/modules/command-buffering.xml)
===================================================================
--- trunk/docs/user-manual/en/command-buffering.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/command-buffering.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="command-buffering">
+    <title>Command Buffering</title>
+    <para>As JBoss Messaging clients send commands to their servers they store each sent command in
+        an in-memory buffer. In the case that connection failure occurs and the client subsequently
+        reconnects to the same server or fails over onto a replica server, as part of the
+        reconnection protocol the server informs the client during reconnection with the id of the
+        last command it successfully received from that client.</para>
+    <para>If the client has sent more commands than were received befor failover it can replay any
+        sent commands from its buffer so that the client and server can reconcile their
+        states.</para>
+    <para>The size of this buffer is configured by the <literal>SendWindowSize</literal> parameter,
+        when the server has received <literal>SendWindowSize</literal> bytes of commands and
+        processed them it will send back a command confirmation to the client, and the client can
+        then free up space in the buffer.</para>
+    <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+        connection factory instances into JNDI then this parameter can be configured in <literal
+            >jbm-jms.xml</literal> using the element <literal>send-window-size</literal> a. If
+        you're using JMS but not using JNDI then you can set these values directly on the <literal
+            >JBossConnectionFactory</literal> instance using the appropriate setter method.</para>
+    <para>If you're using core you can set these values directly on the <literal
+            >ClientSessionFactory</literal> instance using the appropriate setter method.</para>
+    <para>The send window is specified in bytes, and has a default value of <literal
+        >1MiB</literal>.</para>
+    <para>When the send buffer becomes full, any attempts to send more commands from the client will
+        block until the client receives a confirmation from the server and clears out the buffer.
+        Because of the blocking, the command buffer performs a type of <literal>flow
+            control</literal>, preventing the client from overwhelming the server with
+        commands.</para>
+</chapter>

Copied: trunk/docs/user-manual/en/configuration-index.xml (from rev 6908, trunk/docs/user-manual/en/modules/configuration-index.xml)
===================================================================
--- trunk/docs/user-manual/en/configuration-index.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/configuration-index.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,645 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuration-index">
+    <title>Configuration Reference</title>
+    <para>This section is a quick index for looking up configuration. Click on the element name to
+        go to the specific chapter.</para>
+    <section>
+        <title>Server Configuration</title>
+        <section>
+            <title>jbm-configuration.xml</title>
+            <table frame="topbot" border="2">
+                <title>Server Configuration</title>
+                <tgroup cols="4">
+                    <colspec colname="c1" colnum="1"/>
+                    <colspec colname="c2" colnum="2"/>
+                    <colspec colname="c3" colnum="3"/>
+                    <colspec colname="newCol4" colnum="4"/>
+                    <thead>
+                        <row>
+                            <entry>Element Name</entry>
+                            <entry>Element Type</entry>
+                            <entry>Description</entry>
+                            <entry>Default</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>clustered</entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the server is clustered</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry>file-deployment-enabled</entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the server will load configuration from the
+                                configuration files</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="persistence.enabled"
+                                >persistence-enabled</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the server will use the file based journal for
+                                persistence.</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="server.scheduled.thread.pool"
+                                    >scheduled-thread-pool-max-size</link></entry>
+                            <entry>Integer</entry>
+                            <entry>The number of threads that the main scheduled thread pool
+                                has.</entry>
+                            <entry>5</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="server.scheduled.thread.pool"
+                                    >thread-pool-max-size</link></entry>
+                            <entry>Integer</entry>
+                            <entry>The number of threads that the main thread pool has. -1 means no
+                                limit</entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry>security-enabled</entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that security is enabled</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry>security-invalidation-interval</entry>
+                            <entry>Long</entry>
+                            <entry>How long, in milli seconds, to wait before invalidating the
+                                security cache</entry>
+                            <entry>10000</entry>
+                        </row>
+                        <row>
+                            <entry>wild-card-routing-enabled</entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the server supports wild card routing</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="management.core.configuration"
+                                    >management-address</link></entry>
+                            <entry>String</entry>
+                            <entry>The name of the management address to send management messages
+                                too.</entry>
+                            <entry>jbm.management</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="management.notifications.core.configuration"
+                                    >management-notification-address</link></entry>
+                            <entry>String</entry>
+                            <entry>The name of the address that consumers bind to to receive
+                                management notifications</entry>
+                            <entry>jbm.notifications</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="management.replication"
+                                    >management-cluster-password</link></entry>
+                            <entry>String</entry>
+                            <entry>The password used to for replicating management operations
+                                between clustered nodes</entry>
+                            <entry>CHANGE ME!!</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="management.replication"
+                                    >management-request-timeout</link></entry>
+                            <entry>Long</entry>
+                            <entry>How long, in milli seconds, to wait for a reply to a management
+                                request</entry>
+                            <entry>5000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="management.jmx.configuration"
+                                    >jmx-management-enabled</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the management API is available via JMX</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.counters"
+                                    >message-counter-enabled</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that message counters are enabled</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.counters"
+                                    >message-counter-sample-period</link></entry>
+                            <entry>Long</entry>
+                            <entry>The sample period to use for message counters</entry>
+                            <entry>10000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.counters"
+                                    >message-counter-max-day-history</link></entry>
+                            <entry>Integer</entry>
+                            <entry>How many days to keep message counter history</entry>
+                            <entry>10</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="dead.connections"
+                                >connection-scan-period</link></entry>
+                            <entry>Long</entry>
+                            <entry>How often, in milli seconds, to scan for failed connections on
+                                the server </entry>
+                            <entry>1000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="dead.connections"
+                                >connection-ttl-override</link></entry>
+                            <entry>Long</entry>
+                            <entry>If set, this will override how long to keep a connection alive
+                                without receiving a ping. </entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry>transaction-timeout</entry>
+                            <entry>Long</entry>
+                            <entry>How long before a transaction can be removed from the resource
+                                manager after create time</entry>
+                            <entry>60000</entry>
+                        </row>
+                        <row>
+                            <entry>transaction-timeout-scan-period</entry>
+                            <entry>Long</entry>
+                            <entry>How often, in milli seconds, to scan for timeout
+                                transactions</entry>
+                            <entry>1000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.expiry.reaper"
+                                    >message-expiry-scan-period</link></entry>
+                            <entry>Long</entry>
+                            <entry>How often, in milli seconds, to scan for expired messages</entry>
+                            <entry>30000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.expiry.reaper"
+                                    >message-expiry-thread-priority</link></entry>
+                            <entry>Integer</entry>
+                            <entry>The priority of the thread expiring messages</entry>
+                            <entry>3</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="duplicate.id.cache">id-cache-size</link></entry>
+                            <entry>Integer</entry>
+                            <entry>The size of the cache for pre creating message id's</entry>
+                            <entry>2000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="duplicate.id.cache"
+                                >persist-id-cache</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that id's are persisted to the journal</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="queue.activation.timeout"
+                                    >queue-activation-timeout</link></entry>
+                            <entry>Long</entry>
+                            <entry>After failout occurs, this time specifies how long to wait for
+                                consumers to re attach before commencing delivery</entry>
+                            <entry>30000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.live.backup">backup</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that this server is a back up to another node in the a
+                                cluster</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.delivery.count.persistence">
+                                    persist-delivery-count-before-delivery</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the delivery count is persisted before delivery.
+                                False means that this only happens after a message has been
+                                cancelled.</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.live.backup"
+                                    >backup-connector-ref</link></entry>
+                            <entry>String</entry>
+                            <entry>The name of the remoting connector to use for the backup node
+                                when.</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="paging.main.config"
+                                >paging-directory</link></entry>
+                            <entry>String</entry>
+                            <entry>The directory to store paged messages in</entry>
+                            <entry>data/paging</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="paging.main.config"
+                                    >global-page-size</link></entry>
+                            <entry>Long</entry>
+                            <entry>The standard size of a page-file. JBoss Messaging will only read messages when there is enough space to read at least one page file, determined by this value.</entry>
+                            <entry>10 * 1024 * 1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="paging.main.config"
+                                    >paging-max-global-size-bytes</link></entry>
+                            <entry>Long</entry>
+                            <entry>JBoss Messaging enters into global page mode as soon as the total memory consumed by messages hits this value.</entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.bindings.journal"
+                                    >bindings-directory</link></entry>
+                            <entry>String</entry>
+                            <entry>The directory to store the persisted bindings to</entry>
+                            <entry>data/bindings</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.bindings.journal"
+                                    >create-bindings-dir</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the server will create the bindings directory on
+                                start up</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-directory</link></entry>
+                            <entry>String</entry>
+                            <entry>The directory to store the journal files in</entry>
+                            <entry>data/journal</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >create-journal-dir</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>True means that the journal directory will be created</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                >journal-type</link></entry>
+                            <entry>ASYNCIO|NIO</entry>
+                            <entry>What type of journal to use</entry>
+                            <entry>ASYNCIO</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-buffer-reuse-size</link></entry>
+                            <entry>Long</entry>
+                            <entry>The journal will try and re use any buffers smaller than this
+                                size.</entry>
+                            <entry>1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-sync-transactional</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>If true wait for transaction data to be synced to the journal
+                                before returning response to client.</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-sync-non-transactional</link></entry>
+                            <entry>Boolean</entry>
+                            <entry>If true wait for non transaction data to be synced to the journal
+                                before returning response to client.</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-file-size</link></entry>
+                            <entry>Long</entry>
+                            <entry>The size, in bytes, each journal file should be</entry>
+                            <entry>10485760</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-min-files</link></entry>
+                            <entry>Integer</entry>
+                            <entry>How many journal files to pre create</entry>
+                            <entry>2</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring.message.journal"
+                                    >journal-max-aio</link></entry>
+                            <entry>Integer</entry>
+                            <entry>The maximum number of write requests that can be in the AIO queue
+                                at any one time</entry>
+                            <entry>5000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="large.message.configuring"
+                                    >large-messages-directory</link></entry>
+                            <entry>String</entry>
+                            <entry>The directory to store large messages</entry>
+                            <entry>data/largemessages</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="understanding.connectors"
+                                >connectors</link></entry>
+                            <entry>Connector</entry>
+                            <entry>A list of remoting connectors configurations to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="configuring-transports.acceptors"
+                                >acceptors</link></entry>
+                            <entry>Acceptor</entry>
+                            <entry>A list of remoting acceptors to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="clusters.broadcast-groups"
+                                >broadcast-groups</link></entry>
+                            <entry>BroadcastGroup</entry>
+                            <entry>A list of broadcast groups to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="clusters.discovery-groups"
+                                >discovery-groups</link></entry>
+                            <entry>DiscoveryGroup</entry>
+                            <entry>A list of discovery groups to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="diverts">diverts</link></entry>
+                            <entry>Divert</entry>
+                            <entry>A list of diverts to use</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="predefined.queues">queues</link></entry>
+                            <entry>Queue</entry>
+                            <entry>A list of pre configured queues to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="core-bridges">bridges</link></entry>
+                            <entry>Bridge</entry>
+                            <entry>A list of bridges to create</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="clusters.cluster-connections"
+                                    >cluster-connections</link></entry>
+                            <entry>ClusterConnection</entry>
+                            <entry>A list of cluster connections</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry><link linkend="security.settings.roles"
+                                >security-settings</link></entry>
+                            <entry>SecuritySetting</entry>
+                            <entry>A list of security settings</entry>
+                            <entry/>
+                        </row>
+                        <row>
+                            <entry>address-settings</entry>
+                            <entry>AddressSetting</entry>
+                            <entry>A list of address settings</entry>
+                            <entry/>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </section>
+        <section>
+            <title>jbm-jms.xml</title>
+            <table frame="topbot" border="2">
+                <title>JMS Server Configuration</title>
+                <tgroup cols="3">
+                    <colspec colname="c1" colnum="1"/>
+                    <colspec colname="c2" colnum="2"/>
+                    <colspec colname="c3" colnum="3"/>
+                    <thead>
+                        <row>
+                            <entry>Element Name</entry>
+                            <entry>Element Type</entry>
+                            <entry>Description</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry><link linkend="using-jms.server.configuration"
+                                    >connection-factory</link></entry>
+                            <entry>ConnectionFactory</entry>
+                            <entry>A list of connection factories to create and add to JNDI</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="using-jms.server.configuration"
+                                >queue</link></entry>
+                            <entry>Queue</entry>
+                            <entry>A queue to create and add to JNDI</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="using-jms.server.configuration"
+                                >topic</link></entry>
+                            <entry>Topic</entry>
+                            <entry>A topic to create and add to JNDI</entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </section>
+    </section>
+    <section>
+        <title>Client Configuration</title>
+        <section>
+            <title>Client Session Factory API Configuration</title>
+            <table frame="topbot" border="2">
+                <title>Client Session Factory API</title>
+                <tgroup cols="4">
+                    <colspec colname="c1" colnum="1"/>
+                    <colspec colname="c2" colnum="2"/>
+                    <colspec colname="c3" colnum="3"/>
+                    <colspec colname="c4" colnum="4"/>
+                    <thead>
+                        <row>
+                            <entry>Parameter</entry>
+                            <entry>Parameter Type</entry>
+                            <entry>Description</entry>
+                            <entry>Default</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry><link linkend="clusters-discovery.groups.clientside"
+                                    >discoveryRefreshTimeout</link></entry>
+                            <entry>long</entry>
+                            <entry>The timeout, in milli seconds, to when discovering. </entry>
+                            <entry>10000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="dead.connections">pingPeriod</link></entry>
+                            <entry>long</entry>
+                            <entry>The period, in milli seconds, </entry>
+                            <entry>1000000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="dead.connections">connectionTTL</link></entry>
+                            <entry>long</entry>
+                            <entry>The time to live for connections</entry>
+                            <entry>5 * 60000</entry>
+                        </row>
+                        <row>
+                            <entry>callTimeout</entry>
+                            <entry>long</entry>
+                            <entry>the time out, in milliseconds, for remote calls</entry>
+                            <entry>30000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="connection-ttl.session.multiplexing"
+                                    >maxConnections</link></entry>
+                            <entry>int</entry>
+                            <entry>The max number of connections per factory</entry>
+                            <entry>8</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="large-messages.core.config"
+                                    >minLargeMessageSize</link></entry>
+                            <entry>int</entry>
+                            <entry>The size, in bytes, before a message is treated as large </entry>
+                            <entry>100 * 1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="flow-control.core.api"
+                                >consumerWindowSize</link></entry>
+                            <entry>int</entry>
+                            <entry>The window size, in bytes, for consumer flow control</entry>
+                            <entry>1024 * 1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="flow-control.rate.core.api"
+                                >consumerMaxRate</link></entry>
+                            <entry>int</entry>
+                            <entry>The fastest rate a consumer may consume messages per
+                                second</entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry>producerWindowSize</entry>
+                            <entry>int</entry>
+                            <entry>The window size for sending messages</entry>
+                            <entry>1024 * 1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="flow-control.producer.rate.core.api"
+                                    >producerMaxRate</link></entry>
+                            <entry>int</entry>
+                            <entry>The max messages per second that can be sent</entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="send-guarantees.nontrans.acks"
+                                    >blockOnAcknowledge</link></entry>
+                            <entry>boolean</entry>
+                            <entry>Whether or not we acknowledge messages synchronously</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="non-transactional-sends"
+                                    >blockOnPersistentSend</link></entry>
+                            <entry>boolean</entry>
+                            <entry>Whether or not we send persistent messages synchronously</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="non-transactional-sends"
+                                    >blockOnNonPersistentSend</link></entry>
+                            <entry>boolean</entry>
+                            <entry>Whether or not we send non persistent messages
+                                synchronously</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry>autoGroup</entry>
+                            <entry>boolean</entry>
+                            <entry>Whether or not we auto group on queues</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry>preAcknowledge</entry>
+                            <entry>boolean</entry>
+                            <entry>Whether messages are pre acknowledged by the server before
+                                sending</entry>
+                            <entry>false</entry>
+                        </row>
+                        <row>
+                            <entry>ackBatchSize</entry>
+                            <entry>int</entry>
+                            <entry>The batch size for sending acknowledgements</entry>
+                            <entry>1024 * 1024</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="clusters.client.loadbalancing"
+                                    >loadBalancingPolicyClassName</link></entry>
+                            <entry>String</entry>
+                            <entry>The name of the load balancing class</entry>
+                            <entry>org.jboss.messaging.core.client.impl.RoundRobinConnectionLoadBalancingPolicy</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="clusters-discovery.groups.clientside"
+                                    >initialWaitTimeout</link></entry>
+                            <entry>long</entry>
+                            <entry>The initail time to wait, in milli seconds, for discovery groups
+                                to wait for broadcasts</entry>
+                            <entry>2000</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="thread-pooling.client.side"
+                                >useGlobalPools</link></entry>
+                            <entry>boolean</entry>
+                            <entry>Use a global thread pool for threads</entry>
+                            <entry>true</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="thread-pooling.client.side"
+                                    >scheduledThreadPoolMaxSize</link></entry>
+                            <entry>int</entry>
+                            <entry>The size of the scheduled thread pool</entry>
+                            <entry>2</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="thread-pooling.client.side"
+                                    >threadPoolMaxSize</link></entry>
+                            <entry>int</entry>
+                            <entry>The size of the thread pool</entry>
+                            <entry>-1</entry>
+                        </row>
+                        <row>
+                            <entry>retryInterval</entry>
+                            <entry>long</entry>
+                            <entry>The time, in milliseconds, retry a connection after
+                                failing</entry>
+                            <entry>2000</entry>
+                        </row>
+                        <row>
+                            <entry>retryIntervalMultiplier</entry>
+                            <entry>double</entry>
+                            <entry>Used in the calculating the retry interval</entry>
+                            <entry>1d</entry>
+                        </row>
+                        <row>
+                            <entry>reconnectAttempts</entry>
+                            <entry>int</entry>
+                            <entry>The number of attempts to make at reconnecting</entry>
+                            <entry>0</entry>
+                        </row>
+                        <row>
+                            <entry><link linkend="ha.client.automatic"
+                                    >failoverOnServerShutdown</link></entry>
+                            <entry>boolean</entry>
+                            <entry>whether or not to failover on server shutdown</entry>
+                            <entry>false</entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </section>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/configuring-transports.xml (from rev 6908, trunk/docs/user-manual/en/modules/configuring-transports.xml)
===================================================================
--- trunk/docs/user-manual/en/configuring-transports.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/configuring-transports.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,397 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuring-transports">
+    <title>Configuring the Transport</title>
+    <para>JBoss Messaging has a fully pluggable and highly flexible transport layer and defines its
+        own Service Provider Interface (SPI) to make plugging in a new transport provider relatively
+        straightforward.</para>
+    <para>In this chapter we'll describe the concepts required for understanding JBoss Messaging
+        transports and where and how they're configured.</para>
+    <section id="configuring-transports.acceptors">
+        <title>Understanding Acceptors</title>
+        <para>One of the most important concepts in JBoss Messaging transports is the
+                <emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
+            defined in xml in the configuration file <literal
+            >jbm-configuration.xml</literal>.</para>
+        <programlisting>
+&lt;acceptors&gt;                
+    &lt;acceptor name="netty"&gt;
+        &lt;factory-class&gt;org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory&lt;/factory-class&gt;
+        &lt;param key="jbm.remoting.netty.port" value="5446" type="Integer"/&gt;
+    &lt;/acceptor&gt;
+&lt;/acceptors&gt;            
+        </programlisting>
+        <para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can
+            be one or more acceptors defined in the <literal>acceptors</literal> element. There's no
+            upper limit to the number of acceptors per server.</para>
+        <para>Each acceptor defines a way in which connections can be made to the JBoss Messaging
+            server.</para>
+        <para>In the above example we're defining an acceptor that uses Netty to listen for
+            connections at port <literal>5446</literal>. </para>
+        <para>The <literal>acceptor</literal> element contains a sub-element <literal
+                >factory-class</literal>, this element defines the factory used to create acceptor
+            instances. In this case we're using Netty to listen for connections so we use the Netty
+            implementation of an <literal>AcceptorFactory</literal> to do this. Basically, the
+                <literal>factory-class</literal> element determines which pluggable transport we're
+            going to use to do the actual listening.</para>
+        <para>The <literal>acceptor</literal> element can also be configured with zero or more
+                <literal>param</literal> sub-elements. Each <literal>param</literal> element defines
+            a key-value pair. These key-value pairs are used to configure the specific transport,
+            the set of valid key-value pairs depends on the specific transport be used and are
+            passed straight through to the underlying transport.</para>
+        <para>Examples of key-value pairs for a particular transport would be, say, to configure the
+            ip address to bind to, or the port to listen at.</para>
+        <para>Keys are always strings and values can be of type Long, Integer, String or
+            Boolean.</para>
+    </section>
+    <section id="understanding.connectors">
+        <title>Understanding Connectors</title>
+        <para>Whereas acceptors are used on the server to define how we accept connections,
+            connectors are used by a client to define how it connects to a server.</para>
+        <para>Let's look at a connector defined in our <literal>jbm-configuration.xml</literal>
+            file:</para>
+        <programlisting>
+&lt;connectors&gt;
+    &lt;connector name="netty"&gt;
+        &lt;factory-class&gt;org.jboss.messaging.integration.transports.netty.NettyConnectorFactory&lt;/factory-class&gt;
+        &lt;param key="jbm.remoting.netty.port" value="5446" type="Integer"/&gt;
+    &lt;/connector&gt;
+&lt;/connectors&gt;            
+        </programlisting>
+        <para>Connectors can be defined inside an <literal>connectors</literal> element. There can
+            be one or more connectors defined in the <literal>connectors</literal> element. There's
+            no upper limit to the number of connectors per server.</para>
+        <para>You make ask yourself, if connectors are used by the <emphasis>client</emphasis> to
+            make connections then why are they defined on the <emphasis>server</emphasis>? There are
+            a couple of reasons for this:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Sometimes the server acts as a client itself when it connects to another
+                    server, for example when one server is bridged to another, or when a server
+                    takes part in a cluster. In this cases the server needs to know how to connect
+                    to other servers. That's defined by <emphasis>connectors</emphasis>.</para>
+            </listitem>
+            <listitem>
+                <para>If you're using JMS and the server side JMS service to instantiate JMS
+                    ConnectionFactory instances and bind them in JNDI, then when creating the
+                        <literal>JBossConnectionFactory</literal> it needs to know what server that
+                    connection factory will create connections to.</para>
+                <para>That's defined by the <literal>connector-ref</literal> element in the <literal
+                        >jbm-jms.xml</literal>file on the server side. Let's take a look at a
+                    snipped from a <literal>jbm-jms.xml</literal> file that shows a JMS connection
+                    factory that references our netty connector defined in our <literal
+                        >jbm-configuration.xml</literal> file:</para>
+                <programlisting>
+&lt;connection-factory name="ConnectionFactory"&gt;
+    &lt;connector-ref connector-name="netty"/&gt;
+    &lt;entries&gt;
+        &lt;entry name="ConnectionFactory"/&gt;
+        &lt;entry name="XAConnectionFactory"/&gt;
+    &lt;/entries&gt;
+&lt;/connection-factory&gt;                
+            </programlisting>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section id="configuring-transports.client.side">
+        <title>Configuring the transport directly from the client side.</title>
+        <para>How do we configure a core <literal>ClientSessionFactory</literal> with the
+            information that it needs to connect with a server?</para>
+        <para>Connectors are also used indirectly when directly configuring a core <literal
+                >ClientSessionFactory</literal> to directly talk to a server. Although in this case
+            there's no need to define such a connector in the server side configuration, instead we
+            just create the parameters and tell the <literal>ClientSessionFactory</literal> which
+            connector factory to use.</para>
+        <para>Here's an example of creating a <literal>ClientSessionFactory</literal> which will
+            connect directly to the acceptor we defined earlier in this chapter, it uses the
+            standard Netty TCP transport and will try and connect on port 5446 to localhost
+            (default):</para>
+        <programlisting>
+Map&lt;String, Object&gt; connectionParams = new HashMap&lt;String, Object&gt;();
+    
+connectionParams.put(org.jboss.messaging.integration.transports.netty.PORT_PROP_NAME, 5446);
+
+TransportConfiguration transportConfiguration = new TransportConfiguration("org.jboss.messaging.integration.transports.netty.NettyConnectorFactory", connectionParams);
+
+ClientSessionFactory sessionFactory = new ClientSessionFactory(transportConfiguration);
+
+ClientSession session = sessionFactory.createSession(...);
+
+etc                       
+        </programlisting>
+        <para>Similarly, if you're using JMS, you can configure the JMS connection factory directly
+            on the client side without having to define a connector on the server side or define a
+            connection factory in <literal>jbm-jms.xml</literal>:</para>
+        <programlisting>
+Map&lt;String, Object&gt; connectionParams = new HashMap&lt;String, Object&gt;();
+
+connectionParams.put(org.jboss.messaging.integration.transports.netty.PORT_PROP_NAME, 5446);
+
+TransportConfiguration transportConfiguration = new TransportConfiguration("org.jboss.messaging.integration.transports.netty.NettyConnectorFactory", connectionParams);
+
+ConnectionFactory connectionFactory = new JBossConnectionFactory(transportConfiguration);
+
+Connection jmsConnection = connectionFactory.createConnection();
+
+etc                       
+        </programlisting>
+    </section>
+    <section>
+        <title>Configuring the Netty transport</title>
+        <para>Out of the box, JBoss Messaging currently uses <ulink
+                url="http://www.jboss.org/netty/">Netty</ulink>, a high performance low level
+            network library.</para>
+        <para>Our Netty transport can be configured in several different ways; to use old (blocking)
+            Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
+            tunnel over HTTP or HTTPS, on top of that we also provide a servlet transport.</para>
+        <para>We believe this caters for the vast majority of transport requirements.</para>
+        <section>
+            <title>Configuring Netty TCP</title>
+            <para> Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
+                configured to use old blocking Java IO or non blocking Java NIO. We recommend you
+                use the default Java NIO for better scalability. </para>
+            <para>If you're running connections across an untrusted network please bear in mind this
+                transport is unencrypted. You may want to look at the SSL or HTTPS
+                configurations.</para>
+            <para>With the Netty TCP transport all connections are initiated from the client side.
+                I.e. the server does not initiate any connections to the client. This works well
+                with firewall policies that typically only allow connections to be initiated in one
+                direction.</para>
+            <para>All the valid Netty transport keys are defined in the class <literal
+                    >org.jboss.messaging.integration.transports.netty.TransportConstants</literal>.
+                The parameters can be used either with acceptors or connectors. The following
+                parameters can be used to configure Netty for simple TCP:</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.usenio</literal>. If this is <literal
+                            >true</literal> then Java non blocking NIO will be used. If set to
+                            <literal>false</literal> than old blocking Java IO will be used.</para>
+                    <para>We highly recommend that you use non blocking Java NIO. Java NIO does not
+                        maintain a thread per connection so can scale to many more concurrent
+                        connections than with old blocking IO. We recommend the usage of Java 6 for
+                        NIO and the best scalability. The default value for this property is
+                            <literal>true</literal>.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.host</literal>. This specified the host name
+                        or ip address to connect to (when configuring a connector) or to listen on
+                        (when configuring an acceptor). The default value for this property is
+                            <literal>localhost</literal>. Note that if you want your servers
+                        accessible from other nodes, don't bind to localhost!</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.port</literal>. This specified the port to
+                        connect to (when configuring a connector) or to listen on (when configuring
+                        an acceptor). The default value for this property is <literal
+                        >5445</literal>.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.tcpnodelay</literal>. If this is <literal
+                            >true</literal> then <ulink
+                            url="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's
+                            algorithm</ulink> will be enabled. The default value for this property
+                        is <literal>true</literal>.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.tcpsendbuffersize</literal>. This parameter
+                        determines the size of the TCP send buffer in bytes. The default value for
+                        this property is <literal>32768</literal> bytes (32KiB).</para>
+                    <para>TCP buffer sizes should be tuned according to the bandwidth and latency of
+                        your network. Here's a good link that explains the theory behind <ulink
+                            url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>.</para>
+                    <para>In summary TCP send/receive buffer sizes should be calculated as:</para>
+                    <programlisting>
+                        buffer_size = bandwidth * RTT.
+                    </programlisting>
+                    <para>Where bandwidth is in <emphasis>bytes per second</emphasis> and network
+                        round trip time (RTT) is in seconds. RTT can be easily measured using the
+                            <literal>ping</literal> utility.</para>
+                    <para>For fast networks you may want to increase the buffer sizes from the
+                        defaults.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.tcpreceivebuffersize</literal>. This parameter
+                        determines the size of the TCP receive buffer in bytes. The default value
+                        for this property is <literal>32768</literal> bytes (32KiB).</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section>
+            <title>Configuring Netty SSL</title>
+            <para>Netty SSL is similar to the Netty TCP transport but it provides additional
+                security by encrypting TCP connections using the Secure Sockets Layer SSL</para>
+            <para>Please see the examples for a full working example of using Netty SSL.</para>
+            <para>Netty SSL uses all the same properties as Netty TCP but adds the following
+                additional properties:</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.sslenabled</literal>. Must be <literal
+                            >true</literal> to enable SSL.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.keystorepath</literal>. This is the path to
+                        the SSL key store on the client which holds the client certificates.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.keystorepassword</literal>. This is the
+                        password for the client certificate key store on the client.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.truststorepath</literal>. This is the path to
+                        the trusted client certificate store on the server.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.truststorepassword</literal>. This is the
+                        password to the trusted client certificate store on the server.</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section>
+            <title>Configuring Netty HTTP</title>
+            <para>Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios
+                where firewalls only allow HTTP traffice to pass.</para>
+            <para>Please see the examples for a full working example of using Netty HTTP.</para>
+            <para>Netty HTTP uses the same properties as Netty TCP but adds the following additional
+                properties:</para>
+            <itemizedlist>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httpenabled</literal>. Must be <literal
+                            >true</literal> to enable HTTP.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httpclientidletime</literal>. TODO</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httpclientidlescanperiod</literal>.
+                        TODO</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httpresponsetime</literal>. TODO</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httpserverscanperiod</literal>. TODO</para>
+                </listitem>
+                <listitem>
+                    <para><literal>jbm.remoting.netty.httprequiressessionid</literal>. TODO</para>
+                </listitem>
+            </itemizedlist>
+        </section>
+        <section>
+            <title>Configuring Netty Servlet</title>
+            <para>We also provide a Netty servlet transport for use with JBoss Messaging. The
+                servlet transport allows JBoss Messaging traffic to be tunneled over HTTP to a
+                servlet running in a servlet engine which then redirects it to an in-VM JBoss
+                Messaging server.</para>
+            <para>The servlet transport differs from the Netty HTTP transport in that, with the HTTP
+                transport JBoss Messaging effectively acts a web server listening for HTTP traffic
+                on, e.g. port 80 or 8080, whereas with the servlet transport JBM traffic is proxied
+                through a servlet engine which may already be serving web site or other
+                applications. This allows JBoss Messaging to be used where corporate policies may
+                only allow a single web server listening on an HTTP port, and this needs to serve
+                all applications including messaging.</para>
+            <para>Please see the examples for a full working example of the servlet transport being
+                used.</para>
+            <para>To configure a servlet engine to work the Netty Servlet transport we need to do
+                the following things:</para>
+            <itemizedlist>
+                <listitem>
+                    <para>Deploy the servlet. Here's an example web.xml describing a web application
+                        that uses the servlet:</para>
+                    <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+         version="2.4">
+   &lt;context-param>
+      &lt;param-name>serverChannelName&lt;/param-name>
+      &lt;param-value>org.jboss.jbm&lt;/param-value>
+   &lt;/context-param>
+
+    &lt;context-param>
+      &lt;param-name>streaming&lt;/param-name>
+      &lt;param-value>true&lt;/param-value>
+   &lt;/context-param>
+
+   &lt;context-param>
+      &lt;param-name>reconnectTimeout&lt;/param-name>
+      &lt;param-value>3000&lt;/param-value>
+   &lt;/context-param>
+   
+   &lt;listener>
+      &lt;listener-class>org.jboss.netty.channel.socket.http.HttpTunnelingSessionListener&lt;/listener-class>
+   &lt;/listener>
+
+   &lt;listener>
+      &lt;listener-class>org.jboss.netty.channel.socket.http.HttpTunnelingContextListener&lt;/listener-class>
+   &lt;/listener>
+
+   &lt;servlet>
+      &lt;servlet-name>NettyServlet&lt;/servlet-name>
+      &lt;servlet-class>org.jboss.netty.channel.socket.http.HttpTunnelingServlet&lt;/servlet-class>
+   &lt;/servlet>
+
+   &lt;servlet-mapping>
+      &lt;servlet-name>NettyServlet&lt;/servlet-name>
+      &lt;url-pattern>/JBMServlet&lt;/url-pattern>
+   &lt;/servlet-mapping>
+&lt;/web-app>
+</programlisting>
+                </listitem>
+                <listitem>
+                    <para>We also need to add a special Netty invm acceptor on the server side
+                        configuration.</para>
+                    <para>Here's a snippet from the <literal>jbm-configuration.xml</literal> file
+                        showing that acceptor being defined:</para>
+                    <programlisting>                    
+&lt;acceptors>
+
+      &lt;acceptor name="netty-invm">
+         &lt;factory-class>org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory&lt;/factory-class>
+         &lt;param key="jbm.remoting.netty.useinvm" value="true" type="Boolean"/>
+         &lt;param key="jbm.remoting.netty.host" value="org.jboss.jbm" type="String"/>
+      &lt;/acceptor>
+
+&lt;/acceptors>                                         
+                </programlisting>
+                </listitem>
+                <listitem>
+                    <para>Lastly we need a connector for the client, this again will be configured
+                        in the <literal>jbm-configuration.xml</literal> file as such:</para>
+                    <programlisting>&lt;connectors>
+
+      &lt;connector name="netty-servlet">
+         &lt;factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory&lt;/factory-class>
+         &lt;param key="jbm.remoting.netty.host" value="localhost" type="String"/>
+         &lt;param key="jbm.remoting.netty.port" value="8080" type="Integer"/>
+         &lt;param key="jbm.remoting.netty.useservlet" value="true" type="Boolean"/>
+         &lt;param key="jbm.remoting.netty.servletpath" value="/messaging/JBMServlet" type="String"/>
+      &lt;/connector>
+
+ &lt;/connectors></programlisting>
+                </listitem>
+            </itemizedlist>
+            <para>Heres a list of the context params and what they are used for</para>
+            <itemizedlist>
+                <listitem>
+                    <para>serverChannelName - This is the name of the netty acceptor that the
+                        servlet will forward its packets too. You can see it matches the name of the
+                            <literal>jbm.remoting.netty.host</literal> param.</para>
+                </listitem>
+                <listitem>
+                    <para>streaming - set to true means that all packets will be streamed as one
+                        continuous request rather than one request per packet.</para>
+                </listitem>
+                <listitem>
+                    <para>reconnectTimeout - How long in milliseconds the servlet will await for the
+                        client to reconnect after a connection being closed by the web server</para>
+                </listitem>
+            </itemizedlist>
+            <para>The servlet pattern configured in the <literal>web.xml</literal> is the path of
+                the URL that is used. The connector param <literal
+                    >jbm.remoting.netty.servletpath</literal> on the connector config must match
+                this using the application context of the web app if there is one.</para>
+        </section>
+    </section>
+    <section>
+        <title>Writing your own transport</title>
+        <para>TODO</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/connection-ttl.xml (from rev 6908, trunk/docs/user-manual/en/modules/connection-ttl.xml)
===================================================================
--- trunk/docs/user-manual/en/connection-ttl.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/connection-ttl.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="connection-ttl">
+    <title>Dead Connections, Time To Live and Session Multiplexing</title>
+    <para>In this section we will discuss connection time-to-live (TTL) and explain how JBoss
+        Messaging deals with crashed clients and clients which have exited without cleanly closing
+        their resources. We'll also explain how to configure all the related parameters.</para>
+    <section id="dead.connections">
+        <title>Cleaning up Dead Connection Resources on the Server</title>
+        <para>Before a JBoss Messaging client application exits it is considered good practice and
+            part of its contract that it should close its resources in a controlled manager, using a
+                <literal>finally</literal> block.</para>
+        <para>Here's an example of a well behaved core client application closing its session and
+            session factory in a finally block:</para>
+        <programlisting>
+ClientSessionFactory sf = null;
+ClientSession session = null;
+
+try
+{
+   sf = new ClientSessionFactoryImpl(...);
+
+   session = sf.createSession(...);
+   
+   ... do some stuff with the session...
+}
+finally
+{
+   if (session != null)
+   {
+      session.close();
+   }
+   
+   if (sf != null)
+   {
+      sf.close();
+   }
+}
+        </programlisting>
+        <para>And here's an example of a well behaved JMS client application:</para>
+        <programlisting>
+Connection jmsConnection = null;
+
+try
+{
+   ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(...);
+
+   jmsConnection = jmsConnectionFactory.createConnection();
+
+   ... do some stuff with the connection...
+}
+finally
+{
+   if (connection != null)
+   {
+      connection.close();
+   }
+}
+        </programlisting>
+        <para>Unfortunately users don't always write well behaved applications, and sometimes
+            clients crash so they don't have a chance to clean up their resources!</para>
+        <para>If this occurs then it can leave server side resources, e.g. representing the session
+            objects, hanging on the server. If these were not removed somehow then over time this
+            would cause a resource leak on the server.</para>
+        <para>We have to balance this requirement for cleaning up dead client resources with the
+            fact that sometimes the network between the client and the server can fail and then come
+            back, allowing the client to reconnect. JBoss Messaging supports client reconnection, so
+            we don't want to clean up "dead" server side resources too soon or this will prevent any
+            client from reconnecting, as it won't be able to find its old sessions on the
+            server.</para>
+        <para>JBoss Messaging makes all of this configurable. For each <literal
+                >ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
+            Each connection also sends a periodic "ping" to the server, when the server receives the
+            "ping" it sends back "pong". Every time the server receives a ping, it marks the time it
+            received that last ping against the connection. If the server hasn't received a ping for
+            the time given by the TTL, then it will be automatically cleaned up and its server side
+            resources removed. Basically, the TTL determines how long the server will keep a
+            connection alive in the absence of a ping. Normally we configure the TTL to be much
+            larger than the connection ping period so we can allow for session reconnections at
+            significant times later.</para>
+        <para>The ping period is defined by the <literal>PingPeriod</literal> attribute on the
+                <literal>ClientSessionFactory</literal> instance.</para>
+        <para>If you're using JMS it's defined by the <literal>PingPeriod</literal> attribute on a
+                <literal>JBossConnectionFactory</literal> instance, or if you're deploying JMS
+            connection factory instances direct into JNDI on the server side, you can specify it in
+            the xml config, using the parameter <literal>ping-period</literal>.</para>
+        <para>The default value for ping period is <literal>5000</literal>ms, i.e. 5 seconds.</para>
+        <para>The connection TTL is defined by the <literal>ConnectionTTL</literal> attribute on the
+                <literal>ClientSessionFactory</literal> instance.</para>
+        <para>If you're using JMS it's defined by the <literal>ConnectionTTL</literal> attribute on
+            a <literal>JBossConnectionFactory</literal> instance, or if you're deploying JMS
+            connection factory instances direct into JNDI on the server side, you can specify it in
+            the xml config, using the parameter <literal>connection-ttl</literal>.</para>
+        <para>The default value for connection ttl is <literal>300000</literal>ms, i.e. 5
+            minutes.</para>
+        <para>If you do not wish clients to be able to specify their own connection TTL, you can
+            override all values used by a global value set on the server side. This can be done by
+            specifying the <literal>connection-ttl-override</literal> attribute in the server side
+            configuration. The default value for <literal>connection-ttl-override</literal> is
+                <literal>-1</literal> which means "do not override" (i.e. let clients use their own
+            values).</para>
+        <para>There's a thread on the server that periodically checks all the connections to see if
+            they haven't been pinged for time TTL or over. The period between checking connection is
+            determined by the parameter<literal>connection-scan-period</literal> in the file
+                <literal>jbm-configuration.xml</literal>. The default value is <literal
+                >1000</literal>ms.</para>
+    </section>
+    <section>
+        <title>Detecting failure from the client side.</title>
+        <para>In the previous section we discussed how the client sends pings to the server and how
+            "dead" connection resources are cleaned up by the server. There's also another reason
+            for pinging, and that's for the client to be able to detect that the server has
+            failed.</para>
+        <para>Every <literal>pingPeriod</literal> milliseconds a ping is sent to the server, if, by
+            the time the client is ready to send the next ping to the server, the previous pong
+            hasn't arrived then the client will consider the connection failed and will either
+            initiate failover, or call any FailureListener instances (or ExceptionListeners if you
+            are using JMS) depending on how it has been configured.</para>
+        <para/>
+    </section>
+    <section id="connection-ttl.session.multiplexing">
+        <title>Session Multiplexing</title>
+        <para>Each <literal>ClientSessionFactory</literal> creates connections on demand to the same
+            server as you create sessions. Each instance will create up to a maximum of <literal
+                >maxConnections</literal> connections to the same server. Subsequent sessions will
+            use one of the already created connections in a round-robin fashion.</para>
+        <para>To illustrate this, let's say <literal>maxConnections</literal> is set to <literal
+                >8</literal>. The first eight sessions that you create will have a new underlying
+            connection created for them, the next eight you create will use one of the previously
+            created connections.</para>
+        <para>The default value for <literal>maxConnections</literal> is <literal>8</literal>, if
+            you prefer you can set it to a lower value so each factory maintains only one underlying
+            connection. We choose a default value of <literal>8</literal> because on the server side
+            each packet read from a particular connection is read serially by the same thread, so if
+            all traffic from the client's sessions is multiplexed on the same connection it will all
+            be processed by the same thread on the server, which might not be a good use of cores on
+            the server. By choosing <literal>8</literal> then different sessions traffic from the
+            same client can be processed by different cores. If you have many different clients then
+            this may not be relevant anyway.</para>
+        <para>To change the value of <literal>maxConnections</literal> simply use the setter method
+            on the <literal>ClientSessionFactory</literal> immediately after constructing it, or if
+            you are using JMS use the setter on the <literal>JBossConnectionFactory</literal> or
+            specify the <literal>max-connections</literal> parameter in the connection factory xml
+            configuration in <literal>jbm-jms.xml</literal>.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/core-bridges.xml (from rev 6908, trunk/docs/user-manual/en/modules/core-bridges.xml)
===================================================================
--- trunk/docs/user-manual/en/core-bridges.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/core-bridges.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="core-bridges">
+    <title>Core Bridges</title>
+    <para>The function of a bridge is to consume messages from a source queue, and forward them to a
+        target address, typically on a different JBoss Messaging server.</para>
+    <para>The source and target servers do not have to be in the same cluster which makes bridging
+        suitable for reliably sending messages from one cluster to another, for instance across a
+        WAN, and where the connection may be unreliable.</para>
+    <para>The bridge has built in resilience to failure so if the target server connection is lost,
+        e.g. due to network failure, the bridge will retry connecting to the target until it comes
+        back online. When it comes back online it will resume operation as normal.</para>
+    <para>In summary, bridges are a way to reliably connect two separate JBoss Messaging servers
+        together. With a core bridge both source and target servers must be JBoss Messaging
+        servers.</para>
+    <para>Bridges can be configured provide <emphasis>once and only once</emphasis> delivery
+        guarantees even in the event of the failure of the source or the target server. They do this
+        by using duplicate detection. [LINK]</para>
+    <note>
+        <para>Although they have similar function, don't confuse core bridges with JMS
+            bridges!</para>
+        <para>Core bridges are for linking a JBoss Messaging node with another JBoss Messaging node
+            and do not use the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant
+            JMS providers. So,a JMS Bridge could be used for bridging to or from a different JMS
+            compliant messaging system. It's always preferable to use a core bridge if you can. Core
+            bridges use duplicate detection [LINK] to provide <emphasis>once and only
+                once</emphasis> guarantees. To provide the same guarantee using a JMS bridge you
+            would have to use XA which has a higher overhead and is more complex to
+            configure.</para>
+    </note>
+    <section>
+        <title>Configuring Bridges</title>
+        <para>Bridges are configured in <literal>jbm-configuration.xml</literal>. Let's kick off
+            with an example (this is actually from the bridge example):</para>
+        <programlisting>
+&lt;bridge name="my-bridge"&gt;
+    &lt;queue-name&gt;jms.queue.sausage-factory&lt;/queue-name&gt;
+    &lt;forwarding-address&gt;jms.queue.mincing-machine&lt;/forwarding-address&gt;
+    &lt;filter-string="name='aardvark'"/&gt;
+    &lt;transformer-class-name&gt;org.jboss.jms.example.HatColourChangeTransformer&lt;/transformer-class-name&gt;
+    &lt;retry-interval&gt;1000&lt;/retry-interval&gt;
+    &lt;retry-interval-multiplier&gt;1.0&lt;/retry-interval-multiplier&gt;
+    &lt;reconnect-attempts&gt;-1&lt;/reconnect-attempts&gt;
+    &lt;failover-on-server-shutdown&gt;false&lt;/failover-on-server-shutdown&gt;
+    &lt;use-duplicate-detection&gt;true&lt;/use-duplicate-detection&gt;
+    &lt;connector-ref connector-name="remote-connector" backup-connector-name="backup-remote-connector"/&gt;          
+&lt;/bridge&gt;                        
+        </programlisting>
+        <para>Please also note that in order for bridges to be deployed on a server, the <literal>clustered</literal> attribute needs to be set
+        to <literal>true</literal> in <literal>jbm-configuration.xml</literal>.</para>
+        <para>In the above example we should all the parameters its possible to configure for a
+            bridge. In practice you might use many of the defaults so it won't be necessary to
+            specify them all explicitly.</para>
+        <para>Let's take a look at all the parameters in turn:</para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>name</literal> attribute. All bridges must have a unique name in the
+                    server.</para>
+            </listitem>
+            <listitem>
+                <para><literal>queue-name</literal>. This is the unique name of the local queue that
+                    the bridge consumes from, it's a mandatory parameter.</para>
+                <para>The queue must already exist by the time the bridge is instantiated at
+                    start-up.</para>
+                <note>
+                    <para>If you're using JMS then normally the JMS configuration <literal
+                            >jbm-jms.xml</literal>is loaded after the core configuration file
+                            <literal>jbm-configuration.xml</literal> is loaded. If you're bridge is
+                        consuming from a JMS queue then you'll need to make sure the JMS queue is
+                        also deployed as a core queue in the core config. Take a look at the bridge
+                        example for an example of how this is done.</para>
+                </note>
+            </listitem>
+            <listitem>
+                <para><literal>forwarding-address</literal>.This is the address on the target server
+                    that the message will be forwarded to. If a forwarding address is not specified
+                    then the original destination of the message will be retained.</para>
+            </listitem>
+            <listitem>
+                <para><literal>filter-string</literal>. An optional filter string can be supplied.
+                    If specified then only messages which match the filter expression specified in
+                    the filter string will be forwarded. The filter string follows the filter
+                    expression syntax as described in chapter [LINK].</para>
+            </listitem>
+            <listitem>
+                <para><literal>transformer-class-name</literal>. An optional transformer-class-name
+                    can be specified. This is the name of a user-defined class which implements the
+                        <literal>org.jboss.messaging.core.server.cluster.Transformer</literal>
+                    interface.</para>
+                <para>If this is specified then the transformer's <literal>transform()</literal>
+                    method will be invoked with the message before it is forwarded. This gives you
+                    the opportunity to transform the message's header or body before forwarding
+                    it.</para>
+            </listitem>
+            <listitem>
+                <para><literal>retry-interval</literal>. This optional parameter determines the
+                    period in milliseconds between subsequent reconnection attempts, if the
+                    connection to the target server has failed. The default value is <literal
+                        >2000</literal>milliseconds.</para>
+            </listitem>
+            <listitem>
+                <para><literal>retry-interval-multiplier</literal>. This optional parameter
+                    determines determines a multiplier to apply to the time since the last retry to
+                    compute the time to the next retry.</para>
+                <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
+                    between retry attempts.</para>
+                <para>Let's take an example:</para>
+                <para>If we set <literal>retry-interval</literal>to <literal>1000</literal> ms and
+                    we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
+                    then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
+                    ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
+                    subsequent reconnection attempts.</para>
+                <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
+                    spaced at equal intervals.</para>
+            </listitem>
+            <listitem>
+                <para><literal>reconnect-attempts</literal>. This optional parameter determines the
+                    total number of reconnect attempts the bridge will make before giving up and
+                    shutting down. A value of <literal>-1</literal> signifies an unlimited number of
+                    attempts. The default value is <literal>-1</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>failover-on-server-shutdown</literal>. This optional parameter
+                    determines whether the bridge will attempt to failover onto a backup server (if
+                    specified) when the target server is cleanly shutdown rather than
+                    crashed.</para>
+                <para>The bridge connector can specify both a live and a backup server, if it
+                    specifies a backup server and this parameter is set to <literal>true</literal>
+                    then if the target server is <emphasis>cleanly</emphasis> shutdown the bridge
+                    connection will attempt to failover onto its backup. If the bridge connector has
+                    no backup server configured then this parameter has no effect. </para>
+                <para>Sometimes you want a bridge configured with a live and a backup target server,
+                    but you don't want to failover to the backup if the live server is simply taken
+                    down temporarily for maintenance, this is when this parameter comes in
+                    handy.</para>
+                <para>The default value for this parameter is <literal>false</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>use-duplicate-detection</literal>. This optional parameter determines
+                    whether the bridge will automatically insert a duplicate id property into each
+                    message that it forwards.</para>
+                <para>Doing so, allows the target server to perform duplicate detection on messages
+                    it receives from the source server. If the connection fails or server crashes,
+                    then, when the bridge resumes it will resend unacknowledged messages. This might
+                    result in duplicate messages being sent to the target server. By enabling
+                    duplicate detection allows these duplicates to be screened out and
+                    ignored.</para>
+                <para>This allows the bridge to provide a <emphasis>once and only once</emphasis>
+                    delivery guarantee without using heavyweight methods such as XA.</para>
+                <para>For more information on duplicate detection see the chapter [LINK]</para>
+                <para>The default value for this parameter is <literal>true</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>connector-ref</literal>. This mandatory parameter determines which
+                        <emphasis>connector</emphasis> pair the bridge will use to actually make the
+                    connection to the target server.</para>
+                <para>A <emphasis>connector</emphasis> encapsulates knowledge of what transport to
+                    use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port
+                    etc). For more information about what connectors are and how to configure them
+                    please see the chapter [LINK].</para>
+                <para>The <literal>connector-ref</literal> element can be configured with two
+                    attributes:</para>
+                <itemizedlist>
+                    <listitem>
+                        <para><literal>connector-name</literal>. This references the name of a
+                            connector defined in the core configuration file <literal
+                                >jbm-configuration.xml</literal>. The bridge will use this connector
+                            to make its connection to the target server. This attribute is
+                            mandatory.</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>backup-connector-name</literal>. This optional parameter also
+                            references the name of a connector defined in the core configuration
+                            file <literal>jbm-configuration.xml</literal>. It represents the
+                            connector that the bridge will fail-over onto if it detects the live
+                            server connection has failed. If this is specified and <literal
+                                >failover-on-server-shutdown</literal> is set to <literal
+                                >true</literal> then it will also attempt failover onto this
+                            connector if the live target server is cleanly shut-down.</para>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+        </itemizedlist>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/diverts.xml (from rev 6908, trunk/docs/user-manual/en/modules/diverts.xml)
===================================================================
--- trunk/docs/user-manual/en/diverts.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/diverts.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="diverts">
+    <title>Diverting and Duplicating Message Flows</title>
+    <para>JBoss Messaging allows you to configure objects called <emphasis>diverts</emphasis> with some simple server configuration.</para>
+    <para>Diverts allow you to transparently divert messages routed to one address to some other address, without making any changes to any
+    client application logic.</para>
+    <para>Diverts can be <emphasis>exclusive</emphasis>, meaning that that the message is diverted to the new address, and does not go to the old address
+    at all, or they can be <emphasis>non-exclusive</emphasis> which means the message continues to go the old address, and a <emphasis>copy</emphasis> of
+        it is also sent to the new address. Non-exclusive diverts can therefore be used for duplicating message flows, e.g. there may be a requirement to monitor every order sent
+        to an order queue.</para>    
+    <para>Diverts can also be configured to have an optional message filter. If specified then only messages that match the filter will be diverted.</para>
+    <para>Diverts can also be configured to apply a Transformer. If specified, all diverted messages will have the opportunity of being transformed by the Transformer.</para>
+    <para>A divert will only divert a message to an address on the <emphasis>same server</emphasis>, however, if you want to divert to an
+    address on a different server, a common pattern would be to divert to a local store-and-forward queue, then set up a bridge which consumes
+    from that queue and forweards to an address on a different server.</para>                
+    <para>Diverts are therefore a very sophisticated concept, which when combined with bridges can be used to create interesting and complex routings.
+    The set of diverts on a server can be thought of as a type of routing table for messages. Combining diverts with bridges allows you
+    to create a distributed network of reliable routing connections between multiple geographically distributed servers, creating your global
+    messaging mesh.</para>
+    <para>Diverts are defined as xml in the <literal>jbm-configuration.xml</literal> file. There can be zero or more diverts in the file.</para>
+    <para>Please see the divert example [LINK] for a full working example showing you how to configure and use diverts.</para>
+    <para>Let's take a look at some divert examples:</para>
+    <section>
+        <title>Exclusive Divert</title>
+        <para>Let's take a look at an exclusive divert. An exclusive divert diverts all matching messages that are routed to the old address
+        to the new address. Matching messages do not get routed to the old address.</para>
+        <para>Here's some example xml configuration for an exclusive divert, it's taken from the divert example:</para>
+        <programlisting>
+&lt;divert name="prices-divert"&gt;                  
+    &lt;address&gt;jms.topic.priceUpdates&lt;/address&gt;
+    &lt;forwarding-address&gt;jms.queue.priceForwarding&lt;/forwarding-address&gt;    
+    &lt;filter string="office='New York'"/&gt;
+    &lt;transformer-class-name&gt;org.jboss.jms.example.AddForwardingTimeTransformer&lt;/transformer-class-name&gt;     
+    &lt;exclusive&gt;true&lt;/exclusive&gt;
+&lt;/divert&gt;                        
+        </programlisting>
+        <para>We define a divert called '<literal>prices-divert</literal>' that will divert any messages sent to the address
+        '<literal>jms.topic.priceUpdates</literal>' (this corresponds to any messages sent to a JMS Topic called '<literal>priceUpdates</literal>').
+        to another local address '<literal>jms.queue.priceForwarding</literal>' (this corresponds to a local JMS Queue called
+        '<literal>priceForwarding</literal>'</para>
+        <para>We also specify a message filter string so only messages with the message property <literal>office</literal> with value
+        <literal>New York</literal> will get diverted, all other messages will continue to be routed to the normal address. The filter string is
+        optional, if not specified then all messages will be considered matched.</para>
+        <para>In this example a transformer class is specified. Again this is optional, and if specified the transformer will be executed for
+        each matching message. This allows you to change the message's body or properties before it is diverted. In this example the transformer
+        simply adds a header that records the time the divert happened.</para>
+        <para>This example is actually diverting messages to a local store and forward queue, which is configured with a bridge which forwards
+        the message to an address on another JBoss Messaging server. Please see the example for more details.</para>
+    </section>
+    <section>
+        <title>Non-exclusive Divert</title>
+        <para>Now we'll take a look at a non-exclusive divert. Non exclusive diverts are the same as exclusive diverts, but they only forward a 
+        <emphasis>copy</emphasis> of the message to the new address. The original message continues the old address</para>
+        <para>You can therefore think of non-exclusive diverts as <emphasis>duplicating</emphasis> a message flow.</para>
+        <para>Non exclusive diverts can be configured in the same was as exclusive diverts with an optional filter and transformer, here's
+        an example non-exclusive divert, again from the divert example:</para>
+        <programlisting>
+&lt;divert name="order-divert"&gt;                 
+    &lt;address&gt;jms.queue.orders&lt;/address&gt;
+    &lt;forwarding-address&gt;jms.topic.spyTopic&lt;/forwarding-address&gt;         
+    &lt;exclusive&gt;false&lt;/exclusive&gt;
+&lt;/divert&gt;                       
+        </programlisting>
+        <para>The above divert example takes a copy of every message sent to the address '<literal>jms.queue.orders</literal>' (Which
+        corresponds to a JMS Queue called '<literal>orders</literal>') and sends it to a local address called
+        '<literal>jms.topic.SpyTopic</literal>' (which corresponds to a JMS Topic called '<literal>SpyTopic</literal>').</para>
+    </section>
+    
+    
+</chapter>

Copied: trunk/docs/user-manual/en/duplicate-detection.xml (from rev 6908, trunk/docs/user-manual/en/modules/duplicate-detection.xml)
===================================================================
--- trunk/docs/user-manual/en/duplicate-detection.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/duplicate-detection.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="duplicate-detection">
+    <title>Duplicate Message Detection</title>
+    <para>JBoss Messaging includes powerful automatic duplicate message detection, filtering out
+        duplicate messages without you having to code your own fiddly duplicate detection logic at
+        the application level. This chapter will explain what duplicate detection is, how JBoss
+        Messaging uses it and how and where to configure it.</para>
+    <para>When sending messages from a client to a server, or indeed from a server to another
+        server, if the target server or connection fails sometime after sending the message, but
+        before the sender receives a response that the send (or commit) was processed successfully
+        then the sender cannot know for sure if the message was sent successfully to the
+        address.</para>
+    <para>If the target server or connection failed after the send was received and processed but
+        before the response was sent back then the message will have been sent to the address
+        successfully, but if the target server or connection failed before the send was received and
+        finished processing then it will not have been sent to the address successfully. From the
+        senders point of view it's not possible to distinguish these two cases.</para>
+    <para>When the server recovers this leaves the client in a difficult situation. It knows the
+        target server failed, but it does not know if the last message reached its destination ok.
+        If it decides to resend the last message, then that could result in a duplicate message
+        being sent to the address. If each message was an order or a trade then this could result in
+        the order being fulfilled twice or the trade being double booked. This is clearly not a
+        desirable situation.</para>
+    <para>Sending the message(s) in a transaction does not help out either. If the server or
+        connection fails while the transaction commit is being processed it is also indeterminate
+        whether the transaction was successfully committed or not!</para>
+    <para>To solve these issues JBoss Messaging provides automatic duplicate messages detection for
+        messages sent to addresses.</para>
+    <section>
+        <title>Using Duplicate Detection for Message Sending</title>
+        <para>Enabling duplicate message detection for sent messages is simple: you just need to set
+            a property on the message to a unique value. You can create the value however you like,
+            as long as it is unique. When the target server receives the message it will check if
+            that property is set, if it is, then it will check in its in memory cache if it has
+            already received a message with that value of the header. If it has received a message
+            with the same value before then it will ignore the message.</para>
+        <note>
+            <para>Using duplicate detection to move messages between nodes can give you the same
+                    <emphasis>once and only once</emphasis> delivery guarantees as if you were using
+                an XA transaction to consume messages from source and send them to the target, but
+                with less overhead and much easier configuration than using XA.</para>
+        </note>
+        <para>If you're sending messages in a transaction then you don't have to set the property
+            for <emphasis>every</emphasis> message you send in that transaction, you only need to
+            set it once in the transaction. If the server detects a duplicate message for any
+            message in the transaction, then it will ignore the entire transaction.</para>
+        <para>The name of the property that you set is given by the value of <literal
+                >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal>, which
+            is <literal>_JBM_DUPL_ID</literal></para>
+        <para>The value of the property can be of type <literal>byte[]</literal> or <literal
+                >SimpleString</literal> if you're using the core API. If you're using JMS it must be
+            a <literal>String</literal>, and it's valid should be unique. An easy way of generating
+            a unique id is by generating a UUID.</para>
+        <para>Here's an example of setting the property using the core API:</para>
+        <programlisting>
+...     
+
+ClientMessage message = session.createClientMessage(true);
+
+SimpleString myUniqueID = "This is my unique id";   // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
+
+...
+        </programlisting>
+        <para>And here's an example using the JMS API:</para>
+        <programlisting>
+...     
+
+Message jmsMessage = session.createMessage();
+
+String myUniqueID = "This is my unique id";   // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
+
+...
+        </programlisting>
+    </section>
+    <section id="duplicate.id.cache">
+        <title>Configuring the Duplicate ID Cache</title>
+        <para>The server maintains caches of received values of the <literal
+                >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal> property
+            sent to each address. Each address has its own distinct cache.</para>
+        <para>The cache is a circular fixed size cache. If the cache has a maximum size of <literal
+                >n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite
+            the <literal>0</literal>th element in the cache.</para>
+        <para>The maximum size of the cache is configured by the parameter <literal
+                >id-cache-size</literal> in <literal>jbm-configuration.xml</literal>, the default
+            value is <literal>2000</literal> elements.</para>
+        <para>The caches can also be configured to persist to disk or not. This is configured by the
+            parameter <literal>persist-id-cache</literal>, also in <literal
+                >jbm-configuration.xml</literal>. If this is set to <literal>true</literal> then
+            each id will be persisted to permanent storage as they are received. The default value
+            for this parameter is <literal>true</literal>.</para>
+        <note>
+            <para>When choosing a size of the duplicate id cache be sure to set it to a larger
+                enough size so if you resend messages all the previously sent ones are in the cache
+                not having been overwritten.</para>
+        </note>
+    </section>
+    <section>
+        <title>Duplicate Detection and Bridges</title>
+        <para>Core bridges can configured to automatically add a unique duplicate id value (if there
+            isn't already one in the message) before forwarding the message to it's target. This
+            ensures that if the target server crashes or the connection is interrupted and the
+            bridge resends the message, then if it has already been received by the target server,
+            it will be ignored.</para>
+        <para>To configure a core bridge to add the duplicate id header, simply set the <parameter
+                >use-duplicate-detection</parameter> to <literal>true</literal> when configuring a
+            bridge in <literal>jbm-configuration.xml</literal>.</para>
+        <para>The default value for this parameter is <literal>true</literal>.</para>
+        <para>For more information on core bridges and how to configure them see section
+            [LINK]</para>
+    </section>
+    <section>
+        <title>Duplicate Detection and Cluster Connections</title>
+        <para>Cluster connections internally use core bridges to move messages reliable between
+            nodes of the cluster. Consequently they can also be configured to insert the duplicate
+            id header for each message they move using their internal bridges.</para>
+        <para>To configure a cluster connection to add the duplicate id header, simply set the
+                <parameter>use-duplicate-detection</parameter> to <literal>true</literal> when
+            configuring a cluster connection in <literal>jbm-configuration.xml</literal>.</para>
+        <para>The default value for this parameter is <literal>true</literal>.</para>
+        <para>For more information on cluster connections and how to configure them see section
+            [LINK]</para>
+    </section>
+    <section>
+        <title>Duplicate Detection and Paging</title>
+        <para>JBoss Messaging also uses duplicate detection when paging messages to storage. This is
+            so when a message is depaged from storage and server failure occurs, we do not end up
+            depaging the message more than once which could result in duplicate delivery.</para>
+        <para>For more information on paging and how to configure it see section [LINK]</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/embedding-jbm.xml (from rev 6908, trunk/docs/user-manual/en/modules/embedding-jbm.xml)
===================================================================
--- trunk/docs/user-manual/en/embedding-jbm.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/embedding-jbm.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,202 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="embedding-jbm">
+    <title>Embedding JBoss Messaging</title>
+    <para>JBoss Messaging was designed as a simple set of POJOs, and it was designed to be
+        embeddable.</para>
+    <para>Embedding JBM can be done in very few easy steps. Instantiate the configuration object,
+        instantiate the server, start it, and you have a JBoss Messaging running in your virtual
+        machine. Easy and simple like that.</para>
+    <section>
+        <title>POJO instantiation</title>
+        <para>You can follow this step-by-step guide:</para>
+        <para>Create the configuration object. If you need a configuration file, use <literal
+                >FileConfigurationImpl</literal></para>
+        <programlisting>import org.jboss.messaging.core.config.Configuration;
+import org.jboss.messaging.core.config.impl.FileConfiguration;
+
+...
+
+
+Configuration config = new FileConfiguration();
+config.setConfigurationUrl(urlToYourconfigfile);
+config.start();</programlisting>
+        <para>If you don't need to support a configuration file, just use <literal
+                >ConfigurationImpl</literal> and change the config parameters accordingly, such as
+            adding acceptors. </para>
+        <para>The acceptors are configured through <literal>ConfigurationImpl</literal>. Just add
+            the <literal>NettyAcceptorFactory</literal> on the transports the same way you would
+            through the main configuration file.</para>
+        <programlisting>import org.jboss.messaging.core.config.Configuration;
+import org.jboss.messaging.core.config.impl.ConfigurationImpl;
+
+...
+
+Configuration config = new ConfigurationImpl();
+HashSet&lt;TransportConfiguration> transports = new HashSet&lt;TransportConfiguration>();
+      
+transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
+transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
+
+config.setAcceptorConfigurations(transports);</programlisting>
+        <para>You need to instantiate and start JBoss Messaging server. The class <literal
+                >Messaging</literal> on package <literal>org.jboss.messaging.core.server</literal>
+            has a few static methods helpful on instantiating the server, which is aways our
+            preferable way.</para>
+        <programlisting>import org.jboss.messaging.core.server.Messaging;
+import org.jboss.messaging.core.server.MessagingServer;
+
+...
+
+MessagingServer server = Messaging.newMessagingServer(config);
+
+server.start();</programlisting>
+        <para>You also have the option of instantiating <literal>MessagingServerImpl</literal>
+            directly:</para>
+        <programlisting>MessagingServer server = new MessagingServerImpl(config,
+                                                 ManagementFactory.getPlatformMBeanServer(),
+                                                 new JBMSecurityManagerImpl());
+server.start();
+        </programlisting>
+    </section>
+    <section>
+        <title>Dependency Frameworks</title>
+        <para>You may also choose to use a dependency injection framework such as <trademark>JBoss
+                Micro Container</trademark> or <trademark>Spring Framework</trademark>.</para>
+        <para>JBoss Messaging standalone uses JBoss Micro Container as the injection framework.
+                <literal>JBMBootstrapServer</literal> and <literal>jbm-jboss-beans.xml</literal>
+            which are part of the JBoss Messaging distribution provide a very complete
+            implementation of what's needed to bootstrap the server using JBoss Micro Container. </para>
+        <para>When using JBoss Micro Container, you need to provide a XML with the four objects
+            required to instantiate a Server:</para>
+        <itemizedlist>
+            <listitem>
+                <para>The configuration</para>
+            </listitem>
+            <listitem>
+                <para>A <literal>MBeanServer</literal> required by management.</para>
+            </listitem>
+            <listitem>
+                <para>The security manager</para>
+            </listitem>
+            <listitem>
+                <para>And the messaging server itself.</para>
+            </listitem>
+        </itemizedlist>
+        <para>A very basic XML Bean declaration for the JBoss Micro Container would be:</para>
+        <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?>
+
+&lt;deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+    &lt;bean name="MBeanServer" class="javax.management.MBeanServer">
+      &lt;constructor factoryClass="java.lang.management.ManagementFactory"
+                   factoryMethod="getPlatformMBeanServer"/>
+   &lt;/bean> 
+
+   &lt;!-- The core configuration -->
+   &lt;bean name="Configuration" 
+         class="org.jboss.messaging.core.config.impl.FileConfiguration">
+   &lt;/bean>
+
+	&lt;!-- The security manager -->
+   &lt;bean name="JBMSecurityManager" 
+       class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+      &lt;start ignored="true"/>
+      &lt;stop ignored="true"/>
+   &lt;/bean>
+
+	&lt;!-- The core server -->
+   &lt;bean name="MessagingServer" 
+         class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
+     &lt;start ignored="true"/>
+      &lt;stop ignored="true"/>  
+      &lt;constructor>
+         &lt;parameter>
+            &lt;inject bean="Configuration"/>
+         &lt;/parameter>
+         &lt;parameter>
+            &lt;inject bean="MBeanServer"/>
+         &lt;/parameter>
+         &lt;parameter>
+            &lt;inject bean="JBMSecurityManager"/>
+         &lt;/parameter>        
+      &lt;/constructor>         
+   &lt;/bean>
+   &lt;/deployment></programlisting>
+        <para><literal>JBMBootstrapServer</literal> provides an easy encapsulation of JBoss Micro
+            Container.</para>
+        <programlisting>JBMBootstrapServer bootStrap = new JBMBootstrapServer(new String[] {"jbm-jboss-beans.xml"});
+        bootStrap.run();</programlisting>
+    </section>
+    <section>
+        <title>Connecting to the Embedded JBoss Messaging</title>
+        <para>There is no special requirement on connecting to an Embedded JBoss Messaging. As you
+            are managing POJOs directly you just instantiate the factories.</para>
+        <section>
+            <title>Core API</title>
+            <para>If using the core API, just create the <literal>ClientSessionFactory</literal> and
+                use the regular core API.</para>
+            <programlisting>ClientSessionFactory nettyFactory =  new ClientSessionFactoryImpl(
+                      new TransportConfiguration(
+                              InVMConnectorFactory.class.getName()), null);
+
+ClientSession session = factory.createSession(false, true, true);
+session.createQueue("example", "example", true);
+
+ClientProducer producer = session.createProducer("example");
+ClientMessage message = session.createClientMessage(true);
+
+message.getBody().writeString("Hello");
+
+producer.send(message);
+
+session.start();
+
+ClientConsumer consumer = session.createConsumer("example");
+
+ClientMessage msgReceived = consumer.receive();
+System.out.println("message = " + msgReceived.getBody().readString());
+
+session.close();
+            </programlisting>
+        </section>
+        <section>
+            <title>JMS API</title>
+            <para>Connection on an Embedded JBoss Messaging through JMS is also simple. Just
+                instantiate <literal>JBossConnectionFactory</literal> directly. The following
+                example illustrates that.</para>
+            <programlisting>JBossConnectionFactory cf = new JBossConnectionFactory(
+                            new TransportConfiguration(InVMConnectorFactory.class.getName()));
+
+Connection conn = cf.createConnection();
+
+conn.start();
+
+Session sess = conn.createSession(true, Session.SESSION_TRANSACTED);
+
+MessageProducer prod = sess.createProducer(queue);
+
+TextMessage msg = sess.createTextMessage("Hello!");
+
+prod.send(msg);
+
+sess.commit();
+
+MessageConsumer consumer = sess.createConsumer(queue);
+
+TextMessage txtmsg = (TextMessage)consumer.receive();
+
+System.out.println("Msg = " + txtmsg.getText());
+
+sess.commit();
+
+conn.close();
+            </programlisting>
+        </section>
+    </section>
+    <section>
+        <title>JMS Embedding Example</title>
+        <para>The <ulink url="../../../../examples/jms/embedded/readme.html"><literal>JMS
+                    Embedding</literal> Example</ulink> shows how to setup and run JBoss Messaging
+            embedded with JMS...</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/examples.xml (from rev 6908, trunk/docs/user-manual/en/modules/examples.xml)
===================================================================
--- trunk/docs/user-manual/en/examples.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/examples.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,457 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="examples">
+    <title>Examples</title>
+    <para>The JBoss Messaging distribution comes with a wide variety of examples demonstrating many
+        of the features in an easy to use, fully functional examples.</para>
+    <para>The examples are available in the distribution, in the <literal>examples</literal>
+        directory. Examples are split into JMS and Core examples. JMS examples show how a particular
+        feature can be used by a normal JMS client. Core examples (TODO) show how the equivalent
+        feature can be used by a core messaging client.</para>
+    <para>A set of Java EE examples are also provided which need the JBoss Application Server
+        installed to be able to run.</para>
+    <section>
+        <title>JMS Examples</title>
+        <para>To run a JMS example, simply <literal>cd</literal> into the appropriate example
+            directory and type <literal>ant</literal></para>
+        <para>Here's a listing of the examples with a brief description.</para>
+        <section>
+            <title>Application-Layer Failover</title>
+            <para>JBoss Messaging implements fully transparent automatic failover of connections
+                from a live to backup node, this requires no special coding for failover, and is
+                described in a different example. Automatic failover requires server
+                replication.</para>
+            <para>However, JBoss Messaging also supports Application-Layer failover, useful in the
+                case that replication is not enabled on the server side.</para>
+            <para>With Application-Layer failover, it's up to the application to register a JMS
+                ExceptionListener with JBoss Messaging which will be called by JBoss Messaging in
+                the event that connection failure is detected.</para>
+            <para>The code in the ExceptionListener then recreates the JMS Connection, Session, etc
+                on another node and the application can continue.</para>
+            <para>Application-Layer failover is an alternative approach to High Availability
+                (HA).Application-Layer failover differs from automatic failover in that some client
+                side coding is required in order to implement this. Also, with Application-Layer
+                failover, since the old Session object dies and a new one is created, any
+                uncommitted work in the old Session will be lost, and any unacknowledged messages
+                might be redelivered.</para>
+        </section>
+        <section>
+            <title>Automatic (Transparent) Failover</title>
+            <para>This example demonstrates two servers coupled as a live-backup pair for high
+                availability (HA), and a client connection transparently failing over from live to
+                backup when the live server is crashed.</para>
+            <para>JBoss Messaging implements seamless, transparent failover of client connections
+                between live and backup servers. This is implemented by the replication of state
+                between live and backup nodes. When replication is configured and a live node
+                crashes, the client connections can carry on as if nothing happened and carry on
+                sending and consuming messages.</para>
+        </section>
+        <section>
+            <title>Automatic Reconnect Same Server</title>
+            <para>This example demonstrates how JBoss Messaging connections can be configured to be
+                resilient to temporary network failures. In the case of a network failure being
+                detected, either as a result of a failure to read/write to the connection, or the
+                failure of a pong to arrive back from the server in good time after a ping is sent,
+                instead of failing the connection immediately and notifying any user
+                ExceptionListener objects, JBoss Messaging can be configured to automatically retry
+                the connection, and reconnect to the server when it becomes available again across
+                the network.</para>
+        </section>
+        <section>
+            <title>Browser</title>
+            <para>This example shows you how to use a JMS QueueBrowser with JBoss Messaging.</para>
+            <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
+                full details.</para>
+            <para> A QueueBrowser is used to look at messages on the queue without removing them. It
+                can scan the entire content of a queue or only messages matching a message
+                selector.</para>
+        </section>
+        <section>
+            <title>Core Bridge Example</title>
+            <para>This example demonstrates a core bridge deployed on one server, which consumes
+                messages from a local queue and forwards them to an address on a second
+                server.</para>
+            <para>Core bridges are used to create message flows between any two JBoss Messaging
+                servers which are remotely separated. Core bridges are resilient and will cope with
+                temporary connection failure allowing them to be an ideal choice for forwarding over
+                unreliable connections, e.g. a WAN.</para>
+        </section>
+        
+        <section>
+            <title>Client Kickoff</title>
+            <para>This example shows how to kick off a client connected to JBoss Messaging using
+                JMX.</para>
+        </section>
+        <section>
+            <title>Client Side Load-Balancing</title>
+            <para>This example demonstrates how subsequent connections created from a JMS Connection
+                Factory can be created to different nodes of the cluster. In other words it
+                demonstrates how JBoss Messaging does client side load balancing of connections
+                across the cluster.</para>
+        </section>
+        <section>
+            <title>Clustered Topic</title>
+            <para>This example demonstrates a JMS Topic deployed on two different nodes. The two
+                nodes are configured to form a cluster. We then create a subscriber on the topic on
+                each node, and we create a producer on only one of the nodes. We then send some
+                messages via the producer, and we verify that both subscribers receive all the sent
+                messages.</para>
+        </section>
+        
+       
+        <section>
+            <title>Dead Letter</title>
+            <para>This example shows you how to define and deal with dead letter messages. Messages
+                can be delivered unsuccessfully (e.g. if the transacted session used to consume them
+                is rolled back). </para>
+            <para>Such a message goes back to the JMS destination ready to be redelivered. However,
+                this means it is possible for a message to be delivered again and again without any
+                success and remain in the destination, clogging the system.</para>
+            <para>To prevent this, messaging systems define dead letter messages: after a specified
+                unsuccessful delivery attempts, the message is removed from the destination and put
+                instead in a dead letter destination where they can be consumed for further
+                investigation.</para>
+        </section>
+        <section>
+            <title>Delayed Redelivery</title>
+            <para>This example demonstrates how JBoss Messaging can be configured to provide a
+                delayed redelivery in the case a message needs to be redelivered.</para>
+            <para>Delaying redelivery can often be useful in the case that clients regularly fail or
+                roll-back. Without a delayed redelivery, the system can get into a "thrashing"
+                state, with delivery being attempted, the client rolling back, and delivery being
+                re-attempted ad infinitum in quick succession, using up valuable CPU and network
+                resources.</para>
+        </section>
+        <section>
+            <title>Divert</title>
+            <para>JBoss Messaging diverts allow messages to be transparently "diverted" from one
+                address to another with just some simple configuration defined on the server
+                side.</para>
+        </section>
+        <section>
+            <title>Durable Subscription</title>
+            <para>This example shows you how to use a durable subscription with JBoss Messaging.
+                Durable subscriptions are a standard part of JMS, please consult the JMS 1.1
+                specification for full details.</para>
+            <para>Unlike non durable subscriptions, the key function of durable subscriptions is
+                that the messages contained in them persist longer than the lifetime of the
+                subscriber - i.e. they will accumulate messages sent to the topic even if there is
+                no active subscriber on them. They will also survive server restarts. Note that for
+                the messages to be persisted, the messages sent to them must be marked as persistent
+                messages. </para>
+        </section>
+        <section>
+            <title>Embedded</title>
+            <para>This example shows how to embed the JBoss Messaging Server within your own
+                code.</para>
+        </section>
+        
+        
+        
+        <section>
+            <title>HTTP Transport</title>
+            <para>This example shows you how to configure JBoss Messaging to use HTTP protocol as
+                its transport layer.</para>
+        </section>
+        <section>
+            <title>Instantiate JMS Objects Directly</title>
+            <para>Usually, JMS Objects such as ConnectionFactory, Queue and Topic instances are
+                looked up from JNDI before being used by the client code. This objects are called
+                "administered objects" in JMS specification terminology.</para>
+            <para>However, in some cases a JNDI server may not be available or desired. To come to
+                the rescue JBoss Messaging also supports the direct instantiation of these
+                administered objects on the client side.</para>
+        </section>
+        <section>
+            <title>Interceptor</title>
+            <para>JBoss Messaging allows an application to use an interceptor to hook into the
+                messaging system. Interceptors allow you to handle various message events in JBoss
+                Messaging.</para>
+        </section>
+        <section>
+            <title>JAAS</title>
+            <para>This example shows you how to configure JBoss Messaging to use JAAS for security.
+                JBoss Messaging can leverage JAAS to delegate user authentication and authorization
+                to existing security infrastructure.</para>
+        </section>
+        <section>
+            <title>JMX Management</title>
+            <para>This example shows how to manage JBoss Messaging using JMX.</para>
+        </section>
+        <section>
+            <title>Large Message</title>
+            <para>This example shows you how to send and receive very large messages with JBoss
+                Messaging. JBoss Messaging supports the sending and receiving of huge messages, much
+                larger than can fit in available RAM on the client or server. Effectively the only
+                limit to message size is the amount of disk space you have on the server.</para>
+            <para>Large messages are persisted on the server so they can survive a server restart.
+                In other words JBoss Messaging doesn't just do a simple socket stream from the
+                sender to the consumer.</para>
+        </section>
+        <section>
+            <title>Last-Value Queue</title>
+            <para>This example shows you how to define and deal with last-value queues. Last-Value
+                queues are special queues which discard any messages when a newer message with the
+                same value for a well-defined Last-Value property is put in the queue. In other
+                words, a Last-Value queue only retains the last value.</para>
+            <para>A typical example for Last-Value queue is for stock prices, where you are only
+                interested by the latest value for a particular stock.</para>
+        </section>
+        <section>
+            <title>Load Balanced Clustered Queue</title>
+            <para>This example demonstrates a JMS queue deployed on two different nodes. The two
+                nodes are configured to form a cluster.</para>
+            <para>We then create a consumer on the queue on each node, and we create a producer on
+                only one of the nodes. We then send some messages via the producer, and we verify
+                that both consumers receive the sent messages in a round-robin fashion.</para>
+            <para>In other words, JBoss Messaging load balances the sent messages across all
+                consumers on the cluster</para>
+        </section>
+        <section>
+            <title>Management</title>
+            <para>This example shows how to manage JBoss Messaging using JMS Messages to invoke
+                management operations on the server.</para>
+        </section>
+        <section>
+            <title>Management Notification</title>
+            <para>This example shows how to receive management notifications from JBoss Messaging
+                using JMS Messages. JBoss Messaging servers emit management notifications when
+                events of interest occur (consumers are created or closed, destinations are created
+                or deleted, security authentication fails, etc.).</para>
+        </section>
+        <section>
+            <title>Message Consumer Rate Limiting</title>
+            <para>With JBoss Messaging you can specify a maximum consume rate at which a JMS
+                MessageConsumer will consume messages. This can be specified when creating or
+                deploying the connection factory.</para>
+            <para>If this value is specified then JBoss Messaging will ensure that messages are
+                never consumed at a rate higher than the specified rate. This is a form of consumer
+                throttling.</para>
+        </section>
+        <section>
+            <title>Message Counter</title>
+            <para>This example shows you how to use message counters to obtain message information
+                for a JMS queue.</para>
+        </section>
+        <section>
+            <title>Message Expiration</title>
+            <para>This example shows you how to define and deal with message expiration. Messages
+                can be retained in the messaging system for a limited period of time before being
+                removed. JMS specification states that clients should not receive messages that have
+                been expired (but it does not guarantee this will not happen).</para>
+            <para>JBoss Messaging can assign an expiry destination to a given queue so that when
+                messages are expired, they are removed from the queue and sent to the expiry
+                destination. These "expired" messages can later be consumed from the expiry
+                destination for further inspection.</para>
+        </section>
+        <section>
+            <title>Message Group</title>
+            <para>This example shows you how to configure and use message groups with JBoss
+                Messaging. Message groups are sets of messages that has the following
+                characteristics:</para>
+            <para>
+                <itemizedlist>
+                    <listitem>
+                        <para>Messages in a message group share the same group id, i.e. they have
+                            same JMSXGroupID string property values</para>
+                    </listitem>
+                    <listitem>
+                        <para>The consumer that receives the first message of a group will receive
+                            all the messages that belongs to the group</para>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </section>
+        <section>
+            <title>Message Producer Rate Limiting</title>
+            <para>This example demonstrates how, with JBoss Messaging, you can specify a maximum
+                send rate at which a JMS message producer will send messages.</para>
+        </section>
+        <section>
+            <title>Message Priority</title>
+            <para>Message Priority carries the delivery preference of messages. It can be retrieved
+                by the message's standard header field 'JMSPriority' as defined in JMS specification
+                version 1.1. The value is of type integer, ranging from 0 (the lowest) to 9 (the
+                highest). When messages are being delivered, their priorities will effect their
+                order of delivery. Messages of higher priorities will likely be delivered before
+                those of lower priorities. Messages of equal priorities are delivered in the natural
+                order of their arrival at their destinations. Please consult the JMS 1.1
+                specification for full details.</para>
+        </section>
+        <section>
+            <title>Message Redistribution</title>
+            <para>This example demonstrates message redistribution between queues with the same name
+                deployed in different nodes of a cluster.</para>
+        </section>
+        <section>
+            <title>No Consumer Buffering</title>
+            <para>By default, JBoss Messaging consumers buffer messages from the server in a client
+                side buffer before you actually receive them on the client side. This improves
+                performance since otherwise every time you called receive() or had processed the
+                last message in a <literal>MessageListener onMessage()</literal> method, the JBoss
+                Messaging client would have to go the server to request the next message, which
+                would then get sent to the client side, if one was available. This would involve a
+                network round trip for every message and really reduce performance. Therefore, by
+                default, JBoss Messaging pre-fetches messages into a buffer on each consumer.</para>
+        </section>
+        <section>
+            <title>Paging</title>
+            <para>This example shows how JBoss Messaging would avoid running out of resources by
+                paging messages.</para>
+        </section>
+        <section>
+            <title>Pre-Acknowledge</title>
+            <para>Standard JMS supports three acknowledgement modes: AUTO_ACKNOWLEDGE,
+                CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE. For a full description on these modes
+                please consult the JMS specification, or any JMS tutorial.</para>
+            <para>All of these standard modes involve sending acknowledgements from the client to
+                the server. However in some cases, you really don't mind losing messages in event of
+                failure, so it would make sense to acknowledge the message on the server before
+                delivering it to the client. This example demonstrates how JBoss Messaging soes
+                this.</para>
+        </section>
+        
+        <section>
+            <title>Queue</title>
+            <para>A simple example demonstrating a JMS Queue.</para>
+        </section>
+        
+        <section>
+            <title>Queue Requestor</title>
+            <para>A simple example demonstrating a JMS queue requestor.</para>
+        </section>
+        <section>
+            <title>Queue with Message Selector</title>
+            <para>This example shows you how to selectively consume messages using message selectors
+                with queue consumers.</para>
+        </section>
+        
+        <section>
+            <title>Request-Reply</title>
+            <para>A simple example showing the JMS request-reply pattern.</para>
+        </section>
+        <section>
+            <title>Scheduled Message</title>
+            <para>This example shows you how to send a scheduled message to a JMS Queue with JBoss
+                Messaging.</para>
+        </section>
+        <section>
+            <title>Security</title>
+            <para>This example shows you how configure and use security with JBoss Messaging.</para>
+        </section>
+        
+        <section>
+            <title>Static Message Selector</title>
+            <para>This example shows you how to configure a JBoss Messaging queue with static
+                message selectors (filters).</para>
+        </section>
+        <section>
+            <title>Static Message Selector Using JMS</title>
+            <para>This example shows you how to configure a JBoss Messaging queue with static
+                message selectors (filters) using JMS.</para>
+        </section>
+        <section>
+            <title>SSL Transport</title>
+            <para>This example shows you how to configure SSL with JBoss Messaging to send and
+                receive message.</para>
+        </section>
+        <section>
+            <title>Symmetric Cluster</title>
+            <para>This examples demonstrates a symmetric cluster set-up with JBoss Messaging.</para>
+            <para>JBoss Messaging has extremely flexible clustering which allows you to set-up
+                servers in many different topologies. The most common topology that you'll perhaps
+                be familiar with if you are used to application server clustering is a symmetric
+                cluster.</para>
+            <para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
+                the same as every other node, and every node is connected to every other node in the
+                cluster.</para>
+        </section>
+        <section>
+            <title>Temporary Queue</title>
+            <para>A simple example demonstrating how to use a JMS temporary queue.</para>
+        </section>
+        <section>
+            <title>Topic</title>
+            <para>A simple example demonstrating a JMS Topic.</para>
+        </section>
+        <section>
+            <title>Topic Hierarchy</title>
+            <para>JBoss Messaging supports topic hierarchies. With a topic hierarchy you can
+                register a subscriber with a wild-card and that subscriber will receive any messages
+                sent to an address that matches the wild card.</para>
+        </section>
+        <section>
+            <title>Topic Selector 1</title>
+            <para>This example shows you how to send message to a JMS Topic, and subscribe them
+                using selectors with JBoss Messaging.</para>
+        </section>
+        <section>
+            <title>Topic Selector 2</title>
+            <para>This example shows you how to selectively consume messages using message selectors
+                with topic consumers.</para>
+        </section>
+        <section>
+            <title>Transactional Session</title>
+            <para>This example shows you how to use a transactional Session with JBoss
+                Messaging.</para>
+        </section>
+        <section>
+            <title>XA Heuristic</title>
+            <para>This example shows you how to make an XA heuristic decision through JBoss
+                Messaging Management Interface. A heuristic decision is a unilateral decision to
+                commit or rollback an XA transaction branch after it has been prepared.</para>
+        </section>
+        <section>
+            <title>XA Receive</title>
+            <para>This example shows you how message receiving behaves in an XA transaction in JBoss
+                Messaging.</para>
+        </section>
+        <section>
+            <title>XA Send</title>
+            <para>This example shows you how message sending behaves in an XA transaction in JBoss
+                Messaging.</para>
+        </section>
+        <section>
+            <title>XA with Transaction Manager</title>
+            <para>This example shows you how to use JTA interfaces to control transactions with
+                JBoss Messaging.</para>
+        </section>
+    </section>
+    <section>
+        <title>Java EE Examples</title>
+        <para>Most of the Java EE examples can be run the following way. simply cd into the
+            appropriate example directory an type <literal>ant deploy</literal>. This will create a
+            new JBoss AS profile and start the server. When the server is started from a different
+            window type <literal>ant run</literal> to run the example. Some examples require further
+            steps, please refer to the examples documentation for further instructions.</para>
+        <section>
+            <title>EJB/JMS Transaction</title>
+            <para>An example that shows using an EJB and JMS together within a transaction.</para>
+        </section>
+        <section>
+            <title>HAJNDI (High Availability)</title>
+            <para>A simple example demonstrating using JNDI within a cluster.</para>
+        </section>
+        <section>
+            <title>Resource Adapter Configuration</title>
+            <para>This example demonstrates how to configure several properties on the JBoss
+                Messaging Resource Adapter.</para>
+        </section>
+        <section>
+            <title>JMS Bridge</title>
+            <para>An example demonstrating the use of the JBoss Messaging JMS bridge.</para>
+        </section>
+        <section>
+            <title>MDB (Message Driven Bean)</title>
+            <para>A simple example of a message driven bean.</para>
+        </section>
+        <section>
+            <title>Servlet Transport</title>
+            <para>An example of how to use the JBoss Messaging servlet transport.</para>
+        </section>
+        <section>
+            <title>XA Recovery</title>
+            <para>An example of how XA recovery works within the JBoss Application server using
+                JBoss Messaging.</para>
+        </section>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/filter-expressions.xml (from rev 6908, trunk/docs/user-manual/en/modules/filter-expressions.xml)
===================================================================
--- trunk/docs/user-manual/en/filter-expressions.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/filter-expressions.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="filter-expressions">
+    <title>Filter Expressions</title>
+    <para>JBoss Messaging provides a powerful filter language based on a subset of the SQL 92
+        expression syntax.</para>
+    <para>It is very similar to the syntax used for JMS selectors. For documentation on JMS selector
+        syntax please the JMS javadoc for <ulink
+            url="http://java.sun.com/javaee/5/docs/api/javax/jms/Message.html"
+            >javax.jms.Message</ulink>.</para>
+    <para>Filter expressions are used in several places in JBossMessaging</para>
+    <itemizedlist>
+        <listitem>
+            <para>Predefined Queues. When pre-defining a queue, either in <literal
+                    >jbm-configuration.xml</literal> or <literal>jbm-jms.xml</literal> a filter
+                expression can be defined for a queue. Only messages that match the filter
+                expression will enter the queue.</para>
+        </listitem>
+        <listitem>
+            <para>Core Bridges can be defined with an optional filter expression, only matching
+                messages will be bridged. See the section [LINK]</para>
+        </listitem>
+        <listitem>
+            <para>Diverts can be defined with an optional filter expression, only matching messages
+                will be diverted. See the section [LINK]</para>
+        </listitem>
+        <listitem><para>Filter are also used programmatically when creating consumers, queues and in several places in the management API.</para></listitem>
+    </itemizedlist>
+    <para>There are some differences between JMS selector expressions and JBoss Messaging core
+        filter expressions. Whereas JMS selector expressions operate on a JMS message, JBoss
+        Messaging core filter expressions operate on a core message.</para>
+    <para>The following identifiers can be used in a core filter expressions to refer to attributes
+        of the core message in an expression:</para>
+    <itemizedlist>
+        <listitem>
+            <para><literal>JBMPriority</literal>. To refer to the priority of a message. Message
+                priorities are integers with valid values from <literal>0 - 9</literal>. <literal
+                    >0</literal> is the lowest priority and <literal>9</literal> is the highest.
+                E.g. <literal>JBMPriority = 3 AND animal = 'aardvark'</literal></para>
+        </listitem>
+        <listitem>
+            <para><literal>JBMExpiration</literal>. To refer to the expiration time of a message. The value is a long integer.</para>
+        </listitem>
+        <listitem>
+            <para><literal>JBMDurable</literal>. To refer to whether a message is durable or not. The value is a string with valid values:
+            <literal>DURABLE</literal> or <literal>NON_DURABLE</literal>.</para>
+        </listitem>
+        <listitem>
+            <para><literal>JBMTimestamp</literal>. The timestamp of when the message was created. The value is a long integer.</para>
+        </listitem>
+        <listitem>
+            <para><literal>JBMSize</literal>. The size of a message in bytes. The value is an integer.</para>
+        </listitem>
+    </itemizedlist>
+    <para>Any other identifiers used in core filter expressions will be assumed to be properties of the message.</para>
+</chapter>

Copied: trunk/docs/user-manual/en/flow-control.xml (from rev 6908, trunk/docs/user-manual/en/modules/flow-control.xml)
===================================================================
--- trunk/docs/user-manual/en/flow-control.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/flow-control.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="flow-control">
+   <title>Flow Control</title>
+   <para>JBoss Messaging allows the user to restrict how fast messages are delivered between both
+      client and server and also between server and client.</para>
+   <section>
+      <title>Consumer Flow Control</title>
+      <para>This controls the flow of messages between the server and the client. For performance
+         reasons clients buffer messages before delivering to the consumer via the <literal
+            >receive()</literal> method or asynchronously via a message listener. If the consumer
+         cannot process messages as fast as they are being delivered and stored in the internal
+         buffer, then you could end up with a situation where messages just keep building up and are
+         not processed for a long time. </para>
+      <para/>
+      <section id="flow-control.consumer.window">
+         <title>Window-Based Flow Control</title>
+         <para>By default, JBoss Messaging consumers buffer messages from the server in a client
+            side buffer before the client receive them. This improves performance: otherwise every
+            time the client consumes a message, JBoss Messaging would have to go the server to
+            request the next message. In turn, this message would then get sent to the client side,
+            if one was available.</para>
+         <para>A network round trip would be involved for <emphasis>every</emphasis> message and
+            considerably reduce performance.</para>
+         <para>To prevent this, JBoss Messaging pre-fetches messages into a buffer on each consumer.
+            The total maximum size of messages (in bytes) that will be buffered on each consumer is
+            determined by the <literal>consumer-window-size</literal> parameter.</para>
+         <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024
+            bytes).</para>
+         <para>The value can be:</para>
+         <itemizedlist>
+            <listitem>
+               <para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para>
+            </listitem>
+            <listitem>
+               <para><literal>0</literal> to not buffer any messages.</para>
+            </listitem>
+            <listitem>
+               <para><literal>&gt;0</literal> for a buffer with the given maximum size in
+                  bytes.</para>
+            </listitem>
+         </itemizedlist>
+         <para>Setting the consumer window size can considerably improve performance depending on
+            the messaging use case. As an example, let's consider the two extremes: </para>
+         <variablelist>
+            <varlistentry>
+               <term>Fast consumers</term>
+               <listitem>
+                  <para>Fast consumers can process messages as fast as they consume them (or even
+                     faster)</para>
+                  <para>To allow fast consumers, set the <literal>consumer-window-size</literal> to
+                     -1. This will allow <emphasis>unbounded</emphasis> message buffering on the
+                     client side.</para>
+                  <para>Use this setting with caution: it can overflow the client memory if the
+                     consumer is not able to process messages as fast as it receives them.</para>
+               </listitem>
+            </varlistentry>
+            <varlistentry>
+               <term>Slow consumers</term>
+               <listitem>
+                  <para>Slow consumers takes significant time to process each message and it is
+                     desirable to prevent buffering messages on the client side so that they can be
+                     delivered to another consumer instead.</para>
+                  <para>Consider a situation where a queue has 2 consumers 1 of which is very slow.
+                     Messages are delivered in a round robin fashion to both consumers, the fast
+                     consumer processes all of its messages very quickly until its buffer is empty.
+                     At this point there are still messages awaiting to be processed by the slow
+                     consumer which could be being consumed by the other consumer.</para>
+                  <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to
+                     0 (for no buffer at all) or 1 (to buffer only 1 message). This will prevent the
+                     slow consumer from buffering any messages on the client side. Messages will
+                     remain on the server side ready to be consumed by other consumers.</para>
+               </listitem>
+            </varlistentry>
+         </variablelist>
+         <para>Most of the consumers cannot be clearly identified as fast or slow consumers but are
+            in-between. In that case, setting the value of <literal>consumer-window-size</literal>
+            to optimize performance depends on the messaging use case and requires benchmarks to
+            find the optimal value. </para>
+         <section id="flow-control.core.api">
+            <title>Using Core API</title>
+            <para>If JBoss Messaging Core API is used, the consumer window size is specified by
+                  <literal>ClientSessionFactory.setConsumerWindowSize()</literal> method and some of
+               the <literal>ClientSession.createConsumer()</literal> methods.</para>
+         </section>
+         <section>
+            <title>Using JMS</title>
+            <para>if JNDI is used to look up the connection factory, the consumer window size is
+               configured in <literal>jbm-jms.xml</literal>:</para>
+            <programlisting>
+&lt;connection-factory name="ConnectionFactory"&gt;
+   &lt;connector-ref connector-name="netty-connector"/&gt;
+   &lt;entries&gt;
+      &lt;entry name="ConnectionFactory"/&gt;       
+   &lt;/entries&gt;
+      
+   &lt;!-- Set the consumer window size to 0 to have *no* buffer on the client side --&gt;
+   &lt;consumer-window-size&gt;0&lt;/consumer-window-size&gt;
+&lt;/connection-factory&gt;
+            </programlisting>
+            <para>If the connection factory is directly instantiated, the consumer window size is
+               specified by <literal>JBossConnectionFactory.setConsumerWindowSize()</literal>
+               method.</para>
+         </section>
+         <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/no-consumer-buffering/readme.html">
+                  <literal>no-consumer-buffering</literal> example</ulink> shows how to configure
+               JBoss Messaging to prevent consumer buffering when dealing with slow
+               consumers.</para>
+         </section>
+      </section>
+      <section>
+         <title>Rate limited flow control</title>
+         <para>It is also possible to control the rate at which a consumer can consumer messages.
+            This is a form of throttling and can be used to make sure that a consumer never consumes
+            messages at a rate faster than the rate specified. </para>
+         <para>The rate must be a positive integer to enable and is the maximum desired message
+            consumption rate specified in units of messages per second. Setting this to <literal
+               >-1</literal> disables rate limited flow control. The default value is <literal
+               >-1</literal>.</para>
+         <section id="flow-control.rate.core.api">
+            <title>Using Core API</title>
+            <para>If the JBoss Messaging core API is being used the rate can be set via the <literal
+                  >ClientSessionFactory.setConsumerMaxRate(int consumerMaxRate)</literal> method or
+               alternatively via some of the <literal>ClientSession.createConsumer()</literal>
+               methods. </para>
+         </section>
+         <section>
+            <title>Using JMS</title>
+            <para>If JNDI is used to look up the connection factory, the max rate can be configured
+               in <literal>jbm-jms.xml</literal>:</para>
+            <programlisting>&lt;connection-factory name="ConnectionFactory">
+      &lt;connector-ref connector-name="netty-connector"/>
+      &lt;entries>
+         &lt;entry name="ConnectionFactory"/>       
+      &lt;/entries>
+      &lt;!-- We limit consumers created on this connection factory to consume messages at a maximum rate
+      of 10 messages per sec -->
+      &lt;consumer-max-rate>10&lt;/consumer-max-rate>
+ &lt;/connection-factory></programlisting>
+            <para>If the connection factory is directly instantiated, the max rate size can be set
+               via the <literal>JBossConnectionFactory.setConsumerMaxRate(int
+                  consumerMaxRate)</literal> method.</para>
+            <note>
+               <para>Rate limited flow control can be used in conjunction with window based flow
+                  control. Rate limited flow control only effects how many messages a client can
+                  consume in a second and not how many messages are in its buffer. So if you had a
+                  slow rate limit and a high window based limit the clients internal buffer would
+                  soon fill up with messages.</para>
+            </note>
+         </section>
+         <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/consumer-rate-limit/readme.html">
+                  <literal>consumer-rate-limit</literal> example</ulink> shows how to configure
+               JBoss Messaging to prevent consumer buffering when dealing with slow
+               consumers.</para>
+         </section>
+      </section>
+   </section>
+   <section>
+      <title>Producer flow control</title>
+      <para>JBoss Messaging allows producers to be created which limit</para>
+      <section>
+         <title>Window based flow control</title>
+         <para>JBoss Messaging clients maintain a buffer of commands that have been sent to the server, thus provides a form
+         of flow control. Please see the chapter on <xref linkend="command-buffering">command buffering</xref> for more information
+         on this.</para>
+      </section>
+      <section>
+         <title>Rate limited flow control</title>
+         <para>JBoss Messaging also allows the rate a producer can emit message to be limited, in
+            units of messages per second. By specifying such a rate, JBoss Messaging will ensure
+            that producer never produces messages at a rate higher than that specified.</para>
+         <para>The rate must be a positive integer to enable and is the maximum desired message
+            consumption rate specified in units of messages per second. Setting this to <literal
+               >-1</literal> disables rate limited flow control. The default value is <literal
+               >-1</literal>.</para>
+         <section id="flow-control.producer.rate.core.api">
+            <title>Using Core API</title>
+            <para>If the JBoss Messaging core API is being used the rate can be set via the <literal
+                  >ClientSessionFactory.setProducerMaxRate(int consumerMaxRate)</literal> method or
+               alternatively via some of the <literal>ClientSession.createProducer()</literal>
+               methods. </para>
+         </section>
+         <section>
+            <title>Using JMS</title>
+            <para>If JNDI is used to look up the connection factory, the max rate can be configured
+               in <literal>jbm-jms.xml</literal>:</para>
+            <programlisting>&lt;connection-factory name="ConnectionFactory">
+      &lt;connector-ref connector-name="netty-connector"/>
+      &lt;entries>
+         &lt;entry name="ConnectionFactory"/>       
+      &lt;/entries>
+      &lt;!-- We limit producers created on this connection factory to produce messages at a maximum rate
+      of 10 messages per sec -->
+      &lt;producer-max-rate>10&lt;/producer-max-rate>
+ &lt;/connection-factory></programlisting>
+            <para>If the connection factory is directly instantiated, the max rate size can be set
+               via the <literal>JBossConnectionFactory.setProducerMaxRate(int
+                  consumerMaxRate)</literal> method.</para>
+         </section>
+         <section>
+            <title>Example</title>
+            <para>[LINK] to producer rate limit example</para>
+         </section>
+      </section>
+   </section>
+</chapter>

Copied: trunk/docs/user-manual/en/ha.xml (from rev 6908, trunk/docs/user-manual/en/modules/ha.xml)
===================================================================
--- trunk/docs/user-manual/en/ha.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/ha.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ha">
+    <title>High Availability and Failover</title>
+    <para>We define high availability as the <emphasis>ability for the system to continue
+            functioning after failure of one or more of the servers</emphasis>. A part of high
+        availability is <emphasis>failover</emphasis> which we define as the <emphasis>ability for
+            client connections to migrate from one server to another in event of server failure so
+            client applications can continue to operate</emphasis>.</para>
+    <para>JBoss Messaging provides high availability by replicating servers in pairs. It also
+        provides both 100% transparent client failover and application-level client failover.</para>
+    <section>
+        <title>Server replication</title>
+        <para>JBoss Messaging allows pairs of servers to be linked together as <emphasis>live -
+                backup</emphasis> pairs. In this release there is a single backup server for each
+            live server. Backup servers are not operational until failover occurs. In later releases
+            we will be supporting replication onto multiple backup servers and active - active
+            replication where both live and backup servers operate as active servers.</para>
+        <para>When a <emphasis>live - backup</emphasis> pair is configured, JBoss Messaging ensures
+            that the live server state is replicated to the backup server. Replicated state includes
+            session state, and also global state such as the set of queues and addresses on the
+            server. </para>
+        <para>When a client fails over from live to backup server, the backup server will already
+            have the correct global and session state, so the client will be able to resume its
+            session(s) on the backup server as if nothing happened.</para>
+        <para>Replication is performed in an asynchronous fashion between live and backup server.
+            Data is replicated one way in a stream, and responses that the data has reached the
+            backup is returned in another stream. By pipelining replications and responses to
+            replications in separate streams allows replication throughput to be much higher than if
+            we synchronously replicated data and waited for a response serially in an RPC manner
+            before replicating the next piece of data.</para>
+        <section id="configuring.live.backup">
+            <title>Configuring live-backup pairs</title>
+            <para>First, on the live server, in <literal>jbm-configuration.xml</literal> configure
+                the live server with knowledge of its backup server. This is done by specifying a
+                    <literal>backup-connector-ref</literal> element. This element references a
+                connector, also specified on the live server which contains knowledge of how to
+                connect to the backup server. Here's a snippet from <literal
+                    >jbm-configuration.xml</literal> showing a live server configured with a backup
+                server:</para>
+            <programlisting>&lt;backup-connector-ref connector-name="backup-connector"/>
+   
+&lt;!-- Connectors -->
+
+&lt;connectors>
+
+   ...
+   
+   &lt;!-- This connector specifies how to connect to the backup server -->
+   &lt;connector name="backup-connector">
+     &lt;factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory&lt;/factory-class>
+     &lt;param key="jbm.remoting.netty.port" value="5445" type="Integer"/>
+   &lt;/connector>
+
+&lt;/connectors></programlisting>
+            <para>Secondly, on the backup server, also in <literal>jbm-configuration.xml</literal> ,
+                the element <literal>backup</literal> must be set to true. I.e. :</para>
+            <programlisting>&lt;backup>true&lt;/backup>
+</programlisting>
+        </section>
+        <section>
+            <title>Synchronization of live-backup pairs</title>
+            <para>In order for live - backup pairs to operate properly, they must be identical
+                replicas. This means you cannot just use any backup server that's previously been
+                used for other purposes as a backup server, since it will have different data in its
+                persistent storage. If you try to do so you will receive an exceptin in the logs and
+                the server wil fail to start.</para>
+            <para>To create a backup server for a live server that's already been used for other
+                purposes, it's necessary to copy the <literal>data</literal> directory from the live
+                server to the backup server. This means the backup server will have an identical
+                persistent store to the backup server.</para>
+            <para>Similarly when a client fails over from a live server <literal>L</literal>to a
+                backup server <literal>B</literal>, the server <literal>L</literal>becomes invalid
+                since, from that point on, the data on <literal>L</literal> and <literal>B</literal>
+                tmay diverge. After such a failure, at the next available opportunity the <literal
+                    >B</literal> server should be taken down, and its <literal>data</literal>
+                directory copied back to the <literal>L</literal> server. Live and backup servers
+                can then be restarted. In this release of JBoss Messaging we do not provide any
+                automatic facility for re-assigning a backup node with a live node while it is
+                running.</para>
+            <para>For a backup server to function correctly it's also important that it has the same
+                set of bridges, predefined queues, cluster connections, broadcast groups and
+                discovery groups as defined on the live node. The easiest way to ensure this is just
+                to copy the entire server side configuration from live to backup and just make the
+                changes as specified in the previous section. </para>
+        </section>
+        <section id="queue.activation.timeout">
+            <title>Queue activation timeout</title>
+            <para>If a live server fails, as client connections failover from the live node to the
+                backup, they do so at a rate determined by the client, and it might be the case that
+                some client connections never fail over.</para>
+            <para>Different client connections may have different consumers on the same queue(s).
+                The queue on the backup will wait for all its consumers to reattach before
+                activating delivery on itself. If all connections have not reattached with this
+                timeout then the queue will activate regardless.</para>
+            <para>This param is defined in <literal>jbm-configuration.xml</literal> using the
+                setting <literal>queue-activation-timeout</literal>. It's default value is <literal
+                    >30000</literal> milliseconds.</para>
+        </section>
+    </section>
+    <section id="ha.client.automatic">
+        <title>Automatic client failover</title>
+        <para>JBoss Messaging clients can be configured with knowledge of live and backup servers,
+            so that in event of connection failure of the client - live server connection, the
+            client will detect this and reconnect its sessions to the backup server. Because of
+            server replication, then backup server will already have those sessions in the same
+            state they were left on the live server and the client will be able to reconnect them
+            and resume them 100% transparently as if nothing happened.</para>
+        <para>For automatic failover JBoss Messaging requires <emphasis>zero</emphasis> coding of
+            special failover code on the client or server. This differs from other messaging systems
+            which intrusively require you to code special failover handling code. JBoss Messaging
+            automatic failover preserves all your normal JMS or core API semantics and allows your
+            client code to continue 100% uninterrupted on event of connection failure and failover
+            from a live to a backup server.</para>
+        <para>JBoss Messaging clients detect connection failure by using connection pinging on the
+            connection. If the client does not receive a pong response from the server in good time
+            after a ping is sent, it will assume the connection has failed and attempt
+            failover.</para>
+        <para>JBoss Messaging clients can be configured with the list of live-backup server pairs in
+            a number of different ways. They can be configured explicitly or probably the most
+            common way of doing this is to use <emphasis>server discovery</emphasis> for the client
+            to automatically discover the list. For full details on how to configure clients please
+            see the section on server discovery [LINK].</para>
+        <para>Sometimes you want a client to failover onto a backup server even if the live server
+            is just cleanly shutdown rather than having crashed or the connection failed. To
+            configure this you can set the property <literal>FailoverOnServerShutdown</literal> to
+            false either on the <literal>JBossConnectionFactory</literal> if you're using JMS or in
+            the <literal>jbm-jms.xml</literal> file when you define the connection factory, or if
+            using core by setting the property directly on the <literal
+                >ClientSessionFactoryImpl</literal> instance after creation. The default value for
+            this property is <literal>false</literal>, this means that by default <emphasis>JBoss
+                Messaging clients will not failover to a backup server if the live server is simply
+                shutdown cleanly.</emphasis></para>
+        <para>For a fully functional example of automatic failover please see [LINK].</para>
+    </section>
+    <section>
+        <title>Application-level client failover</title>
+        <para>In some cases you may not want automatic client failover, and prefer to handle any
+            connection failure yourself, and code your own manually reconnection logic in your own
+            failure handler. We define this as <emphasis>application-level</emphasis> failover,
+            since the failover is handled at the user application level.</para>
+        <para>If all your clients use application-level failover then you do not need server
+            replication on the server side, and should disabled this. Server replication has some
+            performance overhead and should be disabled if it is not required. To disable server
+            replication simply do not specify a <literal>backup-connector</literal> element for each
+            live server.</para>
+        <para>To implement application-level failover, if you're using JMS then you need to code an
+                <literal>ExceptionListener</literal> class on the JMS connection. The <literal
+                >ExceptionListener</literal> wil be called by JBoss Messaging in the event that
+            connection failure is detected. In your <literal>ExceptionListener</literal> you would
+            close your old JMS connections, potentially look up new connection factory instances
+            from JNDI and creating new connections. In this case you may well be using HA-JNDI
+            [link] to ensure that the new connection factory is looked up from a different
+            server.</para>
+        <para>For a working example of application-level failover please see example [LINK].</para>
+        <para>If you are using the core API, then the procedure is very similar - you would code a
+                <literal>FailureListener</literal> on your core <literal>ClientSession</literal>
+            instances.</para>
+        <para>For a fully functional example of application-level failover please see [LINK].</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/intercepting-operations.xml (from rev 6908, trunk/docs/user-manual/en/modules/intercepting-operations.xml)
===================================================================
--- trunk/docs/user-manual/en/intercepting-operations.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/intercepting-operations.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="intercepting-operations">
+   <title>Intercepting Operations</title>
+      <para>JBoss Messaging supports <emphasis>interceptors</emphasis> to add behavior into 
+      the messaging server.</para>
+
+      <section>
+         <title>Implementing The Interceptors</title>
+         <para>A interceptor must implement the <literal>Interceptor interface</literal>:</para>
+         <programlisting>
+package org.jboss.messaging.core.remoting;
+
+public interface Interceptor
+{   
+   boolean intercept(Packet packet, RemotingConnection connection) throws MessagingException;
+}
+         </programlisting>
+         <para>The returned boolean value is important:</para>
+         <itemizedlist>
+            <listitem><para>if <literal>true</literal> is returned, the process continues normally</para></listitem>
+            <listitem><para>if <literal>false</literal> is returned, the process is aborted, no other interceptors will be called
+            and the packet will not be handled by the server at all.</para></listitem>
+         </itemizedlist>
+         
+      </section>
+
+      <section>
+         <title>Configuring The Interceptors</title>
+         <para>The interceptors are configured in <literal>jbm-configuration.xml</literal>:</para>
+         <programlisting>
+&lt;remoting-interceptors&gt;
+   &lt;class-name&gt;org.jboss.jms.example.LoginInterceptor&lt;/class-name&gt;
+   &lt;class-name&gt;org.jboss.jms.example.AdditionalPropertyInterceptor&lt;/class-name&gt;
+&lt;/remoting-interceptors&gt;
+         </programlisting>
+         <para>The interceptors classes (and their dependencies) must be added to the server classpath
+            to be properly instantiated and called.</para>
+      </section>
+
+      <section>
+         <title>Example</title>
+         <para>The <ulink url="../../../../examples/jms/interceptor/readme.html"><literal>interceptor</literal>
+          example</ulink> shows how to use interceptors to add properties to a message on the server.</para>
+      </section>
+          
+</chapter>

Copied: trunk/docs/user-manual/en/interoperability.xml (from rev 6908, trunk/docs/user-manual/en/modules/interoperability.xml)
===================================================================
--- trunk/docs/user-manual/en/interoperability.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/interoperability.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="interoperability">
+    <title>Interoperability</title>
+    <section>
+        <title>Stomp and StompConnect</title>
+        <para>Stomp is a wire protocol that allows stomp clients from to communicate with Stomp
+            Brokers. Using StompConnect it is possible to turn JBM into a Stomp Broker and use any
+            of the available stomp clients. These include clients written in C, C++, c# and .net
+            etc. For more information on Stomp and StompConnect go to <ulink
+                url="http://stomp.codehaus.org/Home"/></para>
+        <para>To run Stomp first start the JBoss Messaging server and make sure that it is using
+            JNDI.</para>
+        <para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
+            classpath. This should look something like:</para>
+        <programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+java.naming.provider.url=jnp://localhost:1099
+java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting>
+        <para>Make sure this file is in the classpath along with the StompConnect jar and the JBoss
+            Messaging jars and simply run <literal>java
+            org.codehaus.stomp.jms.Main</literal>.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/jms-core-mapping.xml (from rev 6908, trunk/docs/user-manual/en/modules/jms-core-mapping.xml)
===================================================================
--- trunk/docs/user-manual/en/jms-core-mapping.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/jms-core-mapping.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="jms-core-mapping">
+    <title>Mapping JMS to Core API</title>
+    <para>This chapter describes how JMS destinations are mapped to JBoss Messaging Core
+        resources</para>
+    <para>JBoss Messaging Core is JMS agnostic. It does not have any concept of a JMS Topic. A JMS
+        Topic is implemented in Core as an address (the topic name) with zero or more queues bound
+        to it. Each queue bound to that address represents a topic subscription. Likewise, a JMS
+        Queue is implemented as an address (the JMS Queue name) with one single queue bound to it
+        which represents the JMS Queue.</para>
+    <para>By convention, all JMS Queues map to core queues where the core queue name has the string
+            <literal>jms.queue.</literal> prepended to it. E.g. the JMS Queue with the name
+        "orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The
+        address at which the core queue is bound is also given by the core queue name.</para>
+    <para>For JMS Topics the address at which the queues that represent the subscriptions are bound
+        is given by prepending the string "jms.topic." to the name of the JMS Topic. E.g. the JMS
+        Topic with name "news.europe" would map to the core address "jms.topic.news.europe"</para>
+    <para>In other words if you send a JMS Message to a JMS Queue with name "orders.europe" it will
+        get routed on the server to any core queues bound to the address "jms.queue.orders.europe".
+        If you send a JMS Message to a JMS Topic with name "news.europe" it will get routed on the
+        server to any core queues bound to the address "jms.topic.news.europe".</para>
+    <para>If you want to configure settings for a JMS Queue with the name "orders.europe", you need
+        to configure the corresponding core queue "jms.queue.orders.europe":</para>
+    <programlisting>
+      &lt;!-- expired messages in JMS Queue "orders.europe"
+            will be sent to the JMS Queue "expiry.europe" --&gt;
+      &lt;address-setting match="jms.queue.orders.europe"&gt;
+         &lt;expiry-address&gt;jms.queue.expiry.europe&lt;/expiry-address&gt;
+         ...
+      &lt;/address-setting&gt;
+   </programlisting>
+</chapter>

Copied: trunk/docs/user-manual/en/large-messages.xml (from rev 6908, trunk/docs/user-manual/en/modules/large-messages.xml)
===================================================================
--- trunk/docs/user-manual/en/large-messages.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/large-messages.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="large-messages">
+    <title>Large Messages</title>
+    <para>JBoss Messaging supports sending and receiving of messages larger than it would fit on
+        client's or server's memory. The only limit is the disk space.</para>
+    <para>Large messages are broken into smaller pieces and sent through the transport and saved as
+        files on the server. Flow control (<xref linkend="flow-control"/>) is used on the
+        transmission to prevent overusing the channel or running out of memory during the
+        transmission process, so it is possible to send and receive very large messages. </para>
+    <para>For example, it is possible to send an 8GiB message even if you only had 50MiB of RAM on
+        either client and server. </para>
+    <section id="large.message.configuring">
+        <title>Configuring the server</title>
+        <para>Large messages are stored on a disk folder on the server side, as configured on the
+            main configuration file.</para>
+        <para>The configuration property <literal>large-messages-directory</literal> specifies where
+            large messages are stored.</para>
+        <programlisting>&lt;configuration xmlns="urn:jboss:messaging"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
+
+...
+
+&lt;large-message-directory> *** type any folder you choose *** &lt;/large-message-directory>
+
+...
+
+&lt;/configuration</programlisting>
+        <para>By default the large message directory is <literal>data/largemessages</literal></para>
+    </section>
+    <section>
+        <title>Setting the limits</title>
+        <para>The definition of what is a large message is done on the session factory. For example,
+            you may configure a factory on the http transport considering a message as large when
+            its size is greater than 10KiB and another one on the socket transport considering
+            messages greater than 200KiB.</para>
+        <para>By default the min large message size is 100KiB.</para>
+        <section id="large-messages.core.config">
+            <title>Using Core API</title>
+            <para>If the JBoss Messaging Core API is used, the minimal large message size is
+                specified by <literal>ClientSessionFactory.setMinLargeMessageSize</literal>.</para>
+            <programlisting>ClientSessionFactory factory = new ClientSessionFactoryImpl(new 
+                        TransportConfiguration(NettyConnectorFactory.class.getName()), null);
+factory.setMinLargeMessageSize(25 * 1024);</programlisting>
+            <para><xref linkend="configuring-transports.client.side"/> will provide more information
+                on how to instantiate the session factory.</para>
+        </section>
+        <section>
+            <title>Using JMS</title>
+            <para>If JNDI is used to look up the connection factory, the minimal large message size
+                is specified in <literal>jbm-jms.xml</literal></para>
+            <programlisting>...
+&lt;connection-factory name="ConnectionFactory">
+&lt;connector-ref connector-name="netty"/>
+&lt;entries>
+   &lt;entry name="ConnectionFactory"/>
+   &lt;entry name="XAConnectionFactory"/>
+&lt;/entries>
+                
+&lt;min-large-message-size>250000&lt;/min-large-message-size>
+&lt;/connection-factory>
+...</programlisting>
+            <para>If the connection factory is being instantiate directly, the minimal large message
+                size is specified by <literal
+                    >JBossConnectionFactory.setMinLargeMessageSize</literal>.</para>
+        </section>
+    </section>
+    <section>
+        <title>Streaming large messages</title>
+        <para>JBoss Messaging supports setting the body of messages using input and output streams
+                (<literal>java.lang.io</literal>)</para>
+        <para>This is a very efficient way of sending and receiving large messages, the stream will
+            be used directly by JBoss Messaging during the transmission being a very fast
+            process.</para>
+        <para>For messages being sent it is possible to set the input stream and as the message is
+            being transmitted the input stream is read.</para>
+        <para>For messages being received it is possible to set the output stream and as the server
+            sends more packets the output stream will receive the body of the message. </para>
+        <para>You may choose to block while the output stream is recovered using the method <literal
+                >ClientMessage.saveOutputStream</literal> or do it asynchronously using the method
+                <literal>ClientMessage.setOutputstream</literal>. If you choose the non blocking
+            method the caller of the method won't wait the transmission to finish after <literal
+                >setOutputStream</literal> is called so you need to keep the message consumer
+            active.</para>
+        <para>You can use any kind of stream you like. The most common use case is to send files
+            stored in your disk, but you could also send things like JDBC Blobs, <literal
+                >SocketInputStream</literal>, things you recovered from <literal
+                >HTTPRequest</literal> etc. Anything as long as it implements <literal
+                >java.io.InputStream</literal> for sending messages or <literal
+                >java.io.OutputStream</literal> for receiving them.</para>
+        <section>
+            <title>Streaming over Core API</title>
+            <para>The following table shows a list of methods available at <literal
+                    >ClientMessage</literal> which are also available through JMS by the use of
+                object properties.</para>
+            <table frame="topbot" id="large-messages.ClientMessageAPI">
+                <title>org.jboss.messaging.core.client.ClientMessage API</title>
+                <tgroup cols="3">
+                    <colspec colname="Name" colnum="1"/>
+                    <colspec colname="Descr" colnum="2"/>
+                    <colspec colname="JMS" colnum="3"/>
+                    <thead>
+                        <row>
+                            <entry>Name</entry>
+                            <entry>Description</entry>
+                            <entry>JMS Equivalent Property</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>setBodyInputStream(InputStream)</entry>
+                            <entry>Set the InputStream used on a message that will be sent over a
+                                producer</entry>
+                            <entry>JMS_JBM_InputStream</entry>
+                        </row>
+                        <row>
+                            <entry>setOutputStream(OutputStream)</entry>
+                            <entry>Set the OutputStream that will receive the content of a message
+                                received in a non blocking way</entry>
+                            <entry>JMS_JBM_OutputStream</entry>
+                        </row>
+                        <row>
+                            <entry>saveOutputStream(OutputStream)</entry>
+                            <entry>Save the content of the message to the <literal
+                                    >OutputStream</literal>. It will block until the entire content
+                                is transferred to the <literal>OutputStream</literal>.</entry>
+                            <entry>JMS_JBM_SaveStream</entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+            <para> Set the output stream when receiving a core message: </para>
+            <programlisting>
+...
+ClientMessage msg = consumer.receive(...);
+
+
+// This will block here until the stream was transferred
+msg.saveOutputStream(someOutputStream); 
+
+ClientMessage msg2 = consumer.receive(...);
+
+// This will not wait the transfer to finish
+msg.setOutputStream(someOtherOutputStream); 
+...
+                
+            </programlisting>
+            <para> Set the input stream when sending a core message: </para>
+            <programlisting>
+...
+ClientMessage msg = session.createMessage();
+msg.setInputStream(dataInputStream);
+...
+            </programlisting>
+        </section>
+        <section id="large-messages.streaming.over.jms">
+            <title>Streaming over JMS</title>
+            <para>When using JMS JBoss Messaging maps the streaming methods as object properties as
+                seen on <xref linkend="large-messages.ClientMessageAPI"/>. You can use the method
+                    <literal>Message.setObjectProperty</literal> to set the streaming.</para>
+            <para>The <literal>InputStream</literal> can be defined through the JMS Object Property
+                JMS_JBM_InputStream on messages being sent:</para>
+            <programlisting>
+BytesMessage message = session.createBytesMessage();
+
+FileInputStream fileInputStream = new FileInputStream(fileInput);
+
+BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
+
+message.setObjectProperty("JMS_JBM_InputStream", bufferedInput);
+
+someProducer.send(message);</programlisting>
+            <para>The <literal>OutputStream</literal> can be set through the JMS Object Property
+                JMS_JBM_SaveStream on messages being received in a blocking way.</para>
+            <programlisting>
+BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
+                
+File outputFile = new File("huge_message_received.dat");
+                
+FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
+                
+BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
+                
+// This will block until the entire content is saved on disk
+messageReceived.setObjectProperty("JMS_JBM_SaveStream", bufferedOutput);
+            </programlisting>
+            <para>Setting the <literal>OutputStream</literal> could also be done in a non blocking
+                way using the property JMS_JBM_InputStream.</para>
+            <programlisting>
+// This won't wait the stream to finish. You need to keep the consumer active.
+messageReceived.setObjectProperty("JMS_JBM_InputStream", bufferedOutput);
+            </programlisting>
+            <warning>
+                <para>When using JMS, Streaming Large Message is only supported on <literal
+                        >StreamMessage</literal> and <literal>BytesMessage</literal> because of the
+                    extra information required to process other types of messages</para>
+            </warning>
+        </section>
+    </section>
+    <section>
+        <title>Not using streaming</title>
+        <para>You may choose to not use the <literal>InputStream</literal> or <literal
+                >OutputStream</literal> capability over JMS or core API even knowing streaming would
+            be the most performatic approach. </para>
+        <para>You could still access the data transparently both using the core API or JMS.</para>
+        <para>On the Core API just get the bytes of the body as you normally would.</para>
+        <programlisting>ClientMessage msg = consumer.receive();
+         
+byte[] bytes = new byte[1024];
+for (int i = 0 ;  i &lt; msg.getBodySize(); i += bytes.length)
+{
+   msg.getBody().readBytes(bytes);
+   // Whatever you want to do with the bytes
+}</programlisting>
+        <para>If using JMS API, <literal>BytesMessage</literal> and <literal>StreamMessage</literal>
+            also supports it transparently.</para>
+        <programlisting>BytesMessage rm = (BytesMessage)cons.receive(10000);
+
+byte data[] = new byte[1024];
+
+for (int i = 0; i &lt; rm.getBodyLength(); i += 1024)
+{
+   int numberOfBytes = rm.readBytes(data);
+   // Do whatever you want with the data
+}        </programlisting>
+    </section>
+    <section>
+        <title>Other Types of Messages</title>
+        <para>JBoss Messaging supports large messages of type <literal>TextMessage</literal>,
+                <literal>ObjectMessage</literal> and <literal>MapMessage</literal> transparently.
+            However those types of message will require a full reconstruction in memory in order to
+            work properly.</para>
+        <para>For example: You may choose to send a 1MiB String over a TextMessage. When you read
+            the message Java will need to parse the body of the message back into a String, so you
+            need to have enough memory to allocate your large messages when using those types. If
+            you use <literal>BytesMessage</literal> or <literal>StreamMessage</literal> this
+            restriction won't apply.</para>
+    </section>
+    <section>
+        <title>Resending a large message</title>
+        <para>As large messages are broken into smaller packets, we send them as a streaming from
+            server to client. Those message bodies are not kept in memory so once they are read
+            their body is gone therefore it is not possible to resend a large message.</para>
+        <para>As a result resending large messages after reading them will not work as seen on this
+            example:</para>
+        <programlisting>BytesMessage bm = (BytesMessage)cons.receive(1000);
+                
+bm.setObjectProperty("JMS_JBM_SaveStream", bufferedOutput);
+                                
+/// <emphasis role="bold">This will not work! The body streaming is already gone!</emphasis>
+someOtherProducer.send(bm); // resending the message to another destination;            </programlisting>
+    </section>
+    <section id="large-messages.example">
+        <title>Large message example</title>
+        <para>The <ulink url="../../../../examples/jms/large-message/readme.html"><literal
+                    >large-message</literal> Example</ulink> shows how large message is configured
+            and used with JMS.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/last-value-queues.xml (from rev 6908, trunk/docs/user-manual/en/modules/last-value-queues.xml)
===================================================================
--- trunk/docs/user-manual/en/last-value-queues.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/last-value-queues.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="last-value-queues">
+    <title>Last-Value Queues</title>
+       <para>Last-Value queues are special queues which discard any messages when
+        a newer message with the same value for a well-defined Last-Value property is put in the queue.
+        In other words, a Last-Value queue only retains the last value.</para>
+
+       <para>A typical example for Last-Value queue is for stock prices, where you are only 
+          interested by the latest value for a particular stock.</para>
+
+       <section>
+          <title>Configuring Last-Value Queues</title>
+          <para>Last-value queues are defined in the address-setting configuration:</para>
+          <programlisting>
+    &lt;address-setting match="jms.queue.lastValueQueue"&gt;
+       &lt;last-value-queue&gt;true&lt;/last-value-queue&gt;
+    &lt;/address-setting&gt;
+            </programlisting>
+          <para>By default, <literal>last-value-queue</literal> is false. Address wildcards can be used
+          to configure Last-Value queues for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+       </section>
+
+       <section>
+          <title>Using Last-Value Property</title>
+          <para>The property name used to identify the last value is <literal>"_JBM_LVQ_NAME"</literal>
+          (or the constant <literal>MessageImpl.HDR_LAST_VALUE_NAME</literal> from the Core API).</para>
+          <para>For example, if two messages with the same value for the Last-Value property are
+             sent to a Last-Value queue, only the latest message will be kept in the queue:</para>
+          <programlisting>
+             // send 1st message with Last-Value property set to STOCK_NAME
+             TextMessage message = session.createTextMessage("1st message with Last-Value property set");
+             message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
+             producer.send(message);
+
+             // send 2nd message with Last-Value property set to STOCK_NAME             
+             message = session.createTextMessage("2nd message with Last-Value property set");
+             message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
+             producer.send(message);
+             
+             ...
+             
+             // only the 2nd message will be received: it is the latest with the Last-Value property set
+             TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
+             System.out.format("Received message: %s\n", messageReceived.getText());             
+            </programlisting>
+       </section>
+          
+       <section>
+          <title>Example</title>
+          <para>The <ulink url="../../../../examples/jms/last-value-queue/readme.html"><literal>last-value-queue</literal> example</ulink> shows
+             how last value queues are configured and used with JMS.</para>
+       </section>
+</chapter>

Copied: trunk/docs/user-manual/en/logging.xml (from rev 6908, trunk/docs/user-manual/en/modules/logging.xml)
===================================================================
--- trunk/docs/user-manual/en/logging.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/logging.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="logging">
+    <title>Logging</title>
+    <para>JBM leverages the Java Logging framework, JUL, for all its logging meaning we have no
+        dependencies on any logging framework. Users can provide their own logging handler to use or
+        alternatively use one of the handlers provided by JBM. There are 2 of these a Log4j handler
+        and a JBoss logging handler.</para>
+    <para>The handlers are configured via the JUL logging.properties file. This default location for
+        this file is under the <literal>lib</literal> directory found in the Java home directory
+        however can be overriden. The standalone JBM server does this and the <literal
+            >logging.properties</literal> file can be found under the config directory of the JBM
+        installation. </para>
+    <para>To use the Log4j  handler edit the <literal>logging.properties</literal> file and change
+        the <literal>handlers</literal> property to:</para>
+    <programlisting>handlers=org.jboss.messaging.integration.logging.Log4jLoggerHandler</programlisting>
+    <para>A log4j config file <literal>log4j.xml</literal> is provided for configuring Log4j. </para>
+    <para>To use the JBoss handler edit the <literal>logging.properties</literal> file and change
+        the <literal>handlers</literal> propert to:</para>
+    <programlisting>handlers=org.jboss.messaging.integration.logging.JBossLoggerHandler</programlisting>
+    <para>If using the JBoss handler the property <literal
+            >org.jboss.logging.Logger.pluginClass</literal> must be set. By default this is set to
+            <literal>org.jboss.messaging.integration.logging.JBMLoggerPlugin</literal> in the
+        standalone server. Only change this property if you want to use your own plugin
+        class.</para>
+    <note>
+        <para>If running JBM within the JBoss Application Server logging will default to what ever
+            the AS is using. Refer to the AS docs for more info on how to configure logging.</para>
+    </note>
+</chapter>

Copied: trunk/docs/user-manual/en/management.xml (from rev 6908, trunk/docs/user-manual/en/modules/management.xml)
===================================================================
--- trunk/docs/user-manual/en/management.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/management.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,751 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="management">
+   <title>Management</title>
+
+   <para>While JBoss Messaging servers are up and running, it is possible to interact with it
+      to modify its settings, create new resources (e.g. JMS queues and topics), inspect
+      these resources (e.g. how many messages are currently held in a queue) and interact
+      with it (e.g. to remove messages from a queue). All the operations allows to
+      <emphasis>manage</emphasis> JBoss Messaging.</para>
+    <para>There are 3 ways to manage JBoss Messaging:</para>
+    <itemizedlist>
+      <listitem><para>Using JMX -- JMX is the standard way to manage Java applications</para></listitem>
+      <listitem><para>Using Core API -- management operations are sent to JBoss Messaging server
+         using <emphasis>Core messages</emphasis></para></listitem>
+      <listitem><para>Using JMS API -- management operations are sent to JBoss Messaging server
+         using <emphasis>JMS messages</emphasis></para></listitem>
+    </itemizedlist>
+    <para>There are 3 ways to manage JBoss Messaging but they all allow the same set of operations.
+       If it is possible to manage a resource using JMX, it is also possible to achieve the same
+       result using Core messages or JMS messages.</para>
+    <para>This choice depends on your requirements, your application settings and your environment to
+       decide which way suits you best.</para>
+    
+   <section>
+      <title>The Management API</title>
+      <para>Regardless of the way you <emphasis>invoke</emphasis> management operations, the management API
+      is the same.</para>
+      <para>For each <emphasis>managed resource</emphasis>, there exists a Java interface describing
+      what can be invoked for this type of resource.</para>
+      <para>JBoss Messaging exposes its managed resources in 2 packages:</para>
+      <itemizedlist>
+         <listitem><para><emphasis>Core</emphasis> resources are located in the 
+            <literal>org.jboss.messaging.core.management</literal> package</para></listitem>
+         <listitem><para><emphasis>JMS</emphasis> resources are located in the 
+            <literal>org.jboss.messaging.jms.server.management</literal> package</para></listitem>
+      </itemizedlist>
+      <para>The way to invoke a <emphasis>management operations</emphasis> depends wether JMX, Core messages, or JMS Messages are used.</para>
+      
+      <section>
+         <title>Core Management API</title>
+         <para>JBoss Messaging defines a Core Management API to manage Core resources.</para>
+         
+         <section>
+            <title>Core Server Management</title>
+         
+            <itemizedlist>
+               <listitem>
+                  <para>Creating and destroying queues</para>
+                  <para>Core queues can be created (resp. destroyed) using the management operations
+                     <literal>createQueue()</literal> or <literal>deployQueue()</literal> (resp. <literal>destroyQueue()</literal>)
+                     on the <literal>MessagingServerControlMBean</literal> (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Server</literal>
+                     or the resource name <literal>core.server</literal>)</para>
+                  <para><literal>deployQueue</literal> will fail if the queue already exists while <literal>createQueue</literal> will do nothing.</para>
+               </listitem>
+               <listitem>
+                  <para>Listing and closing remote connections</para>
+                  <para>Client's remote addresses can be retrieved using <literal>listRemoteAddresses()</literal>. It is also possible
+                     to close the connections associated with a remote address using the <literal>closeConnectionsForAddress()</literal> method.</para>               
+                  <para>Alternatively, connection IDs can be listed using <literal>listConnectionIDs()</literal> and all the
+                     sessions for a given connection ID can be listed using <literal>listSessions()</literal>.</para>
+               </listitem>
+               <listitem>
+                  <para>Transaction heuristic operations</para>
+                  <para>In case of a server crash, when the server restarts, it it possible that some transaction
+                     requires an manual intervention. The <literal>listPreparedTransactions()</literal> method
+                     lists the transactions which are in the prepared states (the transactions are represented as opaque
+                     Base64 Strings.) To commit (resp. rollback) a given prepared transaction, 
+                     the <literal>commitPreparedTransaction</literal>() (resp. <literal>rollbackPreparedTransaction()</literal>)
+                     method can be used to resolve heuristic transactions.</para>
+               </listitem>
+               <listitem>
+                  <para>Enabling and resetting Message counters</para>
+                  <para>Message counters can be enabled (resp. disabled) using the <literal>enableMessageCounters()</literal>
+                     (resp. <literal>disableMessageCounters()</literal>) method. To reset message counters, it is possible to invoke
+                     <literal>resetAllMessageCounters()</literal> and <literal>resetAllMessageCounterHistories()</literal> methods.</para>
+               </listitem>
+               <listitem>
+                  <para>Retrieving the server configuration and attributes</para>
+                  <para>The <literal>MessagingServerControlMBean</literal> exposes JBoss Messaging server configuration
+                  through all its attributes (e.g. <literal>getVersion()</literal> method to retrieve the server's version, etc.)</para>
+               </listitem>
+            </itemizedlist>
+         </section>
+         
+         <section>
+            <title>Core Address Management</title>
+            <para><para>Core addresses can be managed using the 
+               <literal>AddressControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Address,name="&lt;the address name&gt;"</literal>
+               or the resource name <literal>core.address.&lt;the address name&gt;</literal>).</para>
+            </para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>Modifying roles and permissions for an address</para>
+                  <para>You can add (resp. remove) roles associated to a queue using the
+                     <literal>addRole()</literal> (resp. <literal>removeRole()</literal>) method.
+                     You can list all the roles
+                     associated to the queue with the <literal>getRoles()</literal> method</para>
+               </listitem>   
+            </itemizedlist>
+         </section>
+         
+         <section>
+            <title>Core Queue Management</title>
+         
+            <para>The bulk of the Core management API deals with Core queues. The <literal>QueueControlMBean</literal> class
+               defines the Core queue management operations (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Queue,address="&lt;the bound address&gt;",name="&lt;the queue name&gt;"</literal>
+               or the resource name <literal>core.queue.&lt;the queue name&gt;</literal>).</para>
+            <para>Most of the management operations on the queues
+               takes either a single message ID (e.g. to remove a single message) or a filter (e.g. to expire all messages 
+               with a given property.)</para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>Expiring, sending to a dead letter address and moving messages</para>
+                  <para>Messages can be expired from a queue by using the <literal>expireMessages()</literal> method.
+                     If an expiry address is defined, messages will be be sent to it, otherwise they are discarded.
+                     The queue's expiry address can be set with the <literal>setExpiryAddress()</literal> method.</para>
+                  <para>Messages can also be sent to a dead letter address with the <literal>sendMessagesToDeadLetterAddress()</literal> method. It returns
+                     the number of messages which are sent to the dead letter address. If a dead letter address is not defined, message are removed from the queue
+                     and discarded.
+                     The queue's dead letter address can be set with the <literal>setDeadLetterAddress()</literal> method.</para>
+                  <para>Messages can also be moved from a queue to another queue by using the <literal>moveMatchingMessages()</literal> method.</para>
+               </listitem>
+               <listitem>
+                  <para>Listing and removing messages</para>
+                  <para>Messages can be listed from a queue by using the <literal>listMessages()</literal> method which
+                     returns an array of <literal>Map</literal>, one <literal>Map</literal> for each message.</para>
+                  <para>Messages can also be removed from the queue by using the <literal>removeMatchingMessages()</literal> method 
+                     which returns a <literal>boolean</literal> for the single message ID variant or the number of removed
+                     messages for the filter variant.</para>
+               </listitem>
+               <listitem>
+                  <para>Counting messages</para>
+                  <para>The number of messages in a queue is returned by the <literal>getMessageCount()</literal> method.
+                     Alternatively, the <literal>countMessages()</literal> will return the number of messages in the queue
+                     which <emphasis>match a given filter</emphasis></para>
+               </listitem>
+               <listitem>
+                  <para>Changing message priority</para>
+                  <para>The message priority can be changed by using the <literal>changeMessagesPriority()</literal> method 
+                     which returns a <literal>boolean</literal> for the single message ID variant or the number of updated
+                     messages for the filter variant.</para>
+               </listitem>
+               <listitem>
+                  <para>Message counters</para>
+                  <para>Message counters can be listed for a queue with the <literal>listMessageCounter()</literal>
+                     and <literal>listMessageCounterHistory()</literal> methods (see <xref linkend="management.message-counters" />).
+                     The message counters can also be reset for a single queue using the <literal>resetMessageCounter()</literal>
+                     method.</para>
+               </listitem>
+               <listitem>
+                  <para>Retrieving the queue attributes</para>
+                  <para>The <literal>QueueControlMBean</literal> exposes Core queue settings
+                  through its attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's filter
+                  if it was created with one, <literal>isDurable()</literal> to know wether the queue is durable or not, etc.)</para>
+               </listitem>            
+            </itemizedlist>
+         </section>
+         
+         <section>
+            <title>Other Core Resources Management</title>
+         
+            <para>JBoss Messaging allow to start and stop its remote resources (acceptors, diverts, bridges, etc.)
+               so that a server can be made off line for a given period of time without stopping it completely (e.g. if other
+               management operations must be performed such as resolving heuristic transactions). These resources
+               are:</para>
+               
+            <itemizedlist>
+               <listitem>
+                  <para>Acceptors</para>
+                  <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>AcceptorControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Acceptor,name="&lt;the acceptor name&gt;"</literal>
+                     or the resource name <literal>core.acceptor.&lt;the address name&gt;</literal>). Acceptor's parameters can be retrieved
+                     using the <literal>AcceptorControlMBean</literal> attributes (see <xref linkend="configuring-transports.acceptors" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Diverts</para>
+                  <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>DivertControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Divert,name=&lt;the divert name&gt;</literal>
+                     or the resource name <literal>core.divert.&lt;the divert name&gt;</literal>). Divert's parameters can be retrieved
+                     using the <literal>DivertControlMBean</literal> attributes (see <xref linkend="diverts" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Bridges</para>
+                  <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>BridgeControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Bridge,name="&lt;the bridge name&gt;"</literal>
+                     or the resource name <literal>core.bridge.&lt;the bridge name&gt;</literal>). Bridge's parameters can be retrieved
+                     using the <literal>BridgeControlMBean</literal> attributes (see <xref linkend="core-bridges" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Broadcast groups</para>
+                  <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>BroadcastGroupControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=BroadcastGroup,name="&lt;the broadcast group name&gt;"</literal>
+                     or the resource name <literal>core.broadcastgroup.&lt;the broadcast group name&gt;</literal>). Broadcast group's parameters can be retrieved
+                     using the <literal>BroadcastGroupControlMBean</literal> attributes (see <xref linkend="clusters.broadcast-groups" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Discovery groups</para>
+                  <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>DiscoveryGroupControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=DiscoveryGroup,name="&lt;the discovery group name&gt;"</literal>
+                     or the resource name <literal>core.discovery.&lt;the discovery group name&gt;</literal>). Discovery group's parameters can be retrieved
+                     using the <literal>DiscoveryGroupControlMBean</literal> attributes (see <xref linkend="clusters.discovery-groups" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Cluster connections</para>
+                  <para>They can be  started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
+                     on the <literal>ClusterConnectionControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=ClusterConnection,name="&lt;the cluster connection name&gt;"</literal>
+                     or the resource name <literal>core.clusterconnection.&lt;the cluster connection name&gt;</literal>). Cluster connection's parameters can be retrieved
+                     using the <literal>ClusterConnectionControlMBean</literal> attributes (see <xref linkend="clusters.cluster-connections" />)</para>
+               </listitem>
+            </itemizedlist>
+         </section>                  
+      </section>
+
+      <section>
+         <title>JMS Management API</title>
+         <para>JBoss Messaging defines a JMS Management API to manage JMS <emphasis>administrated objects</emphasis>.</para>
+         
+         <section>
+            <title>JMS Server Management</title>
+            <para>JMS Resources (connection factories and destinations) can be created using the 
+               <literal>JMSServerControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Server</literal>
+               or the resource name <literal>jms.server</literal>).</para>
+   
+            <itemizedlist>
+               <listitem>
+                  <para>Creating/destroying connection factories</para>
+                  <para>JMS connection factories can be created (resp. destroyed) using the <literal>createConnectionFactory()</literal>
+                     methods (resp. <literal>destroyConnectionFactory()</literal>) methods. 
+                     These connection factories are bound to JNDI so that JMS clients can look them up</para>
+               </listitem>            
+               <listitem>
+                  <para>Creating/destroying queues</para>
+                  <para>JMS queues can be created (resp. destroyed) using the <literal>createQueue()</literal>
+                     methods (resp. <literal>destroyQueue()</literal>) methods. 
+                     These queues are bound to JNDI so that JMS clients can look them up</para>
+               </listitem>            
+               <listitem>
+                  <para>Creating/destroying topics</para>
+                  <para>JMS topics can be created (resp. destroyed) using the <literal>createTopic()</literal>
+                     methods (resp. <literal>destroyTopic()</literal>) methods. 
+                     These topics are bound to JNDI so that JMS clients can look them up</para>
+               </listitem>            
+               <listitem>
+                  <para>Listing and closing remote connections</para>
+                  <para>JMS Client's remote addresses can be retrieved using <literal>listRemoteAddresses()</literal>. It is also possible
+                     to close the connections associated with a remote address using the <literal>closeConnectionsForAddress()</literal> method.</para>               
+                  <para>Alternatively, connection IDs can be listed using <literal>listConnectionIDs()</literal> and all the
+                     sessions for a given connection ID can be listed using <literal>listSessions()</literal>.</para>
+               </listitem>            
+            </itemizedlist>
+         </section>
+         
+         <section>
+            <title>JMS ConnectionFactory Management</title>
+         
+            <para>JMS Connection Factories can be managed using the 
+               <literal>ConnectionFactoryControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=ConnectionFactory,name="&lt;the connection factory name&gt;"</literal>
+               or the resource name <literal>jms.connectionfactory.&lt;the connection factory name&gt;</literal>).</para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>Retrieving connection factory attributes</para>
+                  <para>The <literal>ConnectionFactoryControlMBean</literal> exposes JMS ConnectionFactory
+                  configuration through its attributes (e.g. <literal>getConsumerWindowSize()</literal> to retrieve the 
+                  consumer window size for flow control, <literal>isBlockOnNonPersistentSend()</literal> to know wether the 
+                  producers created from the connection factory will block or not when sending non-persistent messages, etc.)</para>
+               </listitem>            
+            </itemizedlist>
+         </section>
+   
+         <section>
+            <title>JMS Queue Management</title>
+         
+            <para>JMS Queues can be managed using the 
+               <literal>JMSQueueControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Queue,name="&lt;the queue name&gt;"</literal>
+               or the resource name <literal>jms.queue.&lt;the queue name&gt;</literal>).</para>
+               <literal>The management operations on a JMS queue are very similar to the operations on a Core queue.</literal>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>Expiring, sending to a dead letter address and moving messages</para>
+                  <para>Messages can be expired from a queue by using the <literal>expireMessages()</literal> method.
+                     If an expiry address is defined, messages will be be sent to it, otherwise they are discarded.
+                     The queue's expiry address can be set with the <literal>setExpiryAddress()</literal> method.</para>
+                  <para>Messages can also be sent to a dead letter address with the <literal>sendMessagesToDeadLetterAddress()</literal> method. It returns
+                     the number of messages which are sent to the dead letter address. If a dead letter address is not defined, message are removed from the queue
+                     and discarded.
+                     The queue's dead letter address can be set with the <literal>setDeadLetterAddress()</literal> method.</para>
+                  <para>Messages can also be moved from a queue to another queue by using the <literal>moveMatchingMessages()</literal> method.</para>
+               </listitem>
+               <listitem>
+                  <para>Listing and removing messages</para>
+                  <para>Messages can be listed from a queue by using the <literal>listMessages()</literal> method which
+                     returns an array of <literal>Map</literal>, one <literal>Map</literal> for each message.</para>
+                  <para>Messages can also be removed from the queue by using the <literal>removeMatchingMessages()</literal> method 
+                     which returns a <literal>boolean</literal> for the single message ID variant or the number of removed
+                     messages for the filter variant.</para>
+               </listitem>
+               <listitem>
+                  <para>Counting messages</para>
+                  <para>The number of messages in a queue is returned by the <literal>getMessageCount()</literal> method.
+                     Alternatively, the <literal>countMessages()</literal> will return the number of messages in the queue
+                     which <emphasis>match a given filter</emphasis></para>
+               </listitem>
+               <listitem>
+                  <para>Changing message priority</para>
+                  <para>The message priority can be changed by using the <literal>changeMessagesPriority()</literal> method 
+                     which returns a <literal>boolean</literal> for the single message ID variant or the number of updated
+                     messages for the filter variant.</para>
+               </listitem>
+               <listitem>
+                  <para>Message counters</para>
+                  <para>Message counters can be listed for a queue with the <literal>listMessageCounter()</literal>
+                     and <literal>listMessageCounterHistory()</literal> methods (see <xref linkend="management.message-counters" />)</para>
+               </listitem>
+               <listitem>
+                  <para>Retrieving the queue attributes</para>
+                  <para>The <literal>JMSQueueControlMBean</literal> exposes JMS queue settings
+                  through its attributes (e.g. <literal>isTemporary()</literal> to know wether the queue is temporary or not, 
+                  <literal>isDurable()</literal> to know wether the queue is durable or not, etc.)</para>
+               </listitem>            
+            </itemizedlist>
+         </section>
+         
+         <section>
+            <title>JMS Topic Management</title>         
+   
+            <para>JMS Topics can be managed using the 
+               <literal>TopicControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Topic,name="&lt;the topic name&gt;"</literal>
+               or the resource name <literal>jms.topic.&lt;the topic name&gt;</literal>).</para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>Listing subscriptions and messages</para>
+                  <para>JMS topic's subscriptions can be listed using the <literal>listAllSubscriptions()</literal>,
+                  <literal>listDurableSubscriptions()</literal>, <literal>listNonDurableSubscriptions()</literal> methods.
+                  These methods return arrays of <literal>Object</literal> representing the subscriptions information (subscription name,
+                  client ID, durability, message count, etc.). It is also possible to list the JMS messages for a given
+                  subscription with the <literal>listMessagesForSubscription()</literal> method.</para>
+               </listitem>
+               <listitem>
+                  <para>Dropping subscriptions</para>
+                  <para>Durable subscriptions can be dropped from the topic using the <literal>dropDurableSubscription()</literal> method.</para>
+               </listitem>            
+               <listitem>
+                  <para>Counting subscription's messages</para>
+                  <para>The <literal>countMessagesForSubscription()</literal> method 
+                  can be used to know the number of messages held for a given subscription (with an optional message selector
+                  to know the number of messages matching the selector)</para>
+               </listitem>            
+            </itemizedlist>
+         </section>
+      </section>
+      
+   </section>
+    
+   <section id="management.jmx">
+      <title>Using Management Via JMX</title>
+      <para>JBoss Messaging can be managed using
+         <ulink url="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/">JMX</ulink>.
+      </para>
+      <para>The management API is exposed by JBoss Messaging using MBeans interfaces. JBoss
+         Messaging registers its resources with the domain <literal>org.jboss.messaging</literal>.</para>
+      <para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal>exampleQueue</literal> is:</para>
+      <programlisting>
+   org.jboss.messaging:module=JMS,type=Queue,name="exampleQueue"   
+      </programlisting>
+      <para>and the MBean is:</para>
+      <programlisting>
+   org.jboss.messaging.jms.server.management.JMSQueueControlMBean   
+      </programlisting>
+      
+      <para>The MBean's <literal>ObjectName</literal> are built using the helper class
+         <literal>org.jboss.messaging.core.management.ObjectNames</literal>. You can also use
+         <literal>jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to manage.
+      </para>
+      
+      <para>Managing JBoss Messaging using JMX is identical to management of any Java Applications
+         using JMX. It can be done by reflection or by creating proxies of the MBeans.</para>
+      
+      <section id="management.jmx.configuration">
+         <title>Configuring JMX</title>
+         <para>By default, JMX is enabled to manage JBoss Messaging. It can be disabled by 
+            setting <literal>jmx-management-enabled</literal> to <literal>false</literal> in <literal>jbm-configuration.xml</literal>:</para>
+         <programlisting>
+   &lt;!-- false to disable JMX management for JBoss Messaging --&gt;
+   &lt;jmx-management-enabled&gt;false&lt;/jmx-management-enabled&gt;            
+         </programlisting>
+         
+         <para>If JMX is enabled, JBoss Messaging can be managed locally using <literal>jconsole</literal>.
+         Remote connections to JMX are not enabled by default for security reasons. Please refer to 
+         <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote">Java Management guide</ulink>
+         to configure the server for remote management (system properties must be set in <literal>run.sh</literal>
+         or <literal>run.bat</literal> scripts).</para>
+         
+         <para>By default, JBoss Messaging uses the Java Virtual Machine's <literal>Platform MBeanServer</literal>
+         to register its MBeans. This is configured in JBoss Microcontainer Beans file 
+         (see <xref linkend="server.microcontainer.configuration" />):</para>
+         <programlisting>
+   &lt;!-- MBeanServer --&gt;
+   &lt;bean name="MBeanServer" class="javax.management.MBeanServer"&gt;
+      &lt;constructor factoryClass="java.lang.management.ManagementFactory"
+                         factoryMethod="getPlatformMBeanServer" /&gt;
+   &lt;/bean&gt;            
+         </programlisting>
+      </section>
+
+      <section>
+         <title>Example</title>
+         <para>The <ulink url="../../../../examples/jms/jmx/readme.html"><literal>jmx</literal> example</ulink> shows
+            how to use a remote connection to JMX and MBean proxies to manage JBoss Messaging.</para>
+      </section>        
+   </section>
+
+   <section>
+      <title>Using Management Via Core API</title>
+      <para>Another way to manage JBoss Messaging is by sending Core messages to a special
+         address, the <emphasis>management address</emphasis>.</para>
+         <para><emphasis>Management messages</emphasis> are regular Core messages with well-known
+         properties that the server needs to understand to interact with the management API:</para>
+      <itemizedlist>
+         <listitem><para>The name of the managed resource</para></listitem>
+         <listitem><para>The name of the management operation</para></listitem>
+         <listitem><para>The parameters of the management operation</para></listitem>
+      </itemizedlist>
+      <para>When such a management message is sent to the management address, JBoss Messaging
+         server will handle it, extract the information, invoke the operation on the managed
+         resources and send a <emphasis>management reply</emphasis> to the management message's
+         reply-to address (specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>).
+      </para>
+      <para>A <literal>ClientConsumer</literal> can be used to consumed the management reply
+         and retrieve the result of the operation (if any) stored in the reply's body. For portability, results
+         are returned as a <ulink url="http://json.org">JSON</ulink> String rather than Java Serialization
+         (the <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> can be used
+         to convert the JSON string to Java objects).</para>
+      <para>These steps can be simplified to make it easier to invoke management operations
+         using Core messages:</para>
+      <orderedlist>
+         <listitem><para>create a <literal>ClientRequestor</literal> to send messages to the management
+            address and receive replies</para></listitem>
+         <listitem><para>create a <literal>ClientMessage</literal></para></listitem>
+         <listitem><para>use the helper class <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal>
+            to fill the message with the management properties</para>
+         </listitem>
+         <listitem><para>send the message using the <literal>ClientRequestor</literal></para></listitem>
+         <listitem><para>use the helper class <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal>
+            to retrieve the operation result from the management reply</para>
+         </listitem>         
+      </orderedlist>
+      <para>For example, to know the number of messages in the Core queue <literal>exampleQueue</literal>:</para>
+      <programlisting>
+   ClientSession session = ...
+   ClientRequestor requestor = new ClientRequestor(session, "jbm.management");
+   ClientMessage message = session.createClientMessage(false);
+   ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "MessageCount");
+   ClientMessage reply = requestor.request(m);
+   int count = (Integer) ManagementHelper.getResult(reply);
+   System.out.println("There are " + count + " messages in exampleQueue");
+      </programlisting>
+      <para>Management operation name and parameters must conform to the Java interfaces defined
+         in the <literal>management</literal> packages.</para>
+      <para>Name of the resources are built using the helper class <literal>org.jboss.messaging.core.management.ResourceNames</literal> and are straightforward
+      (<literal>core.queue.exampleQueue</literal> for the Core Queue <literal>exampleQueue</literal>,
+      <literal>jms.topic.exampleTopic</literal> for the JMS Topic <literal>exampleTopic</literal>, etc.).</para>
+      
+      <section id="management.core.configuration">
+         <title>Configuring Core Management</title>
+         <para>the management address to send management messages is configured in <literal>jbm-configuration.xml</literal>:</para>
+         <programlisting>
+   &lt;management-address&gt;jbm.management&lt;/management-address&gt;
+         </programlisting>
+         <para>By default, the address is <literal>jbm.management</literal>.</para>
+         <para>The management address requires a <emphasis>special</emphasis> user permission 
+            <literal>manage</literal> to be able to receive and handle management messages. 
+            This is also configured in jbm-configuration.xml:</para>
+         <programlisting>
+   &lt;!-- users with the admin role will be allowed to manage --&gt; 
+   &lt;!-- JBoss Messaging using management messages        --&gt;
+   &lt;security-setting match="jbm.management"&gt;
+      &lt;permission type="manage" roles="admin" /&gt;
+   &lt;/security-setting&gt;
+         </programlisting>
+      </section>        
+
+   </section>
+
+   <section id="management.jms">
+      <title>Using Management Via JMS</title>
+      <para>Using JMS messages to manage JBoss Messaging is very similar to using Core API.</para>
+      <para>An important difference is that JMS requires to create a JMS Queue to send the messages
+         (instead of an address for the Core API).</para>
+      <para>The <emphasis>management queue</emphasis> is a special queue and needs to be instantiated
+      directly by the client:</para>
+      <programlisting>
+   Queue managementQueue = new JBossQueue("jbm.management", "jbm.management");   
+      </programlisting>
+      <para>All the other steps are the same than for the Core API but they use JMS API instead:</para>
+      <orderedlist>
+         <listitem><para>create a <literal>QueueRequestor</literal> to send messages to the management
+            address and receive replies</para></listitem>
+         <listitem><para>create a <literal>Message</literal></para></listitem>
+         <listitem><para>use the helper class <literal>org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal>
+            to fill the message with the management properties</para>
+         </listitem>
+         <listitem><para>send the message using the <literal>QueueRequestor</literal></para></listitem>
+         <listitem><para>use the helper class <literal>org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal>
+            to retrieve the operation result from the management reply</para>
+         </listitem>         
+      </orderedlist>
+      <para>For example, to know the number of messages in the JMS queue <literal>exampleQueue</literal>:</para>
+      <programlisting>
+   Queue managementQueue = new JBossQueue("jbm.management", "jbm.management");   
+   
+   QueueSession session = ...      
+   QueueRequestor requestor = new QueueRequestor(session, managementQueue);
+   connection.start();
+   Message message = session.createMessage();
+   JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "MessageCount");
+   Message reply = requestor.request(message);
+   int count = (Integer)JMSManagementHelper.getResult(reply);
+   System.out.println("There are " + count + " messages in exampleQueue");
+      </programlisting>
+         
+      <section>
+         <title>Configuring JMS Management</title>
+         <para>Wether JMS or Core API is used for management, the configuration
+            steps are the same (see <xref linkend="management.core.configuration" />).</para>
+      </section>        
+ 
+      <section>
+         <title>Example</title>
+         <para>The <ulink url="../../../../examples/jms/management/readme.html"><literal>management</literal> example</ulink> shows
+            how to use JMS messages to manage JBoss Messaging server.</para>
+      </section>        
+   </section>
+         
+   <section id="management.replication">
+      <title>Management Replication</title>
+      <para>JBoss Messaging allows to <emphasis>replicate</emphasis> a live server on a backup server.
+         This impacts management as resources created on the live server (e.g. a core address)
+         must also be created on the backup server. Otherwise, when failover occurs, the backup server
+         will not be able to handle messages sent to this address since its resources will have been
+         created on the live server only and not on the backup.</para>
+      <para>JBoss Message <emphasis>replicate management operation</emphasis> regardless
+         of the way used to manage (JMX, Core messages, JMS messages). Any management operation invoked
+         on a live server will also be invoked on its backup server to ensure a proper replication of resources
+         and state. For example, you only need to manage the live server: if a queue is created on the live
+         server, JBoss Messaging will ensure that the same resource will also be created on the backup server.</para>
+      <para>If Core messages or JMS messages are used to invoke management operations, replication is handled
+         automatically by JBoss Messaging.</para>
+      <para>To allow this management replication with JMX, JBoss Messaging defines a <emphasis>management cluster password</emphasis>:
+         this special password <emphasis>must be shared by all nodes</emphasis>. To configure it, change the value
+         in <literal>jbm-configuration.xml</literal>:</para>
+      <programlisting>
+   &lt;management-cluster-password&gt;CHANGE ME!!&lt;/management-cluster-password&gt;
+      </programlisting>
+         <para>By default, its value is <literal>CHANGE ME!!</literal>. It is strongly suggested to change it
+         to a safer value (this password is never sent on the network).</para>
+      <para>JBoss Messaging internally uses Core messages to replicate management operations
+         between the live and backup server when JMX is used. By default, there is a timeout of 5s (5000ms) to send
+         a management request from the live server to the backup server and wait for a reply.
+         If a reply is not received before the timeout is hit, JBoss Messaging considers the replication has failed.
+         This timeout can be configured in <literal>jbm-configuration.xml</literal>:</para>
+      <programlisting>
+         &lt;management-request-timeout&gt;5000&lt;/management-request-timeout&gt;
+      </programlisting>
+   </section>
+
+   <section id="management.notifications">
+      <title>Management Notifications</title>
+      <para>JBoss Messaging emits <emphasis>notifications</emphasis> to inform listeners of potentially
+      interesting events (creation of new resources, security violation, etc.).</para>
+      <para>These notifications can be received by 3 different ways:</para>
+      <itemizedlist>
+         <listitem><para>JMX notifications</para></listitem>
+         <listitem><para>Core messages</para></listitem>
+         <listitem><para>JMS messages</para></listitem>
+      </itemizedlist>
+      
+      
+      <section>
+         <title>JMX Notifications</title>
+         <para>If JMX is enabled (see <xref linkend="management.jmx.configuration"/>), JMX notifications 
+         can be received by subscribing to 2 MBeans:</para>
+         <itemizedlist>
+            <listitem><para><literal>org.jboss.messaging:module=Core,type=Server</literal> for notifications on <emphasis>Core</emphasis> resources</para></listitem>
+            <listitem><para><literal>org.jboss.messaging:module=JMS,type=Server</literal> for notifications on <emphasis>JMS</emphasis> resources</para></listitem>
+         </itemizedlist>         
+      </section>
+      
+      <section>
+         <title>Core Messages Notifications</title>         
+         <para>JBoss Messaging defines a special <emphasis>management notification address</emphasis>.
+         Core queues can be bound to this address so that clients will receive management notifications 
+         as Core messages</para>
+         
+         <section id="management.notifications.core.configuration">
+            <title>Configuring The Core Management Notification Address</title>
+            <para>the management notification address to receive management notifications is configured in <literal>jbm-configuration.xml</literal>:</para>
+            <programlisting>
+      &lt;management-notification-address&gt;jbm.notifications&lt;/management-notification-address&gt;
+            </programlisting>
+            <para>By default, the address is <literal>jbm.notifications</literal>.</para>
+         </section>
+         
+         <para>A Core client which wants to receive management notifications must create a Core
+            queue bound to the management notification address. It can then receive the notifications from
+            its queue.</para>
+         <para>Notifications messages are regular Core messages with additional properties corresponding
+            to the notification (its type, when it occurred, the resources which were concerned, etc.).</para>
+         <para>Since notifications are regular Core messages, it is possible to use message selectors
+            to filter out notifications and receives only a subset of all the notifications emitted by the
+            server.</para>         
+      </section>        
+
+      <section>
+         <title>JMS Messages Notifications</title>         
+         <para>JBoss Messaging's notifications can also be received using JMS messages.</para>
+         <para>It is similar to receiving notifications using Core API but an important difference 
+            is that JMS requires to create a JMS Destination to receive the messages (preferably
+            a Topic):</para>
+         <programlisting>
+   Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
+         </programlisting>
+         <para>Once the notification topic is created, you can receive messages from it
+            or set a <literal>MessageListener</literal>:</para>
+         <programlisting>
+   Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
+
+   Session session = ...
+   MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
+      notificationConsumer.setMessageListener(new MessageListener()
+      {
+         public void onMessage(Message notif)
+         {
+            System.out.println("------------------------");
+            System.out.println("Received notification:");
+            try
+            {
+               Enumeration propertyNames = notif.getPropertyNames();
+               while (propertyNames.hasMoreElements())
+               {
+                  String propertyName = (String)propertyNames.nextElement();
+                  System.out.format("  %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
+               }
+            }
+            catch (JMSException e)
+            {
+            }
+            System.out.println("------------------------");
+         }            
+      });            
+         </programlisting>
+      </section>
+
+      <section>
+         <title>Example</title>
+         <para>The <ulink url="../../../../examples/jms/management-notifications/readme.html"><literal>management-notifications</literal> example</ulink> shows
+            how to use a JMS <literal>MessageListener</literal> to receive management notifications
+            from JBoss Messaging server.</para>
+      </section>        
+   </section>
+
+   <section id="management.message-counters">
+      <title>Message Counters</title>
+      <para>Message counters can be used to have informations on queue <emphasis>over time</emphasis> 
+         as JBoss Messaging keeps a history on queue metrics.</para>
+      <para>They can be used to show <emphasis>trends</emphasis> on queues. For example, using the management API,
+         it would be possible to query the number of messages in a queue at regular interval. However, this would
+         not be enough to know if the queue is used: the number of messages can remain constant because
+         nobody is sending or receiving messages from the queue or because there are as many messages sent to the 
+         queue than messages consumed from it. The number of messages in the queue remains the same in both cases
+         but its use is widely different.</para>
+      <para>Message counters gives additional information about the queues:</para>
+      <itemizedlist>
+         <listitem>
+            <para><literal>count</literal></para>
+            <para>The <emphasis>total</emphasis> number of messages added to the queue since the server
+            was started</para>
+         </listitem>
+         <listitem>
+            <para><literal>countDelta</literal></para>
+            <para>the number of messages added to the queue <emphasis>since the last message counter update</emphasis></para>
+         </listitem>
+         <listitem>
+            <para><literal>depth</literal></para>
+            <para>The <emphasis>current</emphasis> number of messages in the queue</para>
+         </listitem>
+         <listitem>
+            <para><literal>depthDelta</literal></para>
+            <para>The <emphasis>overall</emphasis> number of messages added/removed from the queue <emphasis>since the last message counter update</emphasis>.
+            For example, if <literal>depthDelta</literal> is equal to <literal>-10</literal> this means that overall 10 messages
+            have been removed from the queue (e.g. 2 messages were added and 12 were removed)</para>
+            <para></para>
+         </listitem>
+         <listitem>
+            <para><literal>lastAddTimestamp</literal></para>
+            <para>The timestamp of the last time a message was added to the queue</para>
+         </listitem>
+         <listitem>
+            <para><literal>udpateTimestamp</literal></para>
+            <para>The timestamp of the last message counter update</para>
+         </listitem>
+      </itemizedlist>
+      
+      <section id="configuring.message.counters">
+         <title>Configuring Message Counters</title>
+         <para>By default, message counters are disabled has it consumes memory (the metrics are kept in memory)
+            and CPU (the queues are sampled at regular interval).</para>
+         <para>To enable message counters, you can set it to <literal>true</literal> in <literal>jbm-configuration.xml</literal>:</para>
+         <programlisting>
+   &lt;message-counter-enabled&gt;true&lt;/message-counter-enabled&gt;
+         </programlisting>
+         <para>Message counters keeps a history of the queue metrics (10 days by default) and samples all the queues
+            at regular interval (10 seconds by default). If message counters are enabled, these values should
+            be configured to suit your messaging use case in <literal>jbm-configuration.xml</literal>:</para>
+         <programlisting>
+   &lt;!-- keep history for a week --&gt;
+   &lt;message-counter-max-day-history&gt;7&lt;/message-counter-max-day-history&gt;            
+   &lt;!-- sample the queues every minute (60000ms) --&gt;
+   &lt;message-counter-sample-period&gt;60000&lt;/message-counter-sample-period&gt;
+         </programlisting>
+      </section>        
+
+      <para>Message counters can be retrieved using the Management API. For example, to retrieve message counters on a JMS Queue using JMX:</para>
+      <programlisting>
+   // retrieve a connection to JBoss Messaging's MBeanServer
+   MBeanServerConnection mbsc = ...
+   JMSQueueControlMBean queueControl = (JMSQueueControlMBean)MBeanServerInvocationHandler.newProxyInstance(mbsc,
+                                                                                                         on,
+                                                                                                         JMSQueueControlMBean.class,
+                                                                                                         false);
+   // message counters are retrieved as a JSON String                                                                                                      
+   String counters = queueControl.listMessageCounter();
+   // use the MessageCounterInfo helper class to manipulate message counters more easily
+   MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);         
+   System.out.format("%s message(s) in the queue (since last sample: %s)\n",
+                                 counter.getDepth(),
+                                 counter.getDepthDelta());
+      </programlisting>
+
+      <section>
+         <title>Example</title>
+         <para>The <ulink url="../../../../examples/jms/message-counters/readme.html"><literal>message-counters</literal> example</ulink> shows
+            how to use message counters to retrieve information on a JMS <literal>Queue</literal>.</para>
+      </section>        
+   </section>
+
+</chapter>

Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml	2009-05-20 07:49:41 UTC (rev 6908)
+++ trunk/docs/user-manual/en/master.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -1,48 +1,48 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
         "../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd" [  
-        <!ENTITY appserver-integration   SYSTEM "modules/appserver-integration.xml">     
-        <!ENTITY architecture            SYSTEM "modules/architecture.xml">
-        <!ENTITY client-reconnection     SYSTEM "modules/client-reconnection.xml">     
-        <!ENTITY clusters                SYSTEM "modules/clusters.xml">
-        <!ENTITY configuration-index     SYSTEM "modules/configuration-index.xml">
-        <!ENTITY configuring-transports  SYSTEM "modules/configuring-transports.xml">
-        <!ENTITY connection-ttl          SYSTEM "modules/connection-ttl.xml">
-        <!ENTITY core-bridges            SYSTEM "modules/core-bridges.xml">
-        <!ENTITY diverts                 SYSTEM "modules/diverts.xml">
-        <!ENTITY duplicate-detection     SYSTEM "modules/duplicate-detection.xml">
-        <!ENTITY embedding-jbm           SYSTEM "modules/embedding-jbm.xml">
-        <!ENTITY examples                SYSTEM "modules/examples.xml">
-        <!ENTITY filter-expressions      SYSTEM "modules/filter-expressions.xml">
-        <!ENTITY flow-control            SYSTEM "modules/flow-control.xml">
-        <!ENTITY command-buffering       SYSTEM "modules/command-buffering.xml">
-        <!ENTITY ha                      SYSTEM "modules/ha.xml">
-        <!ENTITY intercepting-operations SYSTEM "modules/intercepting-operations.xml">
-        <!ENTITY interoperability        SYSTEM "modules/interoperability.xml">
-        <!ENTITY jms-core-mapping        SYSTEM "modules/jms-core-mapping.xml">
-        <!ENTITY large-messages          SYSTEM "modules/large-messages.xml">
-        <!ENTITY last-value-queues       SYSTEM "modules/last-value-queues.xml">
-        <!ENTITY logging                 SYSTEM "modules/logging.xml">
-        <!ENTITY management              SYSTEM "modules/management.xml">
-        <!ENTITY message-expiry          SYSTEM "modules/message-expiry.xml">
-        <!ENTITY message-grouping        SYSTEM "modules/message-grouping.xml">
-        <!ENTITY messaging-concepts      SYSTEM "modules/messaging-concepts.xml">       
-        <!ENTITY paging                  SYSTEM "modules/paging.xml">
-        <!ENTITY perf-tuning             SYSTEM "modules/perf-tuning.xml">
-        <!ENTITY persistence             SYSTEM "modules/persistence.xml">
-        <!ENTITY pre-acknowledge         SYSTEM "modules/pre-acknowledge.xml">
-        <!ENTITY preface                 SYSTEM "modules/preface.xml">
-        <!ENTITY project-info            SYSTEM "modules/project-info.xml">
-        <!ENTITY queue-attributes        SYSTEM "modules/queue-attributes.xml">
-        <!ENTITY scheduled-messages      SYSTEM "modules/scheduled-messages.xml">
-        <!ENTITY security                SYSTEM "modules/security.xml">
-        <!ENTITY send-guarantees         SYSTEM "modules/send-guarantees.xml">
-        <!ENTITY thread-pooling          SYSTEM "modules/thread-pooling.xml">
-        <!ENTITY undelivered-messages    SYSTEM "modules/undelivered-messages.xml">
-        <!ENTITY using-core              SYSTEM "modules/using-core.xml">
-        <!ENTITY using-jms               SYSTEM "modules/using-jms.xml">        
-        <!ENTITY using-server            SYSTEM "modules/using-server.xml">
-        <!ENTITY wildcard-syntax         SYSTEM "modules/wildcard-syntax.xml">       
+        <!ENTITY appserver-integration   SYSTEM "appserver-integration.xml">
+        <!ENTITY architecture            SYSTEM "architecture.xml">
+        <!ENTITY client-reconnection     SYSTEM "client-reconnection.xml">
+        <!ENTITY clusters                SYSTEM "clusters.xml">
+        <!ENTITY configuration-index     SYSTEM "configuration-index.xml">
+        <!ENTITY configuring-transports  SYSTEM "configuring-transports.xml">
+        <!ENTITY connection-ttl          SYSTEM "connection-ttl.xml">
+        <!ENTITY core-bridges            SYSTEM "core-bridges.xml">
+        <!ENTITY diverts                 SYSTEM "diverts.xml">
+        <!ENTITY duplicate-detection     SYSTEM "duplicate-detection.xml">
+        <!ENTITY embedding-jbm           SYSTEM "embedding-jbm.xml">
+        <!ENTITY examples                SYSTEM "examples.xml">
+        <!ENTITY filter-expressions      SYSTEM "filter-expressions.xml">
+        <!ENTITY flow-control            SYSTEM "flow-control.xml">
+        <!ENTITY command-buffering       SYSTEM "command-buffering.xml">
+        <!ENTITY ha                      SYSTEM "ha.xml">
+        <!ENTITY intercepting-operations SYSTEM "intercepting-operations.xml">
+        <!ENTITY interoperability        SYSTEM "interoperability.xml">
+        <!ENTITY jms-core-mapping        SYSTEM "jms-core-mapping.xml">
+        <!ENTITY large-messages          SYSTEM "large-messages.xml">
+        <!ENTITY last-value-queues       SYSTEM "last-value-queues.xml">
+        <!ENTITY logging                 SYSTEM "logging.xml">
+        <!ENTITY management              SYSTEM "management.xml">
+        <!ENTITY message-expiry          SYSTEM "message-expiry.xml">
+        <!ENTITY message-grouping        SYSTEM "message-grouping.xml">
+        <!ENTITY messaging-concepts      SYSTEM "messaging-concepts.xml">
+        <!ENTITY paging                  SYSTEM "paging.xml">
+        <!ENTITY perf-tuning             SYSTEM "perf-tuning.xml">
+        <!ENTITY persistence             SYSTEM "persistence.xml">
+        <!ENTITY pre-acknowledge         SYSTEM "pre-acknowledge.xml">
+        <!ENTITY preface                 SYSTEM "preface.xml">
+        <!ENTITY project-info            SYSTEM "project-info.xml">
+        <!ENTITY queue-attributes        SYSTEM "queue-attributes.xml">
+        <!ENTITY scheduled-messages      SYSTEM "scheduled-messages.xml">
+        <!ENTITY security                SYSTEM "security.xml">
+        <!ENTITY send-guarantees         SYSTEM "send-guarantees.xml">
+        <!ENTITY thread-pooling          SYSTEM "thread-pooling.xml">
+        <!ENTITY undelivered-messages    SYSTEM "undelivered-messages.xml">
+        <!ENTITY using-core              SYSTEM "using-core.xml">
+        <!ENTITY using-jms               SYSTEM "using-jms.xml">
+        <!ENTITY using-server            SYSTEM "using-server.xml">
+        <!ENTITY wildcard-syntax         SYSTEM "wildcard-syntax.xml">
         ]>
 <book lang="en">
    <bookinfo>

Copied: trunk/docs/user-manual/en/message-expiry.xml (from rev 6908, trunk/docs/user-manual/en/modules/message-expiry.xml)
===================================================================
--- trunk/docs/user-manual/en/message-expiry.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/message-expiry.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="message-expiry">
+   <title>Message Expiry</title>
+   <para>Messages can be retained in the messaging system for a limited period of time before being
+      removed. JMS specification states that clients should not receive messages that have been
+      expired (but it does not guarantee this will not happen).</para>
+   <para>JBoss Messaging's addresses can be assigned a expiry address so that, when messages are
+      expired, they are removed from the queue and sent to the expiry address. These
+         <emphasis>expired</emphasis> messages can later be consumed for further inspection.</para>
+   <section>
+      <title>Message Expiry</title>
+            <para>Using JBoss Messaging Core API, you can set an expiration time directly on the
+               message:</para>
+            <programlisting>
+      // message will expire in 5000ms from now
+      message.setExpiration(System.currentTimeMillis() + 5000);         
+              </programlisting>
+      <para>JMS MessageProducer allows to set a TimeToLive for the messages it sent:</para>
+      <programlisting>
+// messages sent by this producer will be retained for 5s (5000ms) before expiration           
+producer.setTimeToLive(5000);
+        </programlisting>
+        <para>Expired messages which are consumed from an expiry address have the following properties:</para>
+        <itemizedlist>
+         <listitem>
+            <para><literal>_JBM_ORIG_DESTINATION</literal></para>
+            <para>a String property containing the <emphasis>original destination</emphasis> of the
+            expired message </para>
+         </listitem>
+        <listitem>
+           <para><literal>_JBM_ACTUAL_EXPIRY</literal></para>
+           <para>a Long property containing the <emphasis>actual expiration time</emphasis> of the expired message</para>
+        </listitem>
+        </itemizedlist>
+      
+   </section>
+   <section>
+      <title>Configuring Expiry Addresses</title>
+      <para>Expiry address are defined in the address-setting configuration:</para>
+      <programlisting>
+&lt;!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue --&gt;
+&lt;address-setting match="jms.queue.exampleQueue"&gt;
+   &lt;expiry-address&gt;jms.queue.expiryQueue&lt;/expiry-address&gt;
+&lt;/address-setting&gt;
+        </programlisting>
+      <para>If messages are expired and no expiry address is specified, messages are simply removed
+         from the queue. Address wildcards can be used
+          to configure expiry address for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+   </section>
+   <section id="configuring.expiry.reaper">
+      <title>Configuring The Expiry Reaper Thread</title>
+      <para>A reaper thread is periodically inspecting the queues to check if messages have
+         expired.</para>
+      <para>The reaper thread can be configured with the following properties in <literal
+            >jbm-configuration.xml</literal></para>
+      <itemizedlist>
+         <listitem>
+            <para><literal>message-expiry-scan-period</literal></para>
+            <para>How often the queues will be scanned to detect expired messages (in milliseconds,
+               default is 30000ms)</para>
+         </listitem>
+         <listitem>
+            <para><literal>message-expiry-thread-priority</literal></para>
+            <para>The reaper thread priority (it must be between 0 and 9, 9 being the highest
+               priority, default is 3)</para>
+         </listitem>
+      </itemizedlist>
+   </section>
+   <section>
+      <title>Example</title>
+      <para>The <ulink url="../../../../examples/jms/expiry/readme.html"><literal>expiry</literal> example</ulink> shows
+         how message expiry is configured and used with JMS.</para>
+   </section>
+</chapter>

Copied: trunk/docs/user-manual/en/message-grouping.xml (from rev 6908, trunk/docs/user-manual/en/modules/message-grouping.xml)
===================================================================
--- trunk/docs/user-manual/en/message-grouping.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/message-grouping.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="message-grouping">
+    <title>Message Grouping</title>
+    <para>Message groups are sets of messages that has the following characteristics:</para>
+    <itemizedlist>
+      <listitem><para>Messages in a message group share the same group id, i.e. they have same 
+         group identifier property (<literal>JMSXGroupID</literal> for JMS, 
+         <literal>_JBM_GROUP_ID</literal> for JBoss Messaging Core API).</para></listitem>
+      <listitem><para>Messages in a message group will be all delivered to no more
+         than one of the queue's consumers. The consumer that receives the first message of a group 
+         will receive all the messages that belong to this group.</para></listitem>      
+    </itemizedlist>
+
+    <section>
+       <title>Configuring Message Grouping</title>
+       <para>Message grouping must be enabled in the address-setting configuration
+          by using a specific <literal>distribution-policy-class</literal>:</para>
+       <programlisting>
+          &lt;address-setting match="jms.queue.exampleQueue"&gt;
+             &lt;distribution-policy-class&gt;org.jboss.messaging.core.server.impl.GroupingRoundRobinDistributor&lt;/distribution-policy-class&gt;
+          &lt;/address-setting&gt;
+       </programlisting>
+       <para>By default, <literal>distribution-policy-class</literal> is set to <literal>org.jboss.messaging.core.server.impl.RoundRobinDistributor</literal>
+       and message groups will not be handled by the queue. Address wildcards can be used
+        to configure the distribution policy for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+    </section>
+
+    <section>
+       <title>Using Core API</title>
+       <para>The property name used to identify the message group is <literal>"_JBM_GROUP_ID""</literal>
+       (or the constant <literal>MessageImpl.HDR_GROUP_ID</literal>).</para>
+    </section>
+       
+    <section>
+       <title>Using JMS</title>
+       <para>The property name used to identify the message group is <literal>JMSXGroupID</literal>.</para>
+       <para>Within the same group, messages can also set a <literal>JMSXGroupSeq</literal> 
+         <literal>int</literal> property (starting at 1).</para>
+       <programlisting>
+          // send 2 messages in the same group to ensure the same
+          // consumer will receive both
+          Message message = ...
+          message.setStringProperty("JMSXGroupID", "Group-0");
+          message.setIntProperty("JMSXGroupSeq", 1);
+          producer.send(message);
+
+          message = ...
+          message.setStringProperty("JMSXGroupID", "Group-0");
+          message.setIntProperty("JMSXGroupSeq", 2);
+          producer.send(message);          
+       </programlisting>
+    </section>
+    
+    <section>
+       <title>Example</title>
+       <para>The <ulink url="../../../../examples/jms/message-group/readme.html"><literal>message-group</literal> example</ulink> shows
+          how message groups are configured and used with JMS.</para>
+    </section> 
+</chapter>

Copied: trunk/docs/user-manual/en/messaging-concepts.xml (from rev 6908, trunk/docs/user-manual/en/modules/messaging-concepts.xml)
===================================================================
--- trunk/docs/user-manual/en/messaging-concepts.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/messaging-concepts.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,252 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="messaging-concepts">
+    <title>Messaging Concepts</title>
+    <para>JBoss Messaging is an asynchronous messaging system, an example of <ulink
+            url="http://en.wikipedia.org/wiki/Message_oriented_middleware">Message Oriented
+            Middleware</ulink> , we'll just call them messaging systems in the remainder of this
+        book.</para>
+    <para>We'll first prevent a brief overview of what kind of things messaging systems do and and
+        where they're useful, and the kind of concepts you'll hear about in the messaging
+        world.</para>
+    <para>If you're already familiar with what a messaging system is and what it's capable of, then
+        you can skip this chapter.</para>
+    <para>Messaging systems allow you to loosely couple heteregenous systems together, whilst
+        typically providing reliability, transactions, and many other features.</para>
+    <para>Unlike systems based on a <ulink url="http://en.wikipedia.org/wiki/Remote_procedure_call"
+            >Remote Procedure Call</ulink> (RPC) pattern, messaging systems primarily use an
+        asynchronous message passing pattern with no tight relationship between requests and
+        responses. Most messaging systems also support a request-response mode but this is not a
+        primary feature of messaging systems.</para>
+    <para>Designing systems to be asynchronous from end-to-end allows you to really take advantage
+        of your hardware resources, minimising the amount of threads blocking on IO operations, and
+        to use your network bandwidth to its full capacity. With an RPC approach you have to wait
+        for a response for each request you make so are limited by the network round trip time, or
+            <emphasis role="italic">latency</emphasis> of your network. With an asynchronous you can
+        pipeline flows of messages in different directions, so are limited by the network <emphasis
+            role="italic">bandwidth</emphasis> not the latency. This typically allows you to create
+        much higher performance applications.</para>
+    <para>Messaging systems decouple the senders of messages from the consumers of messages. The
+        senders and consumers of messages are completely independent and know nothing of each other.
+        This allows you to create flexible, loosely coupled systems.</para>
+    <para>Often, large enterprises use a messaging system to implement a message bus which is to
+        loosely couple heterogenous systems together. Message buses often form the core of an <ulink
+            url="http://en.wikipedia.org/wiki/Enterprise_service_bus">Enterprise Service
+        Bus</ulink>. (ESB). Using a message bus to couple disparate systems can allow the system to
+        grow and adapt more flexible as new systems are added and old ones retired, without each
+        system having hard, brittle dependencies on each other.</para>
+    <section>
+        <title>Messaging styles</title>
+        <para>Messaging systems normally support two main styles of asynchronous messaging;<ulink
+                url="http://en.wikipedia.org/wiki/Message_queue"> message queue</ulink> (also known
+            as <emphasis role="italic">point-to-point messaging</emphasis>) and <ulink
+                url="http://en.wikipedia.org/wiki/Publish_subscribe">publish subscribe</ulink>
+            messaging. We'll summarise them briefly here:</para>
+        <section>
+            <title>The Message Queue Pattern</title>
+            <para>With this type of messaging you send a message to a queue. The message is then
+                typically persisted to provide a guarantee of delivery, then some time later the
+                messaging system delivers the message to a consumer. The consumer then processes the
+                message and when it is done, it acknowledges the message. Once the message is
+                acknowledged it disappears from the queue and is not available to be delivered
+                again. If the system crashes before the messaging server receives an acknowledgement
+                from the consumer, then on recovery, the message will be available to be delivered
+                to a consumer again.</para>
+            <para>With point-to-point messaging, there can be many consumers on the queue but a
+                particular message will only ever be consumed by a maximum of one of them. Senders
+                (also known as<emphasis role="italic"> producers</emphasis>) to the queue are
+                completely decoupled from receivers (also known as <emphasis role="italic"
+                    >consumers</emphasis>) of the queue - they do not know of each others
+                existence.</para>
+            <para>A classic example of point to point messaging would be an order queue in a
+                company's book ordering system. Each order is represented as a message which is sent
+                to the order queue. There are many front end ordering systems which send orders to
+                the order queue. When a message arrives on the queue it is persisted - this ensures
+                that if the server crashes the order is not lost. There are many consumers on the
+                order queue - each representing an instance of an order processing component - this
+                can be on different physical machines but consuming from the same queue. The
+                messaging system delivers each message to one and only one of the ordering
+                processing components. Different messages can be processed by order processors, but
+                a single order is only processed by one order processor - this ensures orders aren't
+                processed twice.</para>
+            <para>As an order processor receives a message, its fulfils the order - sends order
+                information to the warehous system and then updates the order database with the
+                order details. Once it's done that it acknowledges the message to tell the server
+                that the order message is done and can be forgotten about. Often the send to the
+                warehouse system, update in database and acknowledgement will be completed in a
+                single transaction to ensure ACID properties.</para>
+        </section>
+        <section>
+            <title>The Publish-Subscribe Pattern</title>
+            <para>With publish-subscribe messaging many senders can send messages to an entity on
+                the server, often called a <emphasis role="italic">topic</emphasis>, e.g. in the JMS
+                world.</para>
+            <para>There can be many subscriptions on a topic, each subscription receives a copy of
+                    <emphasis role="italic">each</emphasis> message sent to the topic. This differs
+                from the message queue pattern where each message is only consumed by a single
+                consumer.</para>
+            <para>Subscriptions can optionally be <emphasis role="italic">durable</emphasis> which
+                means they retain a copy of each message sent to the topic until the subscriber
+                consumes it.</para>
+            <para>An example of publish-subscribe messaging would be a news feed. As news articles
+                are created by different editors around the world they are sent to a news feed
+                topic. There are many subscribers around the world who are interested in receiving
+                news items - each one creates a subscription and the messaging system ensures that a
+                copy of each news message is delivered to each subscription.</para>
+        </section>
+    </section>
+    <section>
+        <title>Delivery guarantees</title>
+        <para>A key feature of most messaging systems is <emphasis role="italic">reliable
+                messaging</emphasis>. With reliable messaging the server gives a guarantee that the
+            message will be delivered once and only once to each consumer of a queue or each
+            subscription of a topic, even in the event of system failure. This is crucial for many
+            businesses - you don't want your orders fulfilled more than once, or your trades to be
+            lost or occur more than once.</para>
+        <para>In other cases you may not care about a once and only once delivery guarantee and are
+            happy to cope with duplicate deliveries. The messaging system allows you to configure
+            which delivery guarantees you require.</para>
+    </section>
+    <section>
+        <title>Transactions</title>
+        <para>Messaging systems typically support the sending and acknowledgement of multiple
+            messages in a single local transaction. JBoss Messaging also supports the sending and
+            acknowledgement of message as part of a large global transaction - using the Java
+            mapping of XA, JTA.</para>
+    </section>
+    <section>
+        <title>Durability</title>
+        <para> Messages are either durable or non durable. Durable messages will persisted in
+            permanent storage and will survive server failure. Non durable messages will not survive
+            server failure or restart. Examples of durable messages might be orders or trades, where
+            they cannot be lost. An example of a non durable message might be a stock price update.
+            This is transitory and there's no need for it to survive a restart. </para>
+    </section>
+    <section>
+        <title>Messaging APIs and protocols</title>
+        <para>How do client applications interact with messaging systems in order to send and
+            consume messages?</para>
+        <para>Several messaging systems provide their own proprietary APIs with which the client
+            communicates with the messaging system.</para>
+        <para>There are also some standard ways of operating with messaging systems and some
+            emerging standards in this space.</para>
+        <para>Let's take a brief look at these:</para>
+        <section>
+            <title>Java Message Service (JMS)</title>
+            <para><ulink url="http://en.wikipedia.org/wiki/Java_Message_Service">JMS</ulink> is part
+                of Sun's JEE specification. It's a Java API that encapsulates both message queue and
+                publish-subscribe messaging patterns. JMS is a lowest common denominator
+                specification - i.e. it was created to encapsulate common functionality of the
+                already existing messaging systems that were available at the time of its
+                creation.</para>
+            <para>JMS is a very popular API and is implemented by most messaging systems. JMS is
+                only available to clients running Java.</para>
+            <para>JMS does not define a standard wire format - it only defines a programmatic API so
+                JMS clients and servers from different vendors cannot interoperate since they will
+                most likely use the vendor's own internal wire protocol.</para>
+            <para>JBoss Messaging provides a fully compliant JMS 1.1 API.</para>
+        </section>
+        <section>
+            <title>System specific APIs</title>
+            <para>Many systems provide their own programmic API for which to interact with the
+                messaging system. The advantage of this it allows the full set of system
+                functionality to be exposed tp the client application. APIs like JMS are not
+                normally rich enough to expose all the extra featurs that most messaging systems
+                provide.</para>
+            <para>JBoss Messaging provides its own core client API for clients to use if they wish
+                to have access to functionality over and above that accesible via the JMS
+                API.</para>
+        </section>
+        <section>
+            <title>STOMP</title>
+            <para><ulink
+                    url="http://en.wikipedia.org/wiki/Streaming_Text_Orientated_Messaging_Protocol"
+                    >STOMP</ulink> is a very simple protocol for interoperating with messaging
+                systems. It defines a wire format, so theoretically any STOMP client can work with
+                any messaging system that supports STOMP. STOMP clients are available in many
+                different programming languages.</para>
+            <para>JBoss Messaging can be used by any STOMP client when using the <ulink
+                    url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> broker which
+                translates STOMP protocol to the JMS API.</para>
+            <para>JBoss Messaging will be shortly implementing the STOMP protocol on the boker, thus
+                avoiding the usage of StompConnect.</para>
+        </section>
+        <section>
+            <title>AMQP</title>
+            <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is an emerging
+                standard for interoperable messaging. It also defines a wire format, so any AMQP
+                client can work with any messaging system that supports AMQP. AMQP clients are
+                available in many different programming languages.</para>
+            <para>JBoss Messaging will shortly be implementing AMQP.</para>
+        </section>
+        <section>
+            <title>REST</title>
+            <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer"
+                    >REST</ulink> approaches to messaging are showing a lot interest recently. With
+                a REST approach messaging resources are manipulated as resources, typically using a
+                simple set of operations on those resources, e.g. PUT, POST, GET etc. REST
+                approaches to messaging often use HTTP as their underlying protocol.</para>
+            <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
+                internet is already tuned to deal with HTTP optimally.</para>
+            <para>JBoss Messaging will shortly be implementing REST.</para>
+        </section>
+    </section>
+    <section>
+        <title>High Availability</title>
+        <para>High Availability (HA) means that the system should remain operation after failure of
+            one or more of the servers. The degree of support for HA varies from messaging system to
+            messaging system.</para>
+        <para>Some messaging systems require you to deal with server side failure by writing some
+            client side code which gets called on event of server failure, and in which you are
+            supposed to recreate your connections to another server.</para>
+        <para>JBoss Messaging provides 100% transparent failover where you don't have have to write
+            any special client side code to deal with failure. On failover JBoss Messaging will
+            automatically fail over your client connections to another server, and your client
+            sessions can continue as if nothing happened.</para>
+    </section>
+    <section>
+        <title>Clusters</title>
+        <para>Many messaging systems allow you to create groups of messaging servers called
+                <emphasis role="italic">clusters</emphasis>. Cluster allow the load of sending and
+            consuming messages to be spread over many servers. This allows your system to be able
+            scale horizontally by adding new servers to the cluster.</para>
+        <para>Degrees of support for clusters varies from messaging system to messaging system, with
+            some systems having fairly basic clusters where the cluster members being hardly aware
+            of each other.</para>
+        <para>JBoss Messaging provides very configurable state of the art clustering where messages
+            can be intelligently load balanced between the servers in the cluster, according to the
+            number of consumers on each node, and whether they are ready for messages.</para>
+        <para>JBoss Messaging also has the ability to automatically redistribute messages between
+            nodes of a cluster to prevent starvation on any particular node.</para>
+        <para>For full details on clustering please the clustering section.</para>
+    </section>
+    <section>
+        <title>Bridges and routing</title>
+        <para>Some messaging systems allow isolated clusters or single nodes to be bridged together,
+            typically over unreliable connections like a Wide Area Network (WAN).</para>
+        <para>A bridge normally consumes from a queue on one server and forwards messages to another
+            queue on a different server. Bridges cope with unreliable connections, automatically
+            reconnecting when the connections becomes available again.</para>
+        <para>JBoss Messaging bridges can be configured with filter expressions to only forward
+            certain messages, and transformation can be hooked in.</para>
+        <para>JBoss Messaging also allows routing between queues to be configured in server side
+            configuration. This allows complex routing networks to be set up forwarding or copying
+            messages from one destination to another, forming a global network of interconnected
+            brokers.</para>
+    </section>
+    <section>
+        <title>Other messaging system functionality</title>
+        <para>Here's a quick run through of other features and terms you might hear in the context
+            of messaging systems:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Message expiry</para>
+                <para>You can set a Time to Live (TTL) on a message. If you do this then if the
+                    messaging system has not delivered the message by the time TTL comes then the
+                    message will be discarded or possibly sent to a configurable other
+                    destination.</para>
+            </listitem>
+            <listitem><para>Message redelivery</para></listitem>
+            <listitem><para>Blah blah</para></listitem>
+        </itemizedlist>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/paging.xml (from rev 6908, trunk/docs/user-manual/en/modules/paging.xml)
===================================================================
--- trunk/docs/user-manual/en/paging.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/paging.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="paging">
+    <title>Paging</title>
+    <para>JBoss Messaging pages messages on disk, avoiding this way running out of Memory.</para>
+    <para>Messages are regularly routed to their queues, persisted on disk for eventual recovery in
+        case of server failure, sent to consumers or kept in memory if the consumers are not ready
+        to read the messages.</para>
+    <para>We compute the size of every message routed and stored in memory. When the total reaches a
+        max configured size JBoss Messaging starts storing messages on disk. As messages are
+        acknowledged and release the memory, we read the page and route messages to the destinations
+        on memory.</para>
+    <para>There are two page modes supported by JBoss Messaging. <link linkend="paging.global.mode"
+            >Global Paging Mode </link> and <link linkend="paging.address.mode">Address Paging Mode
+        </link></para>
+    <section>
+        <title>Page Files</title>
+        <para>Messages are stored per address on the file system. Each address has an individual
+            folder where messages are stored in multiple files (page files). Each file will contain
+            messages up to a max configured size. (<literal>page-size-bytes</literal>). When reading
+            page-files all messages on the page-file are read, routed and the file is deleted as
+            soon as the messages are recovered.</para>
+    </section>
+    <section id="paging.global.mode">
+        <title>Global Paging Mode</title>
+        <para>JBoss Messaging enters into Global Paging Model when the total memory used by queues
+            reaches a configured maximum value, determined by <literal><link
+                    linkend="paging.main.config">paging-max-global-size-bytes</link></literal>. </para>
+        <para>When the total memory is greater than <literal>paging-max-global-size-bytes</literal>,
+            JBoss Messaging starts to page messages. When there is space in memory to fit a page
+            file (<literal>global-page-size</literal>) messages are read and routed of the paging
+            file.</para>
+        <section id="paging.main.config">
+            <title>Configuration</title>
+            <para>Global paging parameters are specified on the main configuration file.</para>
+            <programlisting>&lt;configuration xmlns="urn:jboss:messaging"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
+
+...
+
+&lt;paging-max-global-size-bytes>20485760&lt;/paging-max-global-size-bytes>
+&lt;paging-global-watermark-size>1048576&lt;/paging-global-watermark-size>
+
+...        </programlisting>
+            <para>
+                <table frame="topbot">
+                    <title/>
+                    <tgroup cols="3">
+                        <colspec colname="c1" colnum="1"/>
+                        <colspec colname="c2" colnum="2"/>
+                        <colspec colname="c3" colnum="3"/>
+                        <thead>
+                            <row>
+                                <entry>Property Name</entry>
+                                <entry>Description</entry>
+                                <entry>Default</entry>
+                            </row>
+                        </thead>
+                        <tbody>
+                            <row>
+                                <entry><literal>paging-directory</literal></entry>
+                                <entry>Where page files are stored. JBoss Messaging will create one
+                                    folder for each address being paged under this configured
+                                    location.</entry>
+                                <entry>data/paging</entry>
+                            </row>
+                            <row>
+                                <entry><literal>paging-max-global-size-bytes</literal></entry>
+                                <entry>JBoss Messaging enters into global page mode as soon as the
+                                    total memory consumed by messages hits this value.</entry>
+                                <entry>-1 (disabled)</entry>
+                            </row>
+                            <row>
+                                <entry><literal>global-page-size</literal></entry>
+                                <entry>The standard size of a page-file. JBoss Messaging will only
+                                    read messages when there is enough space to read at least one
+                                    page file, determined by this value.</entry>
+                                <entry>10MiB (10 * 1024 * 1024 bytes)</entry>
+                            </row>
+                        </tbody>
+                    </tgroup>
+                </table>
+            </para>
+        </section>
+    </section>
+    <section id="paging.address.mode">
+        <title>Address Paging Mode</title>
+        <para>It is possible to configured what's the maximum size individually at the address
+            level. As soon as the address is consuming more memory than the maximum configured, that
+            address alone goes into page mode.</para>
+        <section>
+            <title>Configuration</title>
+            <para>Address level config is done at the address settings.</para>
+            <programlisting>  &lt;address-settings>
+      &lt;address-setting match="jms.someaddress">
+         &lt;max-size-bytes>-1&lt;/max-size-bytes>
+         &lt;page-size-bytes>10485760&lt;/page-size-bytes>
+         &lt;drop-messages-when-full>10485760&lt;/drop-messages-when-full>
+      &lt;/address-setting>
+   &lt;/address-settings>
+        </programlisting>
+            <para>This is the list of available parameters on the address settings.</para>
+            <para>
+                <table frame="topbot">
+                    <title/>
+                    <tgroup cols="3">
+                        <colspec colname="c1" colnum="1"/>
+                        <colspec colname="c2" colnum="2"/>
+                        <colspec colname="c3" colnum="3"/>
+                        <thead>
+                            <row>
+                                <entry>Property Name</entry>
+                                <entry>Description</entry>
+                                <entry>Default</entry>
+                            </row>
+                        </thead>
+                        <tbody>
+                            <row>
+                                <entry><literal>max-size</literal></entry>
+                                <entry>What's the max memory the address could have before entering
+                                    on page mode.</entry>
+                                <entry>-1 (disabled)</entry>
+                            </row>
+                            <row>
+                                <entry><literal>page-size-bytes</literal></entry>
+                                <entry>The size of each page file used on the paging system</entry>
+                                <entry>10MiB (10 * 1024 * 1024 bytes)</entry>
+                            </row>
+                            <row>
+                                <entry><literal>drop-messages-when-full</literal></entry>
+                                <entry>if true, messages are dropped instead of paged when <literal
+                                        >used-memory</literal> is greater than <literal
+                                        >max-size</literal></entry>
+                                <entry>false</entry>
+                            </row>
+                        </tbody>
+                    </tgroup>
+                </table>
+            </para>
+        </section>
+    </section>
+    <section>
+        <title>Caution with Addresses with Multiple Queues</title>
+        <para>When a message is sent to multiple queues, on JMS Topics, or on Addresses with
+            multiple queues, the same message is shared as a reference between multiple queues. The
+            message only leaves the memory when it is consumed in all the queues.</para>
+        <para>For example:</para>
+        <itemizedlist>
+            <listitem>
+                <para>An Address has 10 queues </para>
+            </listitem>
+            <listitem>
+                <para>It only has 9 consumers. One of the Queues is leaving messages on the
+                    memory.</para>
+            </listitem>
+            <listitem>
+                <para> Messages are continuously being produced</para>
+            </listitem>
+        </itemizedlist>
+        <para>This will make memory to build on the server, and start paging mode eventually. Once
+            the Address enters in page mode, messages will be stored on disk and not routed to
+            queues until messages are consumed on that queue.</para>
+    </section>
+    <section>
+        <title>Paging Example</title>
+        <para>The <ulink url="../../../../examples/jms/paging/readme.html"><literal>Paging</literal>
+                Example</ulink> shows how to JBoss Messaging avoids running out of memory.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/perf-tuning.xml (from rev 6908, trunk/docs/user-manual/en/modules/perf-tuning.xml)
===================================================================
--- trunk/docs/user-manual/en/perf-tuning.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/perf-tuning.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="perf-tuning">
+    <title>Performance Tuning</title>
+    <para>In this chapter we'll discuss how to tune JBoss Messaging for optimum performance.</para>
+    <section>
+        <title>Tuning the journal</title>
+        <para></para>
+    </section>
+    <section>
+        <title>Tuning JMS</title>
+        <para></para>
+    </section>
+    <section>
+        <title>Tuning the VM</title>
+        <para></para>
+    </section>
+    
+    
+   
+</chapter>

Copied: trunk/docs/user-manual/en/persistence.xml (from rev 6908, trunk/docs/user-manual/en/modules/persistence.xml)
===================================================================
--- trunk/docs/user-manual/en/persistence.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/persistence.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,212 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="persistence">
+    <title>Persistence</title>
+    <para>In this chapter we will describe how persistence works with JBoss Messaging, and you will
+        discover how to configure it.</para>
+    <para>JBoss Messaging includes a high performance journal to provide excellent persistent
+        message performance. By managing its own persistence JBoss Messaging does not require a
+        relational or other database to perform that function. This means that JBoss Messaging can
+        provide much higher persistent rates than are available using a database for persistence
+        since the journal is optimised for its goal, whereas a database is for general purpose data
+        persistence.</para>
+    <para>A JBoss Messaging journal is an <emphasis>append only</emphasis> journal. It consists of a
+        set of files on disk. Each file is of a fixed size and is initially filled with padding. As
+        operations are performed on the server, e.g. add message, update message, delete message, a
+        record is appended to the journal for each operation.</para>
+    <para>Operation records are only added to the end of the journal. By only adding records to the
+        end of the journal, we minimise disk head movement since we're not doing random access
+        operations.</para>
+    <para>When one journal file is full we move to the next one. We typically choose each journal
+        file to be about the right size to fit on a disk cylinder. Modern disk topologies are
+        complex and we are not in control over which cylinder(s) the file is mapped onto so this is
+        not an exact science. By minimising the number of disk cylinders the file is using, we can
+        minimise the amount of disk head movement, since an entire disk cylinder is accessible
+        simply by the disk rotating - the head does not have to move.</para>
+    <para>As delete records are added to the journal, JBoss Messaging has a sophisticated file
+        garbage collection algorithm which can determine if a particular journal file is needed any
+        more - i.e. has all it's data been deleted in the same or other files. If so, the file can
+        be reclaimed and re-used. </para>
+    <para>JBoss Messaging also has a compaction algorithm which removes dead space from the journal
+        and compresses up the data so it takes up less files on disk.</para>
+    <para>The journal is also fully local and XA transaction capable.</para>
+    <para>The majority of the journal is written as common code in Java, and we abstract out the
+        interaction with the actual file system in a thin abstraction layer. We ship JBoss Messaging
+        with two implementations of that abstraction layer:</para>
+    <itemizedlist>
+        <listitem>
+            <para>Java NIO.</para>
+            <para>The first implementation uses standard Java NIO to interface with the file system.
+                This provides very good performance and runs on any platform for which there is a
+                JDK 5+ JVM.</para>
+        </listitem>
+        <listitem>
+            <para>Linux Asynchronous IO (AIO).</para>
+            <para>The second implementation uses a thin JNI wrapper to talk to the Linux
+                asynchronous IO library from Java. In a highly concurrent environment, AIO can
+                provide better overall persistent throughput than is available with Java NIO since
+                it does not require each individual transaction boundary to be synced to disk. Most
+                disks can only support a limited number of syncs per second, so a syncing approach
+                does not scale well with the number of concurrent transactions that need to commit.
+                With AIO, JBoss Messaging will be called back when the data has made it to disk,
+                allowing us to avoid explicit syncs altogether and simply send back confirmation of
+                completion when AIO informs us that the data has been persisted.</para>
+            <para>The AIO journal is only available when running Linux kernel 2.6 or later and after
+                having installed libaio (if it's not already installed). For instructions on how to
+                install libaio please see [LINK]</para>
+        </listitem>
+    </itemizedlist>
+    <para>The standard JBoss Messaging core server uses two instances of the journal:</para>
+    <itemizedlist>
+        <listitem>
+            <para>Bindings journal.</para>
+            <para>This journal is used to store bindings related data. That includes the set of
+                queues that are deployed on the server and their attributes. It also stores data
+                such as id sequence counters. </para>
+            <para>The bindings journal is always a NIO journal as it is typically low throughput
+                compared to the message journal.</para>
+        </listitem>
+        <listitem>
+            <para>Message journal.</para>
+            <para>This journal instance stores all message related data, including the message
+                themselves and also duplicate id caches.</para>
+            <para>By default JBoss Messaging will try and use an AIO journal. If AIO is not
+                available, e.g. the platform is not Linux with the correct kernel version or AIO has
+                not been installed then it will automatically fall back to using Java NIO which is
+                available on any Java platform.</para>
+        </listitem>
+    </itemizedlist>
+    <para>For large messages, JBoss Messaging persists them outside the message journal. This is
+        discussed in the chapter on large messages [LINK]</para>
+    <para>JBoss Messaging also pages messages to disk in low memory situations. This is discussed in
+        the chapter on paging [LINK]</para>
+    <para>If no persistence is required at all, JBoss Messaging can also be configured not to
+        persist any data at all to storage.</para>
+    <section id="configuring.bindings.journal">
+        <title>Configuring the bindings journal</title>
+        <para>The bindings journal is configured using the following attributes in <literal
+                >jbm-configuration.xml</literal></para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>bindings-directory</literal></para>
+                <para>This is the directory in which the bindings journal lives. The default value
+                    is <literal>data/bindings</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>create-bindings-dir</literal></para>
+                <para>If this is set to <literal>true</literal> then the bindings directory will be
+                    automatically created at the location specified in <literal
+                        >bindings-directory</literal> if it does not already exist. The default
+                    value is <literal>true</literal></para>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section id="configuring.message.journal">
+        <title>Configuring the message journal</title>
+        <para>The message journal is configured using the following attributes in <literal
+                >jbm-configuration.xml</literal></para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>journal-directory</literal></para>
+                <para>This is the directory in which the message journal lives. The default value is
+                        <literal>data/journal</literal>.</para>
+                <para>For the best performance, we recommend the journal is located on its own
+                    volume in order to minimise disk head movement. If the journal is on a volume
+                    which is shared with other processes which might be writing other files (e.g.
+                    bindings journal, database, or transaction coordinator) then the disk head may
+                    well be moving rapidly between these files as it writes them, thus reducing
+                    performance.</para>
+                <para>When the message journal is stored on a SAN we recommend each journal instance
+                    that is stored on the SAN is given its own LUN (logical unit).</para>
+            </listitem>
+            <listitem>
+                <para><literal>create-journal-dir</literal></para>
+                <para>If this is set to <literal>true</literal> then the journal directory will be
+                    automatically created at the location specified in <literal
+                        >journal-directory</literal> if it does not already exist. The default value
+                    is <literal>true</literal></para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-type</literal></para>
+                <para>Valid values are <literal>NIO</literal> or <literal>AIO</literal>.</para>
+                <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
+                        <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
+                    choose <literal>AIO</literal> but are not running Linux or you do not have
+                    libaio installed then JBoss Messaging will detect this and automatically fall
+                    back to using <literal>NIO</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-sync-transactional</literal></para>
+                <para>If this is set to true then JBoss Messaging will wait for all transaction data
+                    to be persisted to disk on a commit before sending a commit response OK back to
+                    the client. The default value is <literal>true</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-sync-non-transactional</literal></para>
+                <para>If this is set to true then JBoss Messaging will wait for any non
+                    transactional data to be persisted to disk on a send before sending the response
+                    back to the client. The default value for this is <literal
+                    >false</literal>.</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-file-size</literal></para>
+                <para>The size of each journal file in bytes. The default value for this is 10485760
+                    bytes (10MiB).</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-min-files</literal></para>
+                <para>The minimum number of files the journal will maintain. When JBoss Messaging
+                    starts and there is no initial message data, JBoss Messaging will pre-create
+                        <literal>journal-min-files</literal> number of files.</para>
+                <para>Creating journal files and filling them with padding is a fairly expensive
+                    operation and we want to minimise doing this at run-time as files get filled. By
+                    precreating files, as one is filled the journal can immediately resume with the
+                    next one without pausing to create it.</para>
+                <para>Depending on how much data you expect your queues to contain at steady state
+                    you should tune this number of files to match that total amount of data.</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-max-aio</literal></para>
+                <para>When using an AIO journal, write requests are queued up before being submitted
+                    to AIO for execution. Then when AIO has completed them it calls JBoss Messaging
+                    back. This parameter controls the maximum number of write requests that can be
+                    in the AIO queue at any one time. If the queue becomes full then writes will
+                    block until space is freed up. This parameter has no meaning when using the NIO
+                    journal.</para>
+            </listitem>
+            <listitem>
+                <para><literal>journal-buffer-reuse-size</literal></para>
+                <para>Creaking direct byte buffers is an expensive operation, so the journal will
+                    attempt to re-use any buffers with a size less than this setting, in bytes. If
+                    this value is set to <literal>-1</literal> then the journal will not attempt to
+                    re-use any buffers. This setting only takes effect if the journal is <literal
+                        >AIO</literal>. The default value for this setting is <literal
+                        >1024</literal> bytes.</para>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section>
+        <title>Installing AIO</title>
+        <para>If you are running JBoss Messaging using Linux Kernel 2.6 or later, we highly
+            recommend you use the <literal>AIO</literal> journal for the best persistence
+            performance especially under high concurrency.</para>
+        <para>It's not possible to use the AIO journal under other operating systems or earlier
+            versions of the Linux kernel.</para>
+        <para>If you are running Linux kernel 2.6 or later and don't already have <literal
+                >libaio</literal> installed, you can easily install it using the following
+            steps:</para>
+        <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+            <programlisting>sudo yum install libaio1</programlisting></para>
+        <para>Using aptitude, (e.g. on Ubuntu or Debian system):
+            <programlisting>sudo apt-get install libaio1</programlisting></para>
+    </section>
+    <section id="persistence.enabled">
+        <title>Configuring JBoss Messaging for zero persistence</title>
+        <para> In some situations, zero persistence is sometimes required for a messaging system.
+            Configuring JBoss Messaging to perform zero persistence is straightforward. Simply set
+            the parameter <literal>persistence-enabled</literal> in <literal
+                >jbm-configuration.xml</literal> to <literal>false</literal>. </para>
+        <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
+            persistence will occur. That means no bindings data, message data, large message data,
+            duplicate id caches or paging data will be persisted.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/pre-acknowledge.xml (from rev 6908, trunk/docs/user-manual/en/modules/pre-acknowledge.xml)
===================================================================
--- trunk/docs/user-manual/en/pre-acknowledge.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/pre-acknowledge.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="pre-acknowledge">
+    <title>Pre-Acknowledge Mode</title>
+    <para>JMS specifies 3 acknowledgement modes:</para>
+    <itemizedlist>
+      <listitem><para><literal>AUTO_ACKNOWLEDGE</literal></para></listitem>
+      <listitem><para><literal>CLIENT_ACKNOWLEDGE</literal></para></listitem>
+      <listitem><para><literal>DUPS_OK_ACKNOWLEDGE</literal></para></listitem>
+    </itemizedlist>
+    
+    <para>The acknowledgement modes all involves sending acknowledgement from the client to the server.
+       However, in the case you can afford to lose messages in event of failure, it would make sense to
+       acknowledge the message on the server <emphasis>before</emphasis> delivering it to the client.</para>
+    <para>The disadvantage of acknowledging on the server before delivery is that the message will be lost
+       if the system crashes <emphasis>after</emphasis> acknowledging the message on the server but
+       <emphasis>before</emphasis> it is delivered to the client. In that case, the message is lost and will
+       not be recovered when the system restart.</para>
+   <para>Depending on your messaging case, <literal>pre-acknowledgement</literal> mode can avoid extra
+      network traffic and CPU at the cost of coping with message loss.</para>
+   <para>An example of a use case for pre-acknowledgement is for stock price update messages.
+       With these messages it might be reasonable to lose a message in event of crash, since the next
+        price update message will arrive soon, overriding the previous price.
+    </para>
+
+    <section>
+       <title>Using PRE_ACKNOWLEDGE</title>
+       <para>To use pre-acknowledgement mode, create a JMS Session with the
+          <literal>JBossSession.PRE_ACKNOWLEDGE</literal> constant.</para>
+       <programlisting>
+// messages will be acknowledge on the server *before* being delivered to the client
+Session session = connection.createSession(false, JBossSession.PRE_ACKNOWLEDGE);
+       </programlisting>
+    </section>
+       
+    <section>
+       <title>Example</title>
+       <para>The <ulink url="../../../../examples/jms/pre-acknowledge/readme.html"><literal>pre-acknowledge</literal> example</ulink> shows
+          how to use pre-acknowledgement mode with with JMS.</para>
+    </section>
+   
+</chapter>

Copied: trunk/docs/user-manual/en/preface.xml (from rev 6908, trunk/docs/user-manual/en/modules/preface.xml)
===================================================================
--- trunk/docs/user-manual/en/preface.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/preface.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="preface">
+    <title>Preface</title>
+    <para>The goal of JBoss Messaging is simple and uncompromising; to bring unrivalled levels of
+        performance and reliability to messaging, and to be the fastest, best featured and most
+        scalable multi-protocol messaging system.</para>
+    <para>Why use JBoss Messaging? Here are a few of the reasons:</para>
+    <itemizedlist>
+        <listitem>
+            <para>100% open source software. We use the Apache Software License version 2.0 to limit
+                restrictions on use.</para>
+        </listitem>
+        <listitem>
+            <para>Written in Java. Runs on any platform with a J2SE 5.0 JDK, that's everything from
+                Windows desktops to IBM mainframes.</para>
+        </listitem>
+        <listitem>
+            <para>Superb performance. Our class beating high performance journal provides persistent
+                messaging performance at rates normally seen for non persistent messaging.</para>
+        </listitem>
+        <listitem>
+            <para>Full feature set. All the features you'd expect in any serious messaging system,
+                and others you won't find anywhere else.</para>
+        </listitem>
+        <listitem>
+            <para>Elegant POJO based design with minimal third party dependencies. Run JBoss
+                Messaging stand-alone, run it in integrated in your favourite JEE application
+                server, or run it embedded inside your own product.</para>
+        </listitem>
+        <listitem>
+            <para>Seamless high availabilty. We provide server replication and completely
+                transparent client failover so you don't have to worry about coding your client
+                specially for an HA environment.</para>
+        </listitem>
+        <listitem>
+            <para>Hugely flexible clustering. Create clusters of servers that know how to load
+                balance messages. Link geographically distributed clusters over unreliable
+                connections to form a global network. Configure routing of messages in a highly
+                flexible way.</para>
+        </listitem>
+    </itemizedlist>
+</chapter>

Copied: trunk/docs/user-manual/en/project-info.xml (from rev 6908, trunk/docs/user-manual/en/modules/project-info.xml)
===================================================================
--- trunk/docs/user-manual/en/project-info.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/project-info.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="project-info">
+    <title>Project Information</title>
+    <para>The JBoss Messaging project page is <ulink url="http://www.jboss.org/jbossmessaging/"
+            >here</ulink>. You can download any releases from there.</para>
+    <para>If you have any user questions please use our <ulink
+            url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=238">user
+            forum</ulink></para>
+    <para>If you have development related questions, please use our <ulink
+        url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=153">development
+        forum</ulink></para>
+    <para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/jbossmessaging">IRC channel</ulink></para>  
+    <para>JBoss Messaging svn TRUNK is <ulink url="http://anonsvn.jboss.org/repos/messaging/trunk">here</ulink></para>
+    <para>All our release tags are <ulink url="http://anonsvn.jboss.org/repos/messaging/tags">here</ulink></para>
+    <para>The JBoss Messaging permanent dev team is <ulink url="jbossfox.blogspot.com">Tim Fox</ulink>, Howard Gao, Jeff Mesnil, Clebert
+        Suconic, and Andy Taylor</para>
+</chapter>

Copied: trunk/docs/user-manual/en/queue-attributes.xml (from rev 6908, trunk/docs/user-manual/en/modules/queue-attributes.xml)
===================================================================
--- trunk/docs/user-manual/en/queue-attributes.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/queue-attributes.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="queue-attributes">
+    <title>Queue Attributes</title>
+    <para>Queue attributes can be set in one of 2 ways. Either by configuring them via the
+        configuration file or when using the core API. This chapter will explain how to configure
+        each attribute and what effect the attribute has.</para>
+    <section id="predefined.queues">
+        <title>Predefined Queues</title>
+        <para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly
+            lets look at a JMS level.</para>
+        <para>The following shows a queue predefined in the <literal>jbm-jms.xml</literal>
+            configuration file.</para>
+        <programlisting>&lt;queue name="selectorQueue">
+      &lt;entry name="/queue/selectorQueue"/>
+      &lt;filter string="color='red'"/>
+      &lt;durable>true&lt;/durable>
+&lt;/queue></programlisting>
+        <para>This name attribute of queue defines the name of the queue. When we do this at a jms
+            level we follow a naming convention so the actual name of the queue will be <literal
+                >jms.queue.selectorQueue</literal>.</para>
+        <para>The entry element configures the name that will be used to bind the queue to JNDI.
+            This is a mandatory element and the queue can contain multiple of these to bind the same
+            queue to different names.</para>
+        <para>The filter element defines what filter or message selector the predefined queue will
+            have. This is an optional element with a default of null when ommitted.</para>
+        <para>The durable element specifies whether the queue will be persisted. This again is
+            optional and defaults to true if ommited.</para>
+        <para>Secondly a queue can be predefined at a core level in the <literal
+                >jbm-configuration.xml</literal> file. The following is an example.</para>
+        <programlisting>&lt;queues>     
+   	&lt;queue name="jms.queue.selectorQueue">
+   	    &lt;address>jms.queue.selectorQueue&lt;/address>
+   	    &lt;filter string="color='red'"/>
+       &lt;durable>true&lt;/durable>
+   	&lt;/queue>
+&lt;/queues></programlisting>
+        <para>This is very similar to the jms configuration, with 3 real differences which
+            are.</para>
+        <orderedlist>
+            <listitem>
+                <para>The name attribute of queue is the actual name used for the queue with no
+                    naming convention as in JMS.</para>
+            </listitem>
+            <listitem>
+                <para>The address element defines what address is used for routing messages.</para>
+            </listitem>
+            <listitem>
+                <para>There is no entry element.</para>
+            </listitem>
+        </orderedlist>
+    </section>
+    <section>
+        <title>Using the API</title>
+        <para>Queues can also be created using the core API or the JMS management API.</para>
+        <para>For the core API queues can be created via the <literal
+                >org.jboss.messaging.core.client.ClientSession</literal> interface. There are
+            multiple <literal>createQueue</literal> methods that support setting all of the afore
+            mentioned attributes. There is one extra atrribute that can be set via this API which is
+                <literal>temporary</literal>. setting this to true means that the queue will be
+            deleted once the session is disconnected.</para>
+        <para>Take a look at the <xref linkend="management">management section</xref> for the API
+            for creating queues.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/scheduled-messages.xml (from rev 6908, trunk/docs/user-manual/en/modules/scheduled-messages.xml)
===================================================================
--- trunk/docs/user-manual/en/scheduled-messages.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/scheduled-messages.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="scheduled-messages">
+   <title>Scheduled Messages</title>
+   <para>Scheduled messages are delivered at a time specified by the sender rather than when request by the receiver.</para>
+   <para>Messages are scheduled for later delivery if they have a well-known scheduled delivery property set.</para>
+   
+   <section>
+      <title>Scheduled Delivery Property</title>
+      <para>The property name used to identify a scheduled message is <literal>"_JBM_SCHED_DELIVERY"</literal> (or
+      the constant <literal>MessageImpl.HDR_SCHEDULED_DELIVERY_TIME</literal>).</para>
+      <para>The specified value must be a <literal>long</literal> corresponding to the time the message
+      must be delivered (in milliseconds).</para>
+      <programlisting>
+         TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
+         message.setLongProperty("_JBM_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
+         producer.send(message);
+
+         ...
+         
+         // message will not be received immediately but 5 seconds later
+         TextMessage messageReceived = (TextMessage) consumer.receive();
+        </programlisting>
+   </section>
+         
+   <section>
+      <title>Example</title>
+      <para>The <ulink url="../../../../examples/jms/scheduled-message/readme.html"><literal>scheduled-message</literal> example</ulink> shows
+      how scheduled messages can be used with JMS.</para>
+   </section>
+   
+</chapter>

Copied: trunk/docs/user-manual/en/security.xml (from rev 6908, trunk/docs/user-manual/en/modules/security.xml)
===================================================================
--- trunk/docs/user-manual/en/security.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/security.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="security">
+    <title>Security</title>
+    <para>This chapter describes how security works with JBoss Messaging and how you can configure
+        it.</para>
+    <section id="security.settings.roles">
+        <title>Role based security for addresses</title>
+        <para>JBoss Messaging contains a flexible role-based security model for applying security to
+            queues, based on their addresses.</para>
+        <para>As explained in section [LINK] JBoss Messaging core consists mainly of sets of queues
+            bound to addresses. A message is sent to an address and the server looks up the set of
+            queues that are bound to that address, the server then routes the message to those set
+            of queues.</para>
+        <para>JBoss Messaging allows sets of permissions to be defined against the queues based on
+            their address. An exact match on the address can be used or a wildcard match can be used
+            using the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
+        <para>Seven different permissions can be given to the set of queues which match the address.
+            Those permissions are:</para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>createDurableQueue</literal>. This permission allows the user to
+                    create a durable queue under matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>deleteDurableQueue</literal>. This permission allows the user to
+                    delete a durable queue under matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>createTempQueue</literal>. This permission allows the user to create
+                    a temporary queue under matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>deleteTempQueue</literal>. This permission allows the user to delete
+                    a temporarry queue under matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>send</literal>. This permission allows the user to send a message to
+                    matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>consume</literal>. This permission allows the user to consume a
+                    message from a queue bound to matching addresses.</para>
+            </listitem>
+            <listitem>
+                <para><literal>manage</literal>. This permission allows the user to invoke
+                    management operations by sending management messages to the management
+                    address.</para>
+            </listitem>
+        </itemizedlist>
+        <para>For each permission, a list of roles who are granted that permission is specified. If
+            the user has any of those roles, he/she will be granted that permission for that set of
+            addresses.</para>
+        <para>Let's take a simple example, here's a security block from <literal
+                >jbm-configuration.xml</literal> or <literal>jbm-queues.xml</literal> file:</para>
+        <programlisting>
+&lt;security-setting match="globalqueues.europe.#"&gt;
+    &lt;permission type="createDurableQueue" roles="admin"/&gt;
+    &lt;permission type="deleteDurableQueue" roles="admin"/&gt;
+    &lt;permission type="createTempQueue" roles="admin, guest, europe-users"/&gt;
+    &lt;permission type="deleteTempQueue" roles="admin, guest, europe-users"/&gt;
+    &lt;permission type="send" roles="admin, europe-users"/&gt;
+    &lt;permission type="consume" roles="admin, europe-users"/&gt;
+&lt;/security-setting&gt;            
+        </programlisting>
+        <para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
+            delimited by the '<literal>.</literal>' character. For a full description of the
+            wildcard syntax please see the chapter [LINK]. The above security block applies to any
+            address that starts with the string "globalqueues.europe.":</para>
+        <para>Only users who have the <literal>admin</literal> role can create or delete durable
+            queues bound to an address that starts with the string "globalqueues.europe."</para>
+        <para>Only users who have the <literal>admin</literal> role can create or delete durable
+            queues bound to an address that starts with the string "globalqueues.europe."</para>
+        <para>Any users with the roles <literal>admin</literal>, <literal>guest</literal>, or
+                <literal>europe-users</literal> can create or delete temporary queues bound to an
+            address that starts with the string "globalqueues.europe."</para>
+        <para>Any users with the roles <literal>admin</literal> or <literal>europe-users</literal>
+            can send messages to these addresses or consume messages from queues bound to an address
+            that starts with the string "globalqueues.europe."</para>
+        <para>The mapping between a user and what roles they have is handled by the security
+            manager. JBoss Messaging ships with a user manager that reads user credentials from a
+            file on disk, and can also plug into JAAS or JBoss Application Server security.</para>
+        <para>For more information on configuring the security manager please see section
+            [LINK]</para>
+        <para>There can be zero or more <literal>security-setting</literal> elements in each xml
+            file. Where more than one match applies to a set of addresses the <emphasis>more
+                specific</emphasis> match takes precedence.</para>
+        <para>Let's look at an example of that, here's another <literal>security-setting</literal>
+            block:</para>
+        <programlisting>
+&lt;security-setting match="globalqueues.europe.orders.#"&gt;
+    &lt;permission type="send" roles="europe-users"/&gt;
+    &lt;permission type="consume" roles="europe-users"/&gt;
+&lt;/security-setting&gt;            
+        </programlisting>
+        <para>In this <literal>security-setting</literal> block the match
+            'globalqueues.europe.orders.#' is more specific than the previous match
+            'globalqueues.europe.#'. So any addresses which match 'globalqueues.europe.orders.#'
+            will take their security settings <emphasis>only</emphasis> from the latter
+            security-setting block.</para>
+        <para>Note that settings are not inherited from the former block. All the settings will be
+            taken from the more specific matching block, so for the address
+            'globalqueues.europe.orders.plastics' the only permissions that exist are send and
+            consume for the role europe-users. The permissions createDurableQueue,
+            deleteDurableQueue, createTempQueue, deleteTempQueue are not inherited from the other
+            security-setting block.</para>
+        <para>By not inheriting permissions, it allows you to effectively deny permissions in more
+            specific security-setting blocks by simply not specifying them. Otherwise it would not
+            be possible to deny permissions in sub-groups of addresses.</para>
+    </section>
+    <section>
+        <title>Secure Sockets Layer (SSL) Transport</title>
+        <para>When messaging clients are connected to servers, or servers are connected to other
+            servers (e.g. via bridges) over an untrusted network then JBoss Messaging allows that
+            traffic to be encrypted using the Secure Sockets Layer (SSL) transport.</para>
+        <para>For more information on configuring the SSL transport please see the section
+            [LINK]</para>
+    </section>
+    <section>
+        <title>Basic user credentials</title>
+        <para> JBoss Messaging ships with a security manager implementation that reads user
+            credentials, i.e. usernames, passwords and role information from an xml file on the
+            classpath <literal>jbm-users.xml</literal>. This is the default security manager.</para>
+        <para>If you wish to use this security manager, then users, passwords and roles can easily
+            be added into this file.</para>
+        <para>Let's take a look at an example file:</para>
+        <programlisting>
+&lt;configuration xmlns="urn:jboss:messaging" 
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-users.xsd "&gt;
+    
+    &lt;defaultuser name="guest" password="guest"&gt;
+        &lt;role name="guest"/&gt;
+    &lt;/defaultuser&gt;
+    
+    &lt;user name="tim" password="marmite"&gt;
+        &lt;role name="admin"/&gt;      
+    &lt;/user&gt;
+    
+    &lt;user name="andy" password="doner_kebab"&gt;
+        &lt;role name="admin"/&gt;
+        &lt;role name="guest"/&gt;
+    &lt;/user&gt;
+    
+    &lt;user name="jeff" password="camembert"&gt;
+        &lt;role name="europe-users"/&gt;
+        &lt;role name="guest"/&gt;
+    &lt;/user&gt;
+    
+&lt;/configuration&gt;
+        </programlisting>
+        <para>The first thing to note is the element <literal>default-user</literal>. This defines
+            what user will be assumed when the client does not specify a username/password when
+            creating a session. In this case they be the user <literal>guest</literal> and have the
+            role also called <literal>guest</literal>. Multiple roles can be specified for a default
+            user.</para>
+        <para>Then we have three more users, the user <literal>tim</literal> has the role <literal
+                >admin</literal>. The user <literal>andy</literal> has the roles <literal
+                >admin</literal> and <literal>guest</literal>, and the user <literal>jeff</literal>
+            has the roles <literal>europe-users</literal> and <literal>guest</literal>.</para>
+    </section>
+    <section>
+        <title>Changing the security manager</title>
+        <para>If you do not want to use the default security manager which reads user credentials
+            from the <literal>jbm-users.xml</literal> file, then you can specify the security
+            manager that JBoss Messaging uses by editing the <literal>jbm-jboss-beans.xml</literal>
+            file and changing the class of the security manager that gets injected into the JBoss
+            Messaging server when the JBoss Microcontainer starts up the beans.</para>
+        <para>Let's take a look at a snippet from the default beans file:</para>
+        <programlisting>           
+&lt;bean name="JBMSecurityManager" 
+      class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl"&gt;
+    &lt;start ignored="true"/&gt;
+    &lt;stop ignored="true"/&gt;
+&lt;/bean&gt;            
+        </programlisting>
+        <para>The class <literal
+                >org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl</literal> is the
+            security manager that reads user credentials from the <literal>jbm-users.xml</literal>
+            file. So if you don't want to use that you can replace this with the class name of the
+            security manager of your choice.</para>
+        <para>JBoss Messaging ships with two other security manager implementations you can use off
+            the shelf - one a JAAS security manager and another for integrating with JBoss
+            Application Sever security, alternatively you could write your own implementation by
+            implementing the <literal>org.jboss.messaging.core.security.SecurityManager</literal>
+            interface, and specifying the classname of your implementation in the <literal
+                >jbm-jboss-beans.xml</literal> file.</para>
+        <para>These two implementations are discussed in the next two sections.</para>
+    </section>
+    <section>
+        <title>JAAS Security Manager</title>
+        <para>JAAS stands for 'Java Authentication and Authorization Service' and is a standard part
+            of the Java platform. It provides a common API for security authentication and
+            authorization, allowing you to plugin your pre-built implementations.</para>
+        <para>To configure the JAAS security manager to work with your pre-built JAAS infrastructure
+            you need to specify the security manager as a JAASSecurityManager in the beans file.
+            Here's an example:</para>
+        <programlisting>
+&lt;bean name="JBMSecurityManager" 
+      class="org.jboss.messaging.integration.security.JAASSecurityManager"&gt;      
+    &lt;start ignored="true"/&gt;
+    &lt;stop ignored="true"/&gt;
+    
+    &lt;property name="ConfigurationName"&gt;org.jboss.jms.example.ExampleLoginModule&lt;/property&gt;
+    &lt;property name="Configuration"&gt;
+       &lt;inject bean="ExampleConfiguration"/&gt;
+    &lt;/property&gt;
+    &lt;property name="CallbackHandler"&gt;
+       &lt;inject bean="ExampleCallbackHandler"/&gt;
+    &lt;/property&gt;
+&lt;/bean&gt;            
+        </programlisting>
+        <para>Note that you need to feed the JAAS security manager with three properties:</para>
+        <itemizedlist>
+            <listitem>
+                <para>ConfigurationName: the name of the <literal>LoginModule</literal>
+                    implementation that JAAS must use</para>
+            </listitem>
+            <listitem>
+                <para>Configuration: the <literal>Configuration</literal> implementation used by
+                    JAAS</para>
+            </listitem>
+            <listitem>
+                <para>CallbackHandler: the <literal>CallbackHandler</literal> implementation to use
+                    if user interaction are required</para>
+            </listitem>
+        </itemizedlist>
+        <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/jaas/readme.html"><literal>jaas</literal>
+                    example</ulink> shows how JBoss Messaging can be configured to use JAAS.</para>
+        </section>
+    </section>
+    <section>
+        <title>JBoss AS Security Manager</title>
+        <para> The JBoss AS security manager is used when running JBoss Messaging inside JBoss
+            Application server and when you want tight integration with JBoss Application Server's
+            security model.</para>
+        <para>When running inside JBoss Application Server you will, by default, be using this
+            security manager. The class name of this security manager is <literal
+                >org.jboss.messaging.integration.security.JBossASSecurityManager</literal></para>
+        <para>Take a look at one of the default <literal>jbm-jboss-beans.xml</literal> files for
+            JBoss Application Server that are bundled in the distribution for an example of how this
+            is configured.</para>
+    </section>
+    <section>
+        <title>Changing the Management password for Clustering</title>
+        <para>In order for cluster connections to work correctly, each node in the cluster must
+            register for management notifications from other nodes. To do this they must perform
+            these actions as a user with a role that has <literal>admin</literal> permissions on the
+            management addresses.</para>
+        <para>This password should always be changed from its default after installation. Please see
+            the management chapter for instructions on how to do this.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/send-guarantees.xml (from rev 6908, trunk/docs/user-manual/en/modules/send-guarantees.xml)
===================================================================
--- trunk/docs/user-manual/en/send-guarantees.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/send-guarantees.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="send-guarantees">
+    <title>Guarantees of Transactional and Non-Transactional Sends and Asynchronous Send
+        Acknowledgements</title>
+    <section>
+        <title>Guarantees of Transaction Completion</title>
+        <para>When committing or rolling back a transaction with JBoss Messaging, the request to
+            commit or rollback is sent to the server, and the call will block on the client side
+            until a response has been received from the server that the commit or rollback was
+            executed.</para>
+        <para>When the commit or rollback is received on the server, it will be committed to the
+            journal, and depending on the value of the parameter <literal
+                >journal-sync-transactional</literal> the server will ensure that the commit or
+            rollback is durably persisted to storage before sending the response back to the client.
+            If this parameter has the value <literal>false</literal> then commit or rollback may not
+            actually get persisted to storage until some time after the response has been sent to
+            the client. In event of server failure this may mean the commit or rollback never gets
+            persisted to storage. The default value of this parameter is <literal>true</literal> so
+            the client can be sure all transaction commits or rollbacks have been persisted to
+            storage by the time the call to commit or rollback returns.</para>
+        <para>Setting this parameter to <literal>false</literal> can improve performance at the
+            expense of some loss of transaction durability.</para>
+        <para>This parameter is set in <literal>jbm-configuration.xml</literal></para>
+    </section>
+    <section id="non-transactional-sends">
+        <title>Guarantees of Non Transactional Message Sends</title>
+        <para>If you are sending messages to a server using a non transacted session, JBoss
+            Messaging can be configured to block the call to send until the message has definitely
+            reached the server, and a response has been sent back to the client. This can be
+            configured individually for persistent and non-persistent messages, and is determined by
+            the following two parameters:</para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>BlockOnPersistentSend</literal>. If this is set to <literal
+                        >true</literal> then all calls to send for persistent messages on non
+                    transacted sessions will block until the message has reached the server, and a
+                    response has been sent back. The default value is <literal>false</literal>.
+                </para>
+            </listitem>
+            <listitem>
+                <para><literal>BlockOnNonPersistentSend</literal>. If this is set to <literal
+                        >true</literal> then all calls to send for non-persistent messages on non
+                    transacted sessions will block until the message has reached the server, and a
+                    response has been sent back. The default value is <literal
+                    >false</literal>.</para>
+            </listitem>
+        </itemizedlist>
+        <para>Setting block on sends to <literal>true</literal> can reduce performance since each
+            send requires a network round trip before the next send can be performed. This means the
+            performance of sending messages will be limited by the network round trip time (RTT) of
+            your network, rather than the bandwidth of your network. For better performance we
+            recommend either batching many messages sends together in a transaction since with a
+            transactional session, only the commit / rollback blocks not every send, or, using JBoss
+            Messaging's advanced <emphasis>asynchronous send acknowledgements</emphasis>
+            feature.</para>
+        <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+            connection factory instances into JNDI then these parameters can be configured in
+                <literal>jbm-jms.xml</literal> using the elements <literal
+                >send-p-messages-synchronously</literal> and <literal
+                >send-np-messages-synchronously</literal>. If you're using JMS but not using JNDI
+            then you can set these values directly on the <literal>JBossConnectionFactory</literal>
+            instance using the appropriate setter methods.</para>
+        <para>If you're using core you can set these values directly on the <literal
+                >ClientSessionFactory</literal> instance using the appropriate setter
+            methods.</para>
+        <para>When the server receives a message sent from a non transactional session, and that
+            message is persistent and the message is routed to at least one durable queue, then the
+            server will persist the message in permanent storage. If the journal parameter <literal
+                >journal-sync-non-transactional</literal> is set to <literal>true</literal> the
+            server will not send a response back to the client until the message has been persisted
+            and the server has a guarantee that the data has been persisted to disk. The default
+            value for this parameter is <literal>false</literal>.</para>
+    </section>
+    <section id="send-guarantees.nontrans.acks">
+        <title>Guarantees of Non Transactional Acknowledgements</title>
+        <para>If you are acknowledging the delivery of a message at the client side using a non
+            transacted session, JBoss Messaging can be configured to block the call to acknowledge
+            until the acknowledge has definitely reached the server, and a response has been sent
+            back to the client. This is configured with the parameter <literal
+                >BlockOnAcknowledge</literal>. If this is set to <literal>true</literal> then all
+            calls to acknowledge on non transacted sessions will block until the acknowledge has
+            reached the server, and a response has been sent back. The default value is <literal
+                >false</literal></para>
+    </section>
+    <section>
+        <title>Asynchronous Send Acknowledgements</title>
+        <para>If you are using a non transacted session but want a guarantee that every message sent
+            to the server has reached it, then, as discussed in section <xref
+                linkend="non-transactional-sends"/>, you can configure JBoss Messaging to block the
+            call to send until the server has received the message, persisted it and sent back a
+            response. This works well but has a severe performance penalty - each call to send needs
+            to block for at least the time of a network round trip (RTT) - the performance of
+            sending is thus limited by the latency of the network, <emphasis>not</emphasis> limited
+            by the network bandwidth.</para>
+        <para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
+            1Gib ethernet with a network round trip between the server and the client of 0.25
+            ms.</para>
+        <para>With a RTT of 0.25 ms, the client can send <emphasis>at most</emphasis> 1000/ 0.25 =
+            4000 messages per second if it blocks on each message send.</para>
+        <para>If each message is &lt; 1500 bytes and a standard 1500 bytes MTU size is used on the
+            network, then a 1GiB network has a <emphasis>theoretical</emphasis> upper limit of (1024
+            * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
+            blocking! These figures aren't an exact science but you can clearly see that being
+            limited by network RTT can have serious effect on performance.</para>
+        <para>To remedy this, JBoss Messaging provides an advanced new feature called
+                <emphasis>asynchronous send acknowledgements</emphasis>. With this feature, JBoss
+            Messaging can be configured to send messages without blocking on one direction and
+            asynchronously getting acknowledgement from the server that the messages were received
+            in a separate stream. By de-coupling the send from the acknowledgement of the send, the
+            system is not limited by the network RTT, but is limited by the network bandwidth.
+            Consequently much throughput can be achieved than is possible using a blocking approach,
+            while at the same time having absolute guarantees that messages have successfully
+            reached the server.</para>
+        <section>
+            <title>Asynchronous Send Acknowledgements</title>
+            <para>To use the feature using the core API, you implement the interface <literal
+                    >org.jboss.messaging.core.client.SendAcknowledgementHandler</literal> and set a
+                handler instance on your <literal>ClientSession</literal>.</para>
+            <para>Then, you just send messages as normal using your <literal
+                >ClientSession</literal>, and as messages reach the server, the server will send
+                back an acknowledgment of the send asynchronously, and some time later you are
+                informed at the client side by JBoss Messaging calling your handler's <literal
+                    >sendAcknowledged(ClientMessage message)</literal> method, passing in a
+                reference to the message that was sent.</para>
+            <para>Please see the send acknowledgements example for a full working example
+                [LINK]</para>
+        </section>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/thread-pooling.xml (from rev 6908, trunk/docs/user-manual/en/modules/thread-pooling.xml)
===================================================================
--- trunk/docs/user-manual/en/thread-pooling.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/thread-pooling.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="thread-pooling">
+    <title>Thread management</title>
+    <para>This chapter describes how JBoss Messaging uses and pools thread and how you can manage
+        that.</para>
+    <para>First we'll discuss how threads are managed and used on the server side, then we'll look
+        at the client side.</para>
+    <section>
+        <title>Server-Side Thread Management</title>
+        <para>Each JBoss Messaging Server maintains a single thread pool for general use, and a
+            scheduled thread pool for scheduled use. A Java scheduled thread pool cannot be
+            configured to use a standard thread pool, otherwise we could use a single thread pool
+            for both scheduled and non scheduled activity.</para>
+        <para>There are also a small number of other places where threads are used directly, we'll
+            discuss each in turn.</para>
+        <section id="server.scheduled.thread.pool">
+            <title>Server Scheduled Thread Pool</title>
+            <para>The server scheduled thread pool is used for most activities on the server side
+                that require running periodically or with delays. It maps internally to a <literal
+                    >java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para>
+            <para>The maximum number of thread used by this pool is configure in <literal
+                    >jbm-configuration.xml</literal> with the <literal
+                    >scheduled-thread-pool-max-size</literal> parameter. The default value is
+                    <literal>5</literal> threads. A small number of threads is usually sufficient
+                for this pool.</para>
+        </section>
+        <section>
+            <title>General Purpose Server Thread Pool</title>
+            <para>This general purpose thread pool is used for most asynchronous actions on the
+                server side. It maps internally to a <literal
+                    >java.util.concurrent.ThreadPoolExecutor</literal> instance.</para>
+            <para>The maximum number of thread used by this pool is configure in <literal
+                    >jbm-configuration.xml</literal> with the <literal
+                    >thread-pool-max-size</literal> parameter.</para>
+            <para>If a value of <literal>-1</literal> is used this signifies that the thread pool
+                has no upper bound and new threads will be created on demand if there are non
+                available in the pool to satisfy a request. If activity later subsides then threads
+                are timed-out and closed.</para>
+            <para>If a value of <literal>n</literal> where <literal>n</literal>is a positive integer
+                greater than zero is used this signifies that the thread pool is bounded. If more
+                requests come in and there are no free threads in the pool and the pool is full then
+                requests will block until a thread becomes available. It is recommended that a
+                bounded thread pool is used with caution since it can lead to dead-lock situations
+                if the upper bound is chosen to be too low.</para>
+            <para>The default value for <literal>thread-pool-max-size</literal> is <literal
+                    >-1</literal>, i.e. the thread pool is unbounded.</para>
+            <para>See the <ulink
+                    url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ThreadPoolExecutor.html"
+                    >J2SE javadoc</ulink> for more information on unbounded (cached), and bounded
+                (fixed) thread pools.</para>
+        </section>
+        <section>
+            <title>Expiry Reaper Thread</title>
+            <para>A single thread is also used on the server side to scan for expired messages in
+                queues. We cannot use either of the thread pools for this since this thread needs to
+                run at its own configurable priority.</para>
+            <para>For more information on configuring the reaper, please see the section on message
+                expiry [LINK].</para>
+        </section>
+        <section>
+            <title>Asychronous IO</title>
+            <para>Two threads are used on Asynchronous IO files. One for polling events, and one for
+                writing data. </para>
+            <para>The thread poller is used by the native layer to receive and dispatch events. You
+                will find it on a thread dump with the prefix JBM-AIO-poller-pool. JBoss Messaging
+                uses one poller per opened file on the journal. (there is usually one) and they are
+                aways distributed thorugh a pool.</para>
+            <para>The writing thread is a single thread used to invoke libaio. We do that to avoid
+                context switching on libaio what would cause performance issues. You will find this
+                thread on a thread dump with the prefix JBM-AIO-writer-pool.</para>
+        </section>
+    </section>
+    <section id="thread-pooling.client.side">
+        <title>Client-Side Thread Management</title>
+        <para>On the client side, JBoss Messaging maintains a single static scheduled thread pool
+            and a single static general thread pool for use by all clients using the same
+            classloader in that JVM instance.</para>
+        <para>The static scheduled thread pool has a maximum size of <literal>2</literal> threads,
+            and the general purpose thread pool has an unbounded maximum size.</para>
+        <para>If required JBoss Messaging can also be configured so that each <literal
+                >ClientSessionFactory</literal> instance does not use these static pools but instead
+            maintains its own scheduled and general purpose pool. Any sessions created from that
+                <literal>ClientSessionFactory</literal> will use those pools instead.</para>
+        <para>To configure a <literal>ClientSessionFactory</literal> instance to use its own pools,
+            simply use the appropriate setter methods immediately after creation, for
+            example:</para>
+        <programlisting>
+ClientSessionFactory myFactory = new ClientSessionFactory(...);
+myFactory.setUseGlobalPools(false);
+myFactory.setScheduledThreadPoolMaxSize(10);
+myFactory.setThreadPoolMaxSize(-1);            
+        </programlisting>
+        <para>If you're using the JMS API, you can set the same parameters directly on the <literal
+                >JBossConnectionFactory</literal> instance, for example:</para>
+        <programlisting>
+JBossConnectionFactory myFactory = new JBossConnectionFactory(...);
+myFactory.setUseGlobalPools(false);
+myFactory.setScheduledThreadPoolMaxSize(10);
+myFactory.setThreadPoolMaxSize(-1);                  
+        </programlisting>
+        <para>If you're using JNDI to instantiate <literal>JBossConnectionFactory</literal>
+            instances, you can also set these parameters in the <literal>jbm-jms.xml</literal> file
+            where you describe your connection factory, for example:</para>
+        <programlisting>
+&lt;connection-factory name="ConnectionFactory"&gt;
+    &lt;connector-ref connector-name="netty"/&gt;
+    &lt;entries&gt;
+        &lt;entry name="ConnectionFactory"/&gt;
+        &lt;entry name="XAConnectionFactory"/&gt;
+    &lt;/entries&gt;
+    &lt;use-global-pools&gt;false&lt;/use-global-pools&gt;
+    &lt;scheduled-thread-pool-max-size&gt;10&lt;/scheduled-thread-pool-max-size&gt;
+    &lt;thread-pool-max-size&gt;-1&lt;/thread-pool-max-size&gt;
+&lt;/connection-factory&gt;            
+        </programlisting>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/undelivered-messages.xml (from rev 6908, trunk/docs/user-manual/en/modules/undelivered-messages.xml)
===================================================================
--- trunk/docs/user-manual/en/undelivered-messages.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/undelivered-messages.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="undelivered-messages">
+    <title>Undelivered Messages</title>
+    <para>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back).
+        Such a message goes back to its queue ready to be redelivered.
+        However, this means it is possible for a message to be delivered 
+        again and again without any success and remain in the queue, clogging the system.</para>
+    <para>There are 2 ways to deal with these undelivered messages:</para>
+    <itemizedlist>
+      <listitem>
+         <para><literal>delayed redelivery</literal></para>
+         <para>It is possible to delay messages redelivery to let the client some time to recover
+            from transient failures and not overload its network or CPU resources</para>
+      </listitem>
+      <listitem>
+         <para><literal>dead letter address</literal></para>
+         <para>It is also possible to configure a dead letter address so that after a specified
+            number of unsuccessful deliveries, messages are removed from the queue and will not
+            be delivered again</para>
+      </listitem>
+    </itemizedlist>
+    <para>Both options can be combined for maximum flexibility.</para>
+
+    <section>
+        <title>Delayed Redelivery</title>
+        <para>Delaying redelivery can often be useful in the case that clients regularly fail or rollback.
+            Without a delayed redelivery, the system can get into a "thrashing" state, with delivery being
+            attempted, the client rolling back, and delivery being re-attempted ad infinitum in quick 
+            succession, consuming valuable CPU and network resources.</para>
+        <section>
+           <title>Configuring Delayed Redelivery</title>
+           <para>Delayed redelivery is defined in the address-setting configuration:</para>
+           <programlisting>
+     &lt;!-- delay redelivery of messages for 5s --&gt;
+     &lt;address-setting match="jms.queue.exampleQueue"&gt;
+        &lt;redelivery-delay&gt;5000&lt;/redelivery-delay&gt;
+     &lt;/address-setting&gt;
+             </programlisting>
+           <para>If a <literal>redelivery-delay</literal> is specified, JBoss Messaging will wait this delay
+           before redelivering the messages</para>
+           <para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set to 0).</para>
+           <para>Address wildcards can be used
+            to configure redelivery delay for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+        </section>
+        <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html"><literal>delayed-redelivery</literal> example</ulink> shows
+            how delayed redelivery is configured and used with JMS.</para>
+        </section>     
+    </section>
+    
+    <section>
+        <title>Dead Letter Addresses</title>
+        <para>To prevent a client to receive infinitely the same undelivered message (regardless of what is causing
+           the unsuccessful deliveries), messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the queue and send instead to a dead letter address.
+           </para>
+        <para>JBoss Messaging's addresses can be assigned a dead letter address. Once the messages have
+           be unsuccessfully delivered for a given number of attempts, they are removed from the queue 
+           and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can later 
+           be consumed for further inspection.</para>
+
+        <section>
+           <title>Configuring Dead Letter Addresses</title>
+           <para>Dead letter address is defined in the address-setting configuration:</para>
+           <programlisting>
+     &lt;!-- undelivered messages in exampleQueue will be sent to the dead letter address deadLetterQueue
+             after 3 unsuccessful delivery attempts
+      --&gt;
+     &lt;address-setting match="jms.queue.exampleQueue"&gt;
+        &lt;dead-letter-address&gt;jms.queue.deadLetterQueue&lt;/dead-letter-address&gt;
+        &lt;max-delivery-attempts&gt;3&lt;/max-delivery-attempts&gt;
+     &lt;/address-setting&gt;
+             </programlisting>
+           <para>If a <literal>dead-letter-address</literal> is not specified, messages will removed after <literal>max-delivery-attempts</literal> unsuccessful attempts.</para>
+           <para>By default, messages are redelivered 10 times at the maximum. Set <literal>max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
+           <para>For example, a dead letter can be set globally for a set of matching addresses and you can set <literal>max-delivery-attempts</literal>
+             to -1 for a specific address setting to allow infinite redeliveries only for this address.</para>
+           <para>Address wildcards can be used
+              to configure dead letter settings for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+        </section>
+        <section>
+           <title>Dead Letter Properties</title>
+           <para>Dead letter messages which are consumed from a dead letter address have the following property:</para>
+           <itemizedlist>
+            <listitem>
+               <para><literal>_JBM_ORIG_DESTINATION</literal></para>
+               <para>a String property containing the <emphasis>original destination</emphasis> of the
+               dead letter message </para>
+            </listitem>
+           </itemizedlist>
+        </section>
+        <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/dead-letter/readme.html"><literal>dead-letter</literal> example</ulink> shows
+            how dead letter is configured and used with JMS.</para>
+        </section>
+    </section>
+    
+    <section id="configuring.delivery.count.persistence">
+      <title>Delivery Count Persistence</title>
+      <para>In normal use, JBoss Messaging does not update delivery count <emphasis>persistently</emphasis>
+         until a message is rolled back (i.e. the delivery count is not updated <emphasis>before</emphasis> the message
+         is delivered to the consumer). In most messaging use cases, the messages are consumed, acknowledged and
+         forgotten as soon as they are consumed. In these cases, updating the delivery count persistently
+         before delivering the message would add an extra persistent step <emphasis>for each message delivered</emphasis>,
+         implying a significant performance penalty.</para>
+      <para>However, if the delivery count is not updated persistently before the message delivery happens, in the event of 
+         a server crash, messages might not have been delivered. During the recovery phase, the server will not have
+         knowledge of that and will deliver the message with <literal>redelivered</literal> set to <literal>false</literal>
+         while it should be <literal>true</literal>.
+      </para>
+      <para>As this behavior breaks strict JMS semantics, JBoss Messaging allows to persist delivery count
+         before message delivery but disabled it by default for performance implications.</para>
+      <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal>true</literal> in <literal>jbm-configuration.xml</literal>:</para>
+      <programlisting>
+   &lt;persist-delivery-count-before-delivery&gt;true&lt;/persist-delivery-count-before-delivery&gt;
+      </programlisting>
+    </section>
+    
+   
+</chapter>

Copied: trunk/docs/user-manual/en/using-core.xml (from rev 6908, trunk/docs/user-manual/en/modules/using-core.xml)
===================================================================
--- trunk/docs/user-manual/en/using-core.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/using-core.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="using-core">
+    <title>Using Core</title>
+    <para>JBoss Messaging core is a completely JMS agnostic messaging system with its own core
+        API.</para>
+    <para>If you don't want to use JMS you can use the core API directly. The core API provides all
+        the functionality of JMS but without much of the complications. It also provides features
+        that are not normally available using JMS.</para>
+    <section>
+        <title>Core Messaging Concepts</title>
+        <para>Some of the core messaging concepts are similar to JMS concepts, but Core messaging
+            concepts differ in some ways. In general the core messaging API is simply than the JMS
+            API, since we remove distinctions between queues, topics and subscriptions. We'll
+            discuss each of the major core messaging concepts in turn:</para>
+        <section>
+            <title>Message</title>
+            <para>Messages are sent to <literal>addresses</literal>. When the message arrives on the
+                server the server routes it to zero or more queues depending on the address. Many
+                queues can be bound to a particular address on the server. The server will route the
+                message to all queues bound to that address.</para>
+            <para>Messages can durable or non durable. Durable messages in a durable queue will
+                survive a server crash or restart. Non durable messages will never survive a server
+                crash or restart.</para>
+        </section>
+        <section>
+            <title>Address</title>
+            <para>In core, there is no concept of a Topic, Topic is a JMS only term. Instead, in
+                core, we just deal with <emphasis>addresses</emphasis> and
+                    <emphasis>queues</emphasis>.</para>
+            <para>For example, a JMS topic would implemented by a single address to which many
+                queues are bound. Each queue represents a subscription of the topic. A JMS Queue
+                would be implemented as a single address to which one queue is bound - that queue
+                represents the JMS queue.</para>
+        </section>
+        <section>
+            <title>Queue</title>
+            <para>Queues can de durable, meaning they survive a server crash or restart, as long as
+                the messages in them are durable. Non durable queues do not survive a server restart
+                or crash even if the messages they contain are durable.</para>
+            <para>Queues can also be temporary, meaning they are automatically deleted when the
+                client connection is closed, if they are not explicitly deleted before that.</para>
+            <para>Queues can be bound with an optional filter expression. If a filter expression is
+                supplied then the server will only route messages who match that filter expression
+                to any queues bound to the address.</para>
+        </section>
+        <section>
+            <title>ClientSessionFactory</title>
+            <para>Clients use <literal>ClientSessionFactory</literal> instances to create <literal
+                    >ClientSession</literal> instances. <literal>ClientSessionFactory</literal>
+                instances know how to connect to the server to create sessions.</para>
+        </section>
+        <section>
+            <title>ClientSession</title>
+            <para>blah blah blah</para>
+            <para>ClientSession also fully supports both local and XA transactional
+                semantics.</para>
+        </section>
+        <section>
+            <title>ClientConsumer</title>
+            <para>Clients use <literal>ClientConsumer</literal> instances to consume messages from a
+                queue. Core Messaging supports both synchronous and asynchronous message consumption
+                semantics. <literal>ClientConsumer</literal> instances can be configured with an
+                optional filter expression and will only consume messages which match that
+                expression.</para>
+        </section>
+        <section>
+            <title>ClientProducer</title>
+            <para>Clients create <literal>ClientProducer</literal> instances on <literal
+                    >ClientSession</literal> instances so they can send messages.</para>
+        </section>
+    </section>
+    <section>
+        <title>A simple example of using Core</title>
+        <para/>
+    </section>
+    <section>
+        <title>Core transactions</title>
+        <para/>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/using-jms.xml (from rev 6908, trunk/docs/user-manual/en/modules/using-jms.xml)
===================================================================
--- trunk/docs/user-manual/en/using-jms.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/using-jms.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="using-jms">
+    <title>Using JMS</title>
+    <para>Although JBoss Messaging provides a JMS agnostic messaging API, many users will be more
+        comfortable using JMS.</para>
+    <para>JMS is a very popular API standard for messaging, and most messaging systems provide a JMS
+        API. If you are completely new to JMS we suggest you following the Sun JMS tutorial [link] -
+        a full JMS tutorial is out of scope for this guide.</para>
+    <para>JBoss Messaging also ships with a wide range of examples, many of which demonstrate JMS
+        API usage. A good place to start would be to play around with the simple JMS Queue and Topic
+        example, but we also provide examples for many other parts of the JMS API.</para>
+    <para>In this section we'll go through the main steps in configuring the server for JMS and
+        creating a simple JMS program. We'll also show how to configure and use JNDI, and also how
+        to use JMS with JBoss Messaging without using any JNDI.</para>
+    <section>
+        <title>A simple ordering system</title>
+        <para>For this chapter we're going to use a very simple ordering system as our example. It's
+            a somewhat contrived example because of its extreme simplicity, but it serves to
+            demonstrates the very basics of setting up and using JMS.</para>
+        <para>We will have a single JMS Queue <literal>OrderQueue</literal>, and we will have a
+            single <literal>MessageProducer</literal> sending an order message to the queue and a
+            single <literal>MessageConsumer</literal> consuming the order message from the
+            queue.</para>
+        <para>The queue will be a <literal>durable</literal> queue, i.e. it will survive a server
+            restart or crash. We also want to predeploy the queue, i.e. specifiy the queue in the
+            server JMS config so it's created automatically without us having to explicitly create
+            it from the client.</para>
+        <para/>
+    </section>
+    <section id="using-jms.server.configuration">
+        <title>JMS Server Configuration</title>
+        <para>The file <literal>jbm-jms.xml</literal> on the server classpath contains any JMS
+            Queue, Topic and ConnectionFactory instances that we wish to pre-deploy into the JNDI
+            server so we can look them up.</para>
+        <para>A JMS ConnectionFactory object is used by the client to make connections to the
+            server. It knows the location of the server it is connecting to, as well as many other
+            configuration parameters. In most cases the defaults will be acceptable.</para>
+        <para>We'll deploy a single JMS Queue and a single JMS Connection Factory instance on the
+            server for this example but there are no limits to the number of Queues, Topics and
+            Connection Factory instances you can deploy from the file. Here's our config:</para>
+        <programlisting>
+&lt;configuration xmlns="urn:jboss:messaging" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-jms.xsd "&gt;
+    
+    &lt;connection-factory name="ConnectionFactory"&gt;
+        &lt;connector-ref connector-name="netty"/&gt;
+        &lt;entries&gt;
+            &lt;entry name="ConnectionFactory"/&gt;           
+        &lt;/entries&gt;
+    &lt;/connection-factory&gt;
+    
+    &lt;queue name="OrderQueue"&gt;
+        &lt;entry name="queues/OrderQueue"/&gt;
+    &lt;/queue&gt;
+    
+&lt;/configuration&gt; 
+        </programlisting>
+        <para>We deploy one ConnectionFactory called <literal>ConnectionFactory</literal> and bind
+            it in just one place in JNDI as given by the <literal>entry</literal> element.
+            ConnectionFactory instances can be bound in many places in JNDI if you require. </para>
+        <para>Note that the JMS connection factory references a <literal>connector</literal> called
+                <literal>netty</literal>. This is a reference to a connector object deployed in the
+            main core configuration file <literal>jbm-configuration.xml</literal> which defines the
+            transport and parameters used to actually connect to the server.</para>
+    </section>
+    <section>
+        <title>JNDI configuration</title>
+        <para>When using JNDI from the client side you need to specify a set of JNDI properties
+            which tell the JNDI client where to locate the JNDI server, amongst other things. These
+            are often specified in a file jndi.properties on the client classpath, or you can
+            specify them directly when creating the JNDI initial context. A full JNDI tutorial is
+            outside the scope of this document, please see the Sun JNDI tutorial for more
+            information on how to use JNDI. [LINK]</para>
+        <para>For talking to the JBoss JNDI Server, the jndi properties will look something like
+            this:</para>
+        <programlisting>
+java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+java.naming.provider.url=jnp://myhost:1099
+java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces                        
+        </programlisting>
+        <para>Where <literal>myhost</literal> is the hostname or IP address of the JNDI server. 1099
+            is the port used by the JNDI server and may vary depending on how you have configured
+            your JNDI server.</para>
+        <para>In the default standalone configuration, JNDI server ports are configured in the
+                <literal>jbm-jboss-beans.xml</literal> file where the JNDIServer bean is confgured,
+            here's a snippet from the file:</para>
+        <programlisting>
+&lt;bean name="JNDIServer" class="org.jnp.server.Main"&gt;
+    &lt;property name="namingInfo"&gt;
+        &lt;inject bean="Naming"/&gt;
+    &lt;/property&gt;
+    &lt;property name="port"&gt;1099&lt;/property&gt;
+    &lt;property name="bindAddress"&gt;localhost&lt;/property&gt;
+    &lt;property name="rmiPort"&gt;1098&lt;/property&gt;
+    &lt;property name="rmiBindAddress"&gt;localhost&lt;/property&gt;
+&lt;/bean&gt;                        
+        </programlisting>
+        <para>If you want your JNDI server to be available to non local clients make sure you change
+            it's bind address to something other than <literal>localhost</literal>!</para>
+    </section>
+    <section>
+        <title>The code</title>
+        <para>Here's the code for the example:</para>
+        <para>First we'll create a JNDI initial context from which to lookup our JMS objects:</para>
+        <programlisting>InitialContect ic = new InitialContext();</programlisting>
+        <para>Now we'll look up the connection factory:</para>
+        <programlisting>ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");</programlisting>
+        <para>And look up the Queue:</para>
+        <programlisting>Queue orderQueue = (Queue)ic.lookup("/queues/OrderQueue");</programlisting>
+        <para>Next we create a JMS connection using the connection factory:</para>
+        <programlisting>Connection connection = cf.createConnection();</programlisting>
+        <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge
+            mode:</para>
+        <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
+        <para>We create a MessageProducer that will send orders to the queue:</para>
+        <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
+        <para>And we create a MessageConsumer which will consume orders from the queue:</para>
+        <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
+        <para>We make sure we start the connection, or delivery won't occur on it:</para>
+        <programlisting>connection.start();</programlisting>
+        <para>We create a simple TextMessage and send it:</para>
+        <programlisting>TextMessage message = session.createTextMessage("This is an order");
+producer.send(message);</programlisting>
+        <para>And we consume the message:</para>
+        <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
+System.out.println("Got order: " + receivedMessage.getText());
+        </programlisting>
+        <para>It's as simple as that. For a wide range of working JMS examples please see the
+            examples directory in the distribution.</para>
+    </section>
+    <section>
+        <title>Directly instantiating JMS Queue, Topic and ConnectionFactory instances without using
+            JNDI</title>
+        <para>Although it's a very common JMS usage pattern to lookup JMS <emphasis>Administered
+                Objects</emphasis> (that's JMS Queues, Topics and Connection Factories) from JNDI,
+            in some cases a JNDI server is not available and you still want to use JMS, or you just
+            think "Why do I need JNDI? Why can't I just instantiate these objects directly?"</para>
+        <para>With JBoss Messaging you can do exactly that. JBoss Messaging supports the direct
+            instantiation of JMS Queue, Topic and Connection Factory instances, so you don't have to
+            use JNDI at all.</para>
+        <para>For a full working example of direct instantiation please see the JMS examples.</para>
+        <para>Here's our simple example, rewritten to not use JNDI at all:</para>
+        <para>We create the JMS ConnectionFactory object directly, note we need to provide
+            connection params and specify which transport we are using:</para>
+        <programlisting>              
+TransportConfiguration transportConfiguration = 
+                     new TransportConfiguration(NettyConnectorFactory.class.getName());                
+ConnectionFactory cf = new JBossConnectionFactory();
+        </programlisting>
+        <para>We create the JMS Queue Object directly:</para>
+        <programlisting>Queue orderQueue = new JBossQueue("OrderQueue");</programlisting>
+        <para>Next we create a JMS connection using the connection factory:</para>
+        <programlisting>Connection connection = cf.createConnection();</programlisting>
+        <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge
+            mode:</para>
+        <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
+        <para>We create a MessageProducer that will send orders to the queue:</para>
+        <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
+        <para>And we create a MessageConsumer which will consume orders from the queue:</para>
+        <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
+        <para>We make sure we start the connection, or delivery won't occur on it:</para>
+        <programlisting>connection.start();</programlisting>
+        <para>We create a simple TextMessage and send it:</para>
+        <programlisting>TextMessage message = session.createTextMessage("This is an order");
+producer.send(message);</programlisting>
+        <para>And we consume the message:</para>
+        <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
+System.out.println("Got order: " + receivedMessage.getText());
+        </programlisting>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/using-server.xml (from rev 6908, trunk/docs/user-manual/en/modules/using-server.xml)
===================================================================
--- trunk/docs/user-manual/en/using-server.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/using-server.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,278 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="using-server">
+    <title>Using the Server</title>
+    <para>In this chapter you'll get familiar with the JBoss Messaging server.</para>
+    <para>We'll show where it is, how to start and stop it, and we'll describe the directory layout
+        and what all the files are and what they do.</para>
+    <para>For the remainder of this chapter when we talk about the JBoss Messaging server we mean
+        the JBoss Messaging standalone server, in its default configuration with a JMS Service and
+        JNDI service enabled.</para>
+    <para>When running embedded in JBoss Application Server the layout may be slightly different but
+        by and large will be the same.</para>
+    <section>
+        <title>Starting and Stopping the standalone server</title>
+        <para>In the distribution you will find a directory called <literal>bin</literal>.</para>
+        <para><literal>cd</literal> into that directory and you'll find a unix/linux script called
+                <literal>run.sh</literal> and a windows batch file called <literal
+            >run.bat</literal></para>
+        <para>To run on Unix/Linux type <literal>./run.sh</literal></para>
+        <para>To run on Windows type <literal>run.bat</literal></para>
+        <para>This scripts are very simple and basically just set-up the classpath and some JVM
+            parameters, and call the JBM bootstrap class as the Main class. The bootstrap is special
+            JBoss Microcontainer class which causes the JBoss Microcontainer to start-up.</para>
+        <para>To stop the server you'll also find a unix/linux script <literal>stop.sh</literal> and
+            a windows batch file <literal>run.bat</literal></para>
+        <para>To run on Unix/Linux type <literal>./stop.sh</literal></para>
+        <para>To run on Windows type <literal>stop.bat</literal></para>
+        <para>Please note that JBoss Messaging requires a Java 5 or later JDK to run. We recommend
+            running on Java 6.</para>
+    </section>
+    <section>
+        <title>Server JVM settings</title>
+        <para>The run scripts <literal>run.sh</literal> and <literal>run.bat</literal> set some JVM
+            settings for tuning running on Java 6 and choosing the garbage collection policy. We
+            recommend using a parallel garbage collection algorithm to smooth out latency and
+            minimises large GC pauses.</para>
+        <para>By default JBoss Messaging runs in a maximum of 1GB of RAM. To increase the memory
+            settings change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings
+            as you would for any Java program.</para>
+        <para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts
+            are the place to do it.</para>
+    </section>
+    <section>
+        <title>Server classpath</title>
+        <para>JBoss Messaging looks for its configuration files on the Java classpath</para>
+        <para>The scripts <literal>run.sh</literal> and <literal>run.bat</literal> specify the
+            classpath when calling Java to run the server.</para>
+        <para>In the distribution, the run scripts will add the non clustered configuration
+            directory to the classpath. This is a directory which contains a set of configuration
+            files for running the JBoss Messaging sever in a basic non-clustered configuration. In
+            the distribution this directory is <literal>config/stand-alone/non-clustered/</literal>
+            from the root of the distribution.</para>
+        <para>The distribution contains several standard configuration sets for running:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Non clustered stand-alone.</para>
+            </listitem>
+            <listitem>
+                <para>Clustered stand-alone</para>
+            </listitem>
+            <listitem>
+                <para>Non clustered in JBoss Application Server</para>
+            </listitem>
+            <listitem>
+                <para>Clustered in JBoss Application Server</para>
+            </listitem>
+        </itemizedlist>
+        <para>You can of course create your own configuration and specify any configuration
+            directory when running the run script.</para>
+        <para>Just make sure the directory is on the classpath and JBoss Messaging will search there
+            when starting up.</para>
+        <para>The run scripts also add the location for the various XML schema definition files (xsd
+            files) used by JBoss Messaging to describe its configuration files. By default these are
+            located in <literal>schemas</literal> directory from the root of the
+            distribution.</para>
+    </section>
+    <section>
+        <title>System properties</title>
+        <para>JBoss Messaging also takes a couple of Java system properties on the command line for
+            configuring logging properties</para>
+        <para>JBoss Messaging uses JDK logging to minimise dependencies on other logging systems.
+            JDK logging can then be configured to delegate to some other framework, e.g. log4j if
+            that's what you prefer.</para>
+        <para>For more information on configuring logging, please see the section configuring
+            logging</para>
+    </section>
+    <section>
+        <title>Configuration files</title>
+        <para>The configuration directory is specified on the classpath in the run scripts <literal
+                >run.sh</literal> and <literal>run.bat</literal> This directory can contain the
+            following files.</para>
+        <itemizedlist>
+            <listitem>
+                <para><literal>jbm-jboss-beans.xml</literal>. This is the JBoss Microcontainer beans
+                    file which instructs it what beans to create and what dependencies to enforce
+                    between them. Remember that JBoss Messaging is just a set of POJOs. In the
+                    stand-alone server, it's the JBoss Microcontainer which instantiates these POJOs
+                    and enforces dependencies between them and other beans. Please see the <xref
+                        linkend="usingserver.mainconfig"/> section for more information on this
+                    file.</para>
+            </listitem>
+            <listitem>
+                <para><literal>jbm-configuration.xml</literal>. This is the main JBoss Messaging
+                    configuration file. We'll describe it fully in section [LINK]</para>
+            </listitem>
+            <listitem>
+                <para><literal>jbm-queues.xml</literal>. This file contains pre-defined queues,
+                    queue settings and security settings. The file is optional - all this
+                    configuration can also live in <literal>jbm-configuration.xml</literal>. In
+                    fact, the default configuration sets do not have a <literal
+                        >jbm.queues.xml</literal> file. The purpose of allowing queues to be
+                    configured in these files is to allow you to manage your queue configuration
+                    over many files instead of being forced to maintain it in a single file. There
+                    can be many <literal>jbm-queues.xml</literal> files on the classpath. All will
+                    be loaded if found.. This file is described in full here [LINK]</para>
+            </listitem>
+            <listitem>
+                <para><literal>jbm-users.xml</literal> JBoss Messaging ships with a security manager
+                    impementation which obtains user credentials from the <literal
+                        >jbm-users.xml</literal> file. This file contains user, password and role
+                    information. For more information on security please see the section
+                    [LINK]</para>
+            </listitem>
+            <listitem>
+                <para><literal>jbm-jms.xml</literal> The distro configuration by default includes a
+                    server side JMS service which mainly deploys JMS Queues, Topics and
+                    ConnectionFactorys from this file into JNDI. If you're not using JMS, or you
+                    don't need to deploy JMS objects on the server side, then you don't need this
+                    file.</para>
+            </listitem>
+            <listitem>
+                <para><literal>logging.properties</literal></para>
+            </listitem>
+            <listitem>
+                <para><literal>log4j.xml</literal></para>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section id="server.microcontainer.configuration">
+        <title>JBoss Microcontainer Beans File</title>
+        <para>The stand-alone server is basically a set of POJOs which are instantiated by the light
+            weight JBoss Microcontainer engine. [LINK]</para>
+        <para>Also when running JBoss Messaging in JBoss Application Server, a beans file is also
+            required since JBoss Application Server version 5 or later is basically just an instance
+            of JBoss Microcontainer with various different services running in it.</para>
+        <para>The beans file is what tells JBoss Microcontainer which POJOs to instantiate and what
+            their dependencies are. The beans files used when running in JBoss Messaging stand-alone
+            and when running in JBoss Application Server are slightly different, mainly due to the
+            security manager being used.</para>
+        <para>Let's take a look at an example beans file from the stand-alone server:</para>
+        <para>
+            <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+
+&lt;deployment xmlns="urn:jboss:bean-deployer:2.0"&gt;
+
+&lt;bean name="Naming" class="org.jnp.server.NamingBeanImpl"/&gt;
+
+&lt;!-- JNDI server. Disable this if you don't want JNDI --&gt;
+&lt;bean name="JNDIServer" class="org.jnp.server.Main"&gt;
+&lt;property name="namingInfo"&gt;
+&lt;inject bean="Naming"/&gt;
+&lt;/property&gt;
+&lt;property name="port"&gt;1099&lt;/property&gt;
+&lt;property name="bindAddress"&gt;localhost&lt;/property&gt;
+&lt;property name="rmiPort"&gt;1098&lt;/property&gt;
+&lt;property name="rmiBindAddress"&gt;localhost&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;!-- MBean server --&gt;
+&lt;bean name="MBeanServer" class="javax.management.MBeanServer"&gt;
+&lt;constructor factoryClass="java.lang.management.ManagementFactory"
+factoryMethod="getPlatformMBeanServer"/&gt;
+&lt;/bean&gt; 
+
+&lt;!-- The core configuration --&gt;
+&lt;bean name="Configuration" class="org.jboss.messaging.core.config.impl.FileConfiguration"&gt;
+&lt;/bean&gt;
+
+&lt;!-- The security manager --&gt;
+&lt;bean name="JBMSecurityManager" 
+      class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl"&gt;
+&lt;start ignored="true"/&gt;
+&lt;stop ignored="true"/&gt;
+&lt;/bean&gt;
+
+&lt;!-- The core server --&gt;
+&lt;bean name="MessagingServer" class="org.jboss.messaging.core.server.impl.MessagingServerImpl"&gt;
+&lt;start ignored="true"/&gt;
+&lt;stop ignored="true"/&gt;  
+&lt;constructor&gt;
+&lt;parameter&gt;
+&lt;inject bean="Configuration"/&gt;
+&lt;/parameter&gt;
+&lt;parameter&gt;
+&lt;inject bean="MBeanServer"/&gt;
+&lt;/parameter&gt;
+&lt;parameter&gt;
+&lt;inject bean="JBMSecurityManager"/&gt;
+&lt;/parameter&gt;        
+&lt;/constructor&gt;         
+&lt;/bean&gt;
+
+&lt;!-- The JMS server --&gt;
+&lt;bean name="JMSServerManager" 
+      class="org.jboss.messaging.jms.server.impl.JMSServerManagerImpl"&gt;
+&lt;constructor&gt;         
+&lt;parameter&gt;
+&lt;inject bean="MessagingServer"/&gt;
+&lt;/parameter&gt;         
+&lt;/constructor&gt;
+&lt;/bean&gt;
+
+&lt;/deployment&gt;</programlisting>
+        </para>
+        <para>We can see that, as well as the core JBoss Messaging server, the stand-alone server
+            instantiates various different POJOs, lets look at them in turn:</para>
+        <itemizedlist>
+            <listitem>
+                <para>JNDIServer</para>
+                <para>Many clients like to look up JMS Objects from JNDI so we provide a JNDI server
+                    for them to do that. If you don't need JNDI this can be commented out or
+                    removed.</para>
+            </listitem>
+            <listitem>
+                <para>MBeanServer</para>
+                <para>In order to provide a JMX management interface a JMS MBean server is necessary
+                    in which to register the management objects. Normally this is just the default
+                    platform MBean Server available in the JVM instance. If you don't want to
+                    provide a JMX management interface this can be commented out or removed.</para>
+            </listitem>
+            <listitem>
+                <para>Configuration</para>
+                <para>The messaging server is configured with a Configuration object. In the default
+                    stand-alone set-up it uses a FileConfiguration object which knows to read
+                    configuration information from the file system. In different configurations such
+                    as embedded you might want to provide configuration information from somewhere
+                    else.</para>
+            </listitem>
+            <listitem>
+                <para>Security Manager. The security manager used by the messaging server is
+                    pluggable. The default one used just reads user-role information from the
+                        <literal>jbm-users.xml</literal> file on disk. However it can be replaced by
+                    a JAAS security manager, or when running inside JBoss Application Server it is
+                    configure to use the JBoss AS security manager for tight integration with JBoss
+                    AS security.</para>
+            </listitem>
+            <listitem>
+                <para>MessagingServer</para>
+                <para>This is the JMS agnostic core server. It's where 99% of the magic
+                    happens</para>
+            </listitem>
+            <listitem>
+                <para>JMSServerManager</para>
+                <para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory
+                    instances from <literal>jbm-jms.xml</literal> files on the disk. It also
+                    provides a simple management API for manipulating JMS Objects. On the whole it
+                    just translates and delegates its work to the core server. If you don't need to
+                    deploy JMS Queues, Topics and ConnectionFactorys from server side config and
+                    don't require the JMS management interface this can be disabled.</para>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section id="usingserver.mainconfig">
+        <title>The main configuration file.</title>
+        <para>The configuration for the JBoss Messaging core server is contained in <literal
+                >jbm-configuration.xml</literal>. This is what the FileConfiguration bean uses to
+            configure the messaging server.</para>
+        <para>There are many attributes which which you can configure JBoss Messaging. In most cases
+            the defaults will do fine, in fact every attribute can be defaulted which means a file
+            with a single empty <literal>configuration</literal> element is a valid configuration
+            file.</para>
+        <para>We'll take a look at an example <literal>jbm-configuration.xml</literal> file where
+            all attributes have been specified, and we'll give a brief explanation of each with a
+            link to the appropriate section for its related concepts.</para>
+        <para>Note that in any real example you'd rarely have to explicitly specify each attribute
+            value.</para>
+        <para>TODO jbm configuration file and explanation.</para>
+    </section>
+</chapter>

Copied: trunk/docs/user-manual/en/wildcard-syntax.xml (from rev 6908, trunk/docs/user-manual/en/modules/wildcard-syntax.xml)
===================================================================
--- trunk/docs/user-manual/en/wildcard-syntax.xml	                        (rev 0)
+++ trunk/docs/user-manual/en/wildcard-syntax.xml	2009-05-20 08:58:22 UTC (rev 6909)
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="wildcard-syntax">
+    <title>Understanding the JBoss Messaging Wildcard Syntax</title>
+    <para>JBoss Messaging uses a specific syntax for representing wildcards in security settings, address settings and when creating consumers.</para>
+    <para>The syntax is similar to that used by AMQP [LINK]</para>
+    <para>A JBoss Messaging wildcard expression contains words delimited by the character '<literal>.</literal>' (full stop).</para>
+    <para>The special characters '<literal>#</literal>' and '<literal>*</literal>' also have special meaning and can take the place of a word.</para>
+    <para>The character '<literal>#</literal>' means 'match any sequence of zero or more words'.</para>
+    <para>The character '<literal>*</literal>' means 'match a single word'.</para>
+    <para>So the wildcard 'news.europe.#' would match 'news.europe', 'news.europe.sport', 'news.europe.politics', and 'news.europe.politics.regional'
+    but would not match 'news.usa', 'news.usa.sport' nor 'entertainment'.</para>
+    <para>The wildcard 'news.*' would match 'news.europe', but not 'news.europe.sport'.</para>
+    <para>The wildcard 'news.*.sport' would match 'news.europe.sport' and also 'news.usa.sport', but not 'news.europe.politics'.</para>
+    
+    
+    
+</chapter>
+

Modified: trunk/docs/user-manual/user-manual.xpr
===================================================================
--- trunk/docs/user-manual/user-manual.xpr	2009-05-20 07:49:41 UTC (rev 6908)
+++ trunk/docs/user-manual/user-manual.xpr	2009-05-20 08:58:22 UTC (rev 6909)
@@ -7,51 +7,55 @@
     </meta>
     <projectTree name="user-manual.xpr">
         <folder name="en">
-            <folder name="images"/>
-            <folder name="modules">
-                <file name="en/modules/appserver-integration.xml"/>
-                <file name="en/modules/architecture.xml"/>
-                <file name="en/modules/client-reconnection.xml"/>
-                <file name="en/modules/clusters.xml"/>
-                <file name="en/modules/configuration-index.xml"/>
-                <file name="en/modules/configuring-transports.xml"/>
-                <file name="en/modules/connection-ttl.xml"/>
-                <file name="en/modules/core-bridges.xml"/>
-                <file name="en/modules/diverts.xml"/>
-                <file name="en/modules/duplicate-detection.xml"/>
-                <file name="en/modules/embedding-jbm.xml"/>
-                <file name="en/modules/examples.xml"/>
-                <file name="en/modules/filter-expressions.xml"/>
-                <file name="en/modules/flow-control.xml"/>
-                <file name="en/modules/ha.xml"/>
-                <file name="en/modules/intercepting-operations.xml"/>
-                <file name="en/modules/interoperability.xml"/>
-                <file name="en/modules/jms-core-mapping.xml"/>
-                <file name="en/modules/large-messages.xml"/>
-                <file name="en/modules/last-value-queues.xml"/>
-                <file name="en/modules/logging.xml"/>
-                <file name="en/modules/management.xml"/>
-                <file name="en/modules/message-expiry.xml"/>
-                <file name="en/modules/message-grouping.xml"/>
-                <file name="en/modules/messaging-concepts.xml"/>
-                <file name="en/modules/paging.xml"/>
-                <file name="en/modules/perf-tuning.xml"/>
-                <file name="en/modules/persistence.xml"/>
-                <file name="en/modules/pre-acknowledge.xml"/>
-                <file name="en/modules/preface.xml"/>
-                <file name="en/modules/project-info.xml"/>
-                <file name="en/modules/queue-attributes.xml"/>
-                <file name="en/modules/scheduled-messages.xml"/>
-                <file name="en/modules/security.xml"/>
-                <file name="en/modules/send-guarantees.xml"/>
-                <file name="en/modules/thread-pooling.xml"/>
-                <file name="en/modules/undelivered-messages.xml"/>
-                <file name="en/modules/using-core.xml"/>
-                <file name="en/modules/using-jms.xml"/>
-                <file name="en/modules/using-server.xml"/>
-                <file name="en/modules/wildcard-syntax.xml"/>
+            <folder name="diagrams">
+                <file name="en/diagrams/architecture-diagrams.odg"/>
             </folder>
+            <folder name="images">
+                <file name="en/images/architecture1.jpg"/>
+            </folder>
+            <file name="en/appserver-integration.xml"/>
+            <file name="en/architecture.xml"/>
+            <file name="en/client-reconnection.xml"/>
+            <file name="en/clusters.xml"/>
+            <file name="en/command-buffering.xml"/>
+            <file name="en/configuration-index.xml"/>
+            <file name="en/configuring-transports.xml"/>
+            <file name="en/connection-ttl.xml"/>
+            <file name="en/core-bridges.xml"/>
+            <file name="en/diverts.xml"/>
+            <file name="en/duplicate-detection.xml"/>
+            <file name="en/embedding-jbm.xml"/>
+            <file name="en/examples.xml"/>
+            <file name="en/filter-expressions.xml"/>
+            <file name="en/flow-control.xml"/>
+            <file name="en/ha.xml"/>
+            <file name="en/intercepting-operations.xml"/>
+            <file name="en/interoperability.xml"/>
+            <file name="en/jms-core-mapping.xml"/>
+            <file name="en/large-messages.xml"/>
+            <file name="en/last-value-queues.xml"/>
+            <file name="en/logging.xml"/>
+            <file name="en/management.xml"/>
             <file name="en/master.xml"/>
+            <file name="en/message-expiry.xml"/>
+            <file name="en/message-grouping.xml"/>
+            <file name="en/messaging-concepts.xml"/>
+            <file name="en/paging.xml"/>
+            <file name="en/perf-tuning.xml"/>
+            <file name="en/persistence.xml"/>
+            <file name="en/pre-acknowledge.xml"/>
+            <file name="en/preface.xml"/>
+            <file name="en/project-info.xml"/>
+            <file name="en/queue-attributes.xml"/>
+            <file name="en/scheduled-messages.xml"/>
+            <file name="en/security.xml"/>
+            <file name="en/send-guarantees.xml"/>
+            <file name="en/thread-pooling.xml"/>
+            <file name="en/undelivered-messages.xml"/>
+            <file name="en/using-core.xml"/>
+            <file name="en/using-jms.xml"/>
+            <file name="en/using-server.xml"/>
+            <file name="en/wildcard-syntax.xml"/>
         </folder>
     </projectTree>
 </project>




More information about the jboss-cvs-commits mailing list