[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><resourceadapter>
+ <resourceadapter-class>org.jboss.messaging.ra.JBMResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport type</description>
+ <config-property-name>ConnectorClassName</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>org.jboss.messaging.core.remoting.impl.invm.InVMConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
+ <config-property-name>ConnectionParameters</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>jbm.remoting.invm.serverid=0</config-property-value>
+ </config-property>
+ <config-property>
+ <description>Use XA methods to obtain connections?</description>
+ <config-property-name>UseXA</config-property-name>
+ <config-property-type>java.lang.Boolean</config-property-type>
+ <config-property-value>true</config-property-value>
+ </config-property>
+
+ <outbound-resourceadapter>
+ <connection-definition>
+ <managedconnectionfactory-class>org.jboss.messaging.ra.JBMManagedConnectionFactory</managedconnectionfactory-class>
+
+ <config-property>
+ <description>The default session type</description>
+ <config-property-name>SessionDefaultType</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>javax.jms.Queue</config-property-value>
+ </config-property>
+ <config-property>
+ <description>Try to obtain a lock within specified number of seconds; less than or equal to 0 disable this functionality</description>
+ <config-property-name>UseTryLock</config-property-name>
+ <config-property-type>java.lang.Integer</config-property-type>
+ <config-property-value>0</config-property-value>
+ </config-property>
+
+ <connectionfactory-interface>org.jboss.messaging.ra.JBMConnectionFactory</connectionfactory-interface>
+ <connectionfactory-impl-class>org.jboss.messaging.ra.JBMConnectionFactoryImpl</connectionfactory-impl-class>
+ <connection-interface>javax.jms.Session</connection-interface>
+ <connection-impl-class>org.jboss.messaging.ra.JBMSession</connection-impl-class>
+ </connection-definition>
+ <transaction-support>XATransaction</transaction-support>
+ <authentication-mechanism>
+ <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
+ <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
+ </authentication-mechanism>
+ <reauthentication-support>false</reauthentication-support>
+ </outbound-resourceadapter>
+
+ <inbound-resourceadapter>
+ <messageadapter>
+ <messagelistener>
+ <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
+ <activationspec>
+ <activationspec-class>org.jboss.messaging.ra.inflow.JBMActivationSpec</activationspec-class>
+ <required-config-property>
+ <config-property-name>destination</config-property-name>
+ </required-config-property>
+ </activationspec>
+ </messagelistener>
+ </messageadapter>
+ </inbound-resourceadapter>
+
+ </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><tx-connection-factory>
+ <jndi-name>RemoteJmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>jms-ra.rar</rar-name>
+ <connection-definition>org.jboss.messaging.ra.JBMConnectionFactory</connection-definition>
+ <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
+ <config-property name="ConnectorClassName" type="java.lang.String">org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</config-property>
+ <config-property name="ConnectionParameters" type="java.lang.String">jbm.remoting.netty.port=5445</config-property>
+ <max-pool-size>20</max-pool-size>
+</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<String, String> jndiParameters = new Hashtable<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><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="JMSBridge" class="org.jboss.messaging.jms.bridge.impl.JMSBridgeImpl">
+ <!-- JBoss Messaging must be started before the bridge -->
+ <depends>MessagingServer</depends>
+ <constructor>
+ <!-- Source ConnectionFactory Factory -->
+ <parameter>
+ <inject bean="SourceCFF"/>
+ </parameter>
+ <!-- Target ConnectionFactory Factory -->
+ <parameter>
+ <inject bean="TargetCFF"/>
+ </parameter>
+ <!-- Source DestinationFactory -->
+ <parameter>
+ <inject bean="SourceDestinationFactory"/>
+ </parameter>
+ <!-- Target DestinationFactory -->
+ <parameter>
+ <inject bean="TargetDestinationFactory"/>
+ </parameter>
+ <!-- Source username (no username here) -->
+ <parameter><null /></parameter>
+ <!-- Source password (no password here)-->
+ <parameter><null /></parameter>
+ <!-- Target username (no username here)-->
+ <parameter><null /></parameter>
+ <!-- Target password (no password here)-->
+ <parameter><null /></parameter>
+ <!-- Selector -->
+ <parameter><null /></parameter>
+ <!-- Interval to retry in case of failure (in ms) -->
+ <parameter>5000</parameter>
+ <!-- Maximum number of retries to connect to the source and target -->
+ <parameter>10</parameter>
+ <!-- Quality of service -->
+ <parameter>ONCE_AND_ONLY_ONCE</parameter>
+ <!-- Maximum batch size -->
+ <parameter>1</parameter>
+ <!-- Maximum batch time (-1 means infinite) -->
+ <parameter>-1</parameter>
+ <!-- Subscription name (no subscription name here)-->
+ <parameter><null /></parameter>
+ <!-- client ID (no client ID here)-->
+ <parameter><null /></parameter>
+ <!-- concatenate JMS messageID to the target's message header -->
+ <parameter>true</parameter>
+ </constructor>
+ <property name="transactionManager">
+ <inject bean="RealTransactionManager"/>
+ </property>
+ </bean>
+
+ <!-- SourceCFF describes the ConnectionFactory used to connect to the source destination -->
+ <bean name="SourceCFF" class="org.jboss.messaging.jms.bridge.impl.JNDIConnectionFactoryFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/ConnectionFactory</parameter>
+ </constructor>
+ </bean>
+
+ <!-- TargetCFF describes the ConnectionFactory used to connect to the target destination -->
+ <bean name="TargetCFF" class="org.jboss.messaging.jms.bridge.impl.JNDIConnectionFactoryFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/ConnectionFactory</parameter>
+ </constructor>
+ </bean>
+
+ <!-- SourceDestinationFactory describes the Destination used as the source -->
+ <bean name="SourceDestinationFactory" class="org.jboss.messaging.jms.bridge.impl.JNDIDestinationFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/queue/source</parameter>
+ </constructor>
+ </bean>
+
+ <!-- TargetDestinationFactory describes the Destination used as the target -->
+ <bean name="TargetDestinationFactory" class="org.jboss.messaging.jms.bridge.impl.JNDIDestinationFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/queue/target</parameter>
+ </constructor>
+ </bean>
+
+ <!-- JNDI is a Hashtable containing the JNDI properties required -->
+ <!-- to connect to the sources and targets JMS resrouces -->
+ <bean name="JNDI" class="java.util.Hashtable">
+ <constructor class="java.util.Map">
+ <map class="java.util.Hashtable" keyClass="java.lang.String"
+ valueClass="java.lang.String">
+ <entry>
+ <key>java.naming.factory.initial</key>
+ <value>org.jnp.interfaces.NamingContextFactory</value>
+ </entry>
+ <entry>
+ <key>java.naming.provider.url</key>
+ <value>jnp://localhost:1099</value>
+ </entry>
+ <entry>
+ <key>java.naming.factory.url.pkgs</key>
+ <value>org.jboss.naming:org.jnp.interfaces"</value>
+ </entry>
+ </map>
+ </constructor>
+ </bean>
+
+</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>
+ <properties depends="arjuna" name="jta">
+ ...
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1"
+ value="org.jboss.messaging.jms.server.recovery.MessagingXAResourceRecovery;java:/XAConnectionFactory"/>
+ </properties>
+ </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>
+ <connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+ </entries>
+ <retry-interval>1000</retry-interval>
+ <retry-interval-multiplier>1.5</retry-interval-multiplier>
+ <reconnect-attempts>1000</reconnect-attempts>
+ </connection-factory>
+ </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><broadcast-groups>
+ <broadcast-group name="my-broadcast-group">
+ <local-bind-port>54321</local-bind-port>
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <broadcast-period>1000</broadcast-period>
+ <connector-ref connector-name="netty-connector" backup-connector-name="backup-connector"/>
+ </broadcast-group>
+</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><discovery-groups>
+ <discovery-group name="my-discovery-group">
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <refresh-timeout>10000</refresh-timeout>
+ </discovery-group>
+</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><connection-factory name="ConnectionFactory">
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+</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>
+<cluster-connections>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <retry-interval>500</retry-interval>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>false</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ </cluster-connection>
+</cluster-connections>
+ </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>
+<connection-factory name="ConnectionFactory">
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <connection-load-balancing-policy-class-name>org.jboss.messaging.core.client.impl.RandomConnectionLoadBalancingPolicy</connection-load-balancing-policy-class-name>
+</connection-factory>
+ </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><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="my-connector1" backup-connector-name="my-backup-connector1"/>
+ <connector-ref connector-name="my-connector2" backup-connector-name="my-backup-connector2"/>
+ <connector-ref connector-name="my-connector3" backup-connector-name="my-backup-connector3"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+</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<Pair<TransportConfiguration, TransportConfiguration>> serverList = new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair<TransportConfiguration, TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair<TransportConfiguration, TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair<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<Pair<TransportConfiguration, TransportConfiguration>> serverList = new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair<TransportConfiguration, TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair<TransportConfiguration, TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair<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><cluster-connections>
+ <cluster-connection name="my-explicit-cluster">
+ <address>jms</address>
+ <connector-ref connector-name="my-connector1" backup-connector-name="my-backup-connector1"/>
+ <connector-ref connector-name="my-connector2" backup-connector-name="my-backup-connector2"/>
+ <connector-ref connector-name="my-connector3" backup-connector-name="my-backup-connector3"/>
+ </cluster-connection>
+</cluster-connections></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><address-settings>
+ <address-setting match="jms.#">
+ <redistribution-delay>0</redistribution-delay>
+ </address-setting>
+ </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>
+<acceptors>
+ <acceptor name="netty">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory</factory-class>
+ <param key="jbm.remoting.netty.port" value="5446" type="Integer"/>
+ </acceptor>
+</acceptors>
+ </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>
+<connectors>
+ <connector name="netty">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
+ <param key="jbm.remoting.netty.port" value="5446" type="Integer"/>
+ </connector>
+</connectors>
+ </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>
+<connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+ </entries>
+</connection-factory>
+ </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<String, Object> connectionParams = new HashMap<String, Object>();
+
+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<String, Object> connectionParams = new HashMap<String, Object>();
+
+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><?xml version="1.0" encoding="UTF-8"?>
+<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">
+ <context-param>
+ <param-name>serverChannelName</param-name>
+ <param-value>org.jboss.jbm</param-value>
+ </context-param>
+
+ <context-param>
+ <param-name>streaming</param-name>
+ <param-value>true</param-value>
+ </context-param>
+
+ <context-param>
+ <param-name>reconnectTimeout</param-name>
+ <param-value>3000</param-value>
+ </context-param>
+
+ <listener>
+ <listener-class>org.jboss.netty.channel.socket.http.HttpTunnelingSessionListener</listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>org.jboss.netty.channel.socket.http.HttpTunnelingContextListener</listener-class>
+ </listener>
+
+ <servlet>
+ <servlet-name>NettyServlet</servlet-name>
+ <servlet-class>org.jboss.netty.channel.socket.http.HttpTunnelingServlet</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>NettyServlet</servlet-name>
+ <url-pattern>/JBMServlet</url-pattern>
+ </servlet-mapping>
+</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>
+<acceptors>
+
+ <acceptor name="netty-invm">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory</factory-class>
+ <param key="jbm.remoting.netty.useinvm" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.host" value="org.jboss.jbm" type="String"/>
+ </acceptor>
+
+</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><connectors>
+
+ <connector name="netty-servlet">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
+ <param key="jbm.remoting.netty.host" value="localhost" type="String"/>
+ <param key="jbm.remoting.netty.port" value="8080" type="Integer"/>
+ <param key="jbm.remoting.netty.useservlet" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.servletpath" value="/messaging/JBMServlet" type="String"/>
+ </connector>
+
+ </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>
+<bridge name="my-bridge">
+ <queue-name>jms.queue.sausage-factory</queue-name>
+ <forwarding-address>jms.queue.mincing-machine</forwarding-address>
+ <filter-string="name='aardvark'"/>
+ <transformer-class-name>org.jboss.jms.example.HatColourChangeTransformer</transformer-class-name>
+ <retry-interval>1000</retry-interval>
+ <retry-interval-multiplier>1.0</retry-interval-multiplier>
+ <reconnect-attempts>-1</reconnect-attempts>
+ <failover-on-server-shutdown>false</failover-on-server-shutdown>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <connector-ref connector-name="remote-connector" backup-connector-name="backup-remote-connector"/>
+</bridge>
+ </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>
+<divert name="prices-divert">
+ <address>jms.topic.priceUpdates</address>
+ <forwarding-address>jms.queue.priceForwarding</forwarding-address>
+ <filter string="office='New York'"/>
+ <transformer-class-name>org.jboss.jms.example.AddForwardingTimeTransformer</transformer-class-name>
+ <exclusive>true</exclusive>
+</divert>
+ </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>
+<divert name="order-divert">
+ <address>jms.queue.orders</address>
+ <forwarding-address>jms.topic.spyTopic</forwarding-address>
+ <exclusive>false</exclusive>
+</divert>
+ </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<TransportConfiguration> transports = new HashSet<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><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
+ factoryMethod="getPlatformMBeanServer"/>
+ </bean>
+
+ <!-- The core configuration -->
+ <bean name="Configuration"
+ class="org.jboss.messaging.core.config.impl.FileConfiguration">
+ </bean>
+
+ <!-- The security manager -->
+ <bean name="JBMSecurityManager"
+ class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ </bean>
+
+ <!-- The core server -->
+ <bean name="MessagingServer"
+ class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ <constructor>
+ <parameter>
+ <inject bean="Configuration"/>
+ </parameter>
+ <parameter>
+ <inject bean="MBeanServer"/>
+ </parameter>
+ <parameter>
+ <inject bean="JBMSecurityManager"/>
+ </parameter>
+ </constructor>
+ </bean>
+ </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>>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>
+<connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty-connector"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+
+ <!-- Set the consumer window size to 0 to have *no* buffer on the client side -->
+ <consumer-window-size>0</consumer-window-size>
+</connection-factory>
+ </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><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty-connector"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <!-- We limit consumers created on this connection factory to consume messages at a maximum rate
+ of 10 messages per sec -->
+ <consumer-max-rate>10</consumer-max-rate>
+ </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><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty-connector"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <!-- We limit producers created on this connection factory to produce messages at a maximum rate
+ of 10 messages per sec -->
+ <producer-max-rate>10</producer-max-rate>
+ </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><backup-connector-ref connector-name="backup-connector"/>
+
+<!-- Connectors -->
+
+<connectors>
+
+ ...
+
+ <!-- This connector specifies how to connect to the backup server -->
+ <connector name="backup-connector">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
+ <param key="jbm.remoting.netty.port" value="5445" type="Integer"/>
+ </connector>
+
+</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><backup>true</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>
+<remoting-interceptors>
+ <class-name>org.jboss.jms.example.LoginInterceptor</class-name>
+ <class-name>org.jboss.jms.example.AdditionalPropertyInterceptor</class-name>
+</remoting-interceptors>
+ </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>
+ <!-- expired messages in JMS Queue "orders.europe"
+ will be sent to the JMS Queue "expiry.europe" -->
+ <address-setting match="jms.queue.orders.europe">
+ <expiry-address>jms.queue.expiry.europe</expiry-address>
+ ...
+ </address-setting>
+ </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><configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
+
+...
+
+<large-message-directory> *** type any folder you choose *** </large-message-directory>
+
+...
+
+</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>...
+<connection-factory name="ConnectionFactory">
+<connector-ref connector-name="netty"/>
+<entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+</entries>
+
+<min-large-message-size>250000</min-large-message-size>
+</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 < 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 < 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>
+ <address-setting match="jms.queue.lastValueQueue">
+ <last-value-queue>true</last-value-queue>
+ </address-setting>
+ </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="<the address name>"</literal>
+ or the resource name <literal>core.address.<the address name></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="<the bound address>",name="<the queue name>"</literal>
+ or the resource name <literal>core.queue.<the queue name></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="<the acceptor name>"</literal>
+ or the resource name <literal>core.acceptor.<the address name></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=<the divert name></literal>
+ or the resource name <literal>core.divert.<the divert name></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="<the bridge name>"</literal>
+ or the resource name <literal>core.bridge.<the bridge name></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="<the broadcast group name>"</literal>
+ or the resource name <literal>core.broadcastgroup.<the broadcast group name></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="<the discovery group name>"</literal>
+ or the resource name <literal>core.discovery.<the discovery group name></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="<the cluster connection name>"</literal>
+ or the resource name <literal>core.clusterconnection.<the cluster connection name></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="<the connection factory name>"</literal>
+ or the resource name <literal>jms.connectionfactory.<the connection factory name></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="<the queue name>"</literal>
+ or the resource name <literal>jms.queue.<the queue name></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="<the topic name>"</literal>
+ or the resource name <literal>jms.topic.<the topic name></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>
+ <!-- false to disable JMX management for JBoss Messaging -->
+ <jmx-management-enabled>false</jmx-management-enabled>
+ </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>
+ <!-- MBeanServer -->
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
+ factoryMethod="getPlatformMBeanServer" />
+ </bean>
+ </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>
+ <management-address>jbm.management</management-address>
+ </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>
+ <!-- users with the admin role will be allowed to manage -->
+ <!-- JBoss Messaging using management messages -->
+ <security-setting match="jbm.management">
+ <permission type="manage" roles="admin" />
+ </security-setting>
+ </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>
+ <management-cluster-password>CHANGE ME!!</management-cluster-password>
+ </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>
+ <management-request-timeout>5000</management-request-timeout>
+ </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>
+ <management-notification-address>jbm.notifications</management-notification-address>
+ </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>
+ <message-counter-enabled>true</message-counter-enabled>
+ </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>
+ <!-- keep history for a week -->
+ <message-counter-max-day-history>7</message-counter-max-day-history>
+ <!-- sample the queues every minute (60000ms) -->
+ <message-counter-sample-period>60000</message-counter-sample-period>
+ </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>
+<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
+<address-setting match="jms.queue.exampleQueue">
+ <expiry-address>jms.queue.expiryQueue</expiry-address>
+</address-setting>
+ </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>
+ <address-setting match="jms.queue.exampleQueue">
+ <distribution-policy-class>org.jboss.messaging.core.server.impl.GroupingRoundRobinDistributor</distribution-policy-class>
+ </address-setting>
+ </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><configuration xmlns="urn:jboss:messaging"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
+
+...
+
+<paging-max-global-size-bytes>20485760</paging-max-global-size-bytes>
+<paging-global-watermark-size>1048576</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> <address-settings>
+ <address-setting match="jms.someaddress">
+ <max-size-bytes>-1</max-size-bytes>
+ <page-size-bytes>10485760</page-size-bytes>
+ <drop-messages-when-full>10485760</drop-messages-when-full>
+ </address-setting>
+ </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&op=viewforum&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&op=viewforum&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><queue name="selectorQueue">
+ <entry name="/queue/selectorQueue"/>
+ <filter string="color='red'"/>
+ <durable>true</durable>
+</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><queues>
+ <queue name="jms.queue.selectorQueue">
+ <address>jms.queue.selectorQueue</address>
+ <filter string="color='red'"/>
+ <durable>true</durable>
+ </queue>
+</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>
+<security-setting match="globalqueues.europe.#">
+ <permission type="createDurableQueue" roles="admin"/>
+ <permission type="deleteDurableQueue" roles="admin"/>
+ <permission type="createTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="deleteTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="send" roles="admin, europe-users"/>
+ <permission type="consume" roles="admin, europe-users"/>
+</security-setting>
+ </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>
+<security-setting match="globalqueues.europe.orders.#">
+ <permission type="send" roles="europe-users"/>
+ <permission type="consume" roles="europe-users"/>
+</security-setting>
+ </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>
+<configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-users.xsd ">
+
+ <defaultuser name="guest" password="guest">
+ <role name="guest"/>
+ </defaultuser>
+
+ <user name="tim" password="marmite">
+ <role name="admin"/>
+ </user>
+
+ <user name="andy" password="doner_kebab">
+ <role name="admin"/>
+ <role name="guest"/>
+ </user>
+
+ <user name="jeff" password="camembert">
+ <role name="europe-users"/>
+ <role name="guest"/>
+ </user>
+
+</configuration>
+ </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>
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+</bean>
+ </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>
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.integration.security.JAASSecurityManager">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+
+ <property name="ConfigurationName">org.jboss.jms.example.ExampleLoginModule</property>
+ <property name="Configuration">
+ <inject bean="ExampleConfiguration"/>
+ </property>
+ <property name="CallbackHandler">
+ <inject bean="ExampleCallbackHandler"/>
+ </property>
+</bean>
+ </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 < 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>
+<connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+ </entries>
+ <use-global-pools>false</use-global-pools>
+ <scheduled-thread-pool-max-size>10</scheduled-thread-pool-max-size>
+ <thread-pool-max-size>-1</thread-pool-max-size>
+</connection-factory>
+ </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>
+ <!-- delay redelivery of messages for 5s -->
+ <address-setting match="jms.queue.exampleQueue">
+ <redelivery-delay>5000</redelivery-delay>
+ </address-setting>
+ </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>
+ <!-- undelivered messages in exampleQueue will be sent to the dead letter address deadLetterQueue
+ after 3 unsuccessful delivery attempts
+ -->
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ </address-setting>
+ </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>
+ <persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
+ </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>
+<configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-jms.xsd ">
+
+ <connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ </connection-factory>
+
+ <queue name="OrderQueue">
+ <entry name="queues/OrderQueue"/>
+ </queue>
+
+</configuration>
+ </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>
+<bean name="JNDIServer" class="org.jnp.server.Main">
+ <property name="namingInfo">
+ <inject bean="Naming"/>
+ </property>
+ <property name="port">1099</property>
+ <property name="bindAddress">localhost</property>
+ <property name="rmiPort">1098</property>
+ <property name="rmiBindAddress">localhost</property>
+</bean>
+ </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><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+<bean name="Naming" class="org.jnp.server.NamingBeanImpl"/>
+
+<!-- JNDI server. Disable this if you don't want JNDI -->
+<bean name="JNDIServer" class="org.jnp.server.Main">
+<property name="namingInfo">
+<inject bean="Naming"/>
+</property>
+<property name="port">1099</property>
+<property name="bindAddress">localhost</property>
+<property name="rmiPort">1098</property>
+<property name="rmiBindAddress">localhost</property>
+</bean>
+
+<!-- MBean server -->
+<bean name="MBeanServer" class="javax.management.MBeanServer">
+<constructor factoryClass="java.lang.management.ManagementFactory"
+factoryMethod="getPlatformMBeanServer"/>
+</bean>
+
+<!-- The core configuration -->
+<bean name="Configuration" class="org.jboss.messaging.core.config.impl.FileConfiguration">
+</bean>
+
+<!-- The security manager -->
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+<start ignored="true"/>
+<stop ignored="true"/>
+</bean>
+
+<!-- The core server -->
+<bean name="MessagingServer" class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
+<start ignored="true"/>
+<stop ignored="true"/>
+<constructor>
+<parameter>
+<inject bean="Configuration"/>
+</parameter>
+<parameter>
+<inject bean="MBeanServer"/>
+</parameter>
+<parameter>
+<inject bean="JBMSecurityManager"/>
+</parameter>
+</constructor>
+</bean>
+
+<!-- The JMS server -->
+<bean name="JMSServerManager"
+ class="org.jboss.messaging.jms.server.impl.JMSServerManagerImpl">
+<constructor>
+<parameter>
+<inject bean="MessagingServer"/>
+</parameter>
+</constructor>
+</bean>
+
+</deployment></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