[jboss-cvs] JBoss Messaging SVN: r7017 - trunk/docs/user-manual/en.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 26 08:40:30 EDT 2009
Author: jmesnil
Date: 2009-05-26 08:40:30 -0400 (Tue, 26 May 2009)
New Revision: 7017
Modified:
trunk/docs/user-manual/en/appserver-integration.xml
Log:
user manual
* updated JMS Bridge section by describing the bridge parameters
(copied from JBM 1.4 doc)
Modified: trunk/docs/user-manual/en/appserver-integration.xml
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml 2009-05-26 11:47:37 UTC (rev 7016)
+++ trunk/docs/user-manual/en/appserver-integration.xml 2009-05-26 12:40:30 UTC (rev 7017)
@@ -441,11 +441,6 @@
<para>A bridge is deployed inside a JBoss AS instance. The instance can be the same instance
as either the source or target server. Or could be on a third, separate JBoss AS
instance.</para>
- <para>A bridge is deployed as an MBean inside JBoss AS. Deployment is trivial - just drop
- the MBean descriptor into the deploy directory of a JBoss configuration which contains
- JBoss Messaging.</para>
- <para>An example in docs/example/bridge demonstrates a simple bridge being deployed in JBoss
- AS, and moving messages from the source to the target destination</para>
<para>The bridge can also be used to bridge messages from other non JBoss Messaging JMS
servers, as long as they are JMS 1.1 compliant.<note>
<para>Don't confuse a JMS bridge with a core bridge. A JMS bridge can be used to
@@ -456,7 +451,7 @@
performance than a JMS bridge. Also the core bridge can provide <emphasis>once
and only once</emphasis> delivery guarantees without using XA.</para>
</note></para>
- <para>The bridge has built in resilience to failure so if the source or target server
+ <para>The bridge has built-in resilience to failure so if the source or target server
connection is lost, e.g. due to network failure, the bridge will retry connecting to the
source and/or target until they come back online. When it comes back online it will
resume operation as normal.</para>
@@ -466,8 +461,8 @@
it can be configured to consume using a non durable or durable subscription</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>
+ example shows an example of a beans file that bridges 2 destinations which are actually
+ on the same server. </para>
<programlisting><?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
@@ -492,31 +487,31 @@
<parameter>
<inject bean="TargetDestinationFactory"/>
</parameter>
- <!-- Source username (no username here) -->
+ <!-- Source User Name (no username here) -->
<parameter><null /></parameter>
- <!-- Source password (no password here)-->
+ <!-- Source Password (no password here)-->
<parameter><null /></parameter>
- <!-- Target username (no username here)-->
+ <!-- Target User Name (no username here)-->
<parameter><null /></parameter>
- <!-- Target password (no password here)-->
+ <!-- Target Password (no password here)-->
<parameter><null /></parameter>
<!-- Selector -->
<parameter><null /></parameter>
- <!-- Interval to retry in case of failure (in ms) -->
+ <!-- Failure Retry Interval (in ms) -->
<parameter>5000</parameter>
- <!-- Maximum number of retries to connect to the source and target -->
+ <!-- Max Retries -->
<parameter>10</parameter>
- <!-- Quality of service -->
+ <!-- Quality Of Service -->
<parameter>ONCE_AND_ONLY_ONCE</parameter>
- <!-- Maximum batch size -->
+ <!-- Max Batch Size -->
<parameter>1</parameter>
- <!-- Maximum batch time (-1 means infinite) -->
+ <!-- Max Batch Time (-1 means infinite) -->
<parameter>-1</parameter>
<!-- Subscription name (no subscription name here)-->
<parameter><null /></parameter>
- <!-- client ID (no client ID here)-->
+ <!-- Client ID (no client ID here)-->
<parameter><null /></parameter>
- <!-- concatenate JMS messageID to the target's message header -->
+ <!-- Add MessageID In Header -->
<parameter>true</parameter>
</constructor>
<property name="transactionManager">
@@ -593,123 +588,174 @@
</bean>
</deployment></programlisting>
- <para>TODO TODO - please copy the documentation on these parameters from the JBM 1.4 docs</para>
- <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 milliseconds).</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>JMS Bridge Parameters</title>
+ <para>The main bean deployed is the <literal>JMSBridge</literal> bean. The bean is configurable
+ by the parameters passed to its constructor.</para>
+ <note>
+ <para>To let a parameter be unspecified (for example, if the authentication is anonymous or no message selector
+ is provided), use <literal><null /></literal> for the unspecified parameter value.</para>
+ </note>
+ <itemizedlist>
+ <listitem>
+ <para>Source Connection Factory Factory</para>
+ <para>This injects the <literal>SourceCFF</literal> bean (also defined in the beans
+ file). This bean is used to create the <emphasis>source</emphasis> <literal>ConnectionFactory</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Target Connection Factory Factory</para>
+ <para>This injects the <literal>TargetCFF</literal> bean (also defined in the beans
+ file). This bean is used to create the <emphasis>target</emphasis> <literal>ConnectionFactory</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Source Destination Factory Factory</para>
+ <para>This injects the <literal>SourceDestinationFactory</literal> bean (also defined in the beans
+ file). This bean is used to create the <emphasis>source</emphasis> <literal>Destination</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Target Destination Factory Factory</para>
+ <para>This injects the <literal>TargetDestinationFactory</literal> bean (also defined in the beans
+ file). This bean is used to create the <emphasis>target</emphasis> <literal>Destination</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Source User Name</para>
+ <para>this parameter is the username for creating the <emphasis>source</emphasis> connection</para>
+ </listitem>
+ <listitem>
+ <para>Source Password</para>
+ <para>this parameter is the parameter for creating the <emphasis>source</emphasis> connection</para>
+ </listitem>
+ <listitem>
+ <para>Target User Name</para>
+ <para>this parameter is the username for creating the <emphasis>target</emphasis> connection</para>
+ </listitem>
+ <listitem>
+ <para>Target Password</para>
+ <para>this parameter is the password for creating the <emphasis>target</emphasis> connection</para>
+ </listitem>
+ <listitem>
+ <para>Selector</para>
+ <para>This represents a JMS selector expression used for consuming messages
+ from the source destination. Only messages that match the selector expression will be
+ bridged from the source to the target destination</para>
+ <para>
+ <note>Ut is always more efficient to apply selectors on source topic subscriptions to source
+ queue consumers</note>
+ </para>
+ <para>The selector expression must follow the
+ <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/jms/Message.html">JMS selector syntax</ulink></para>
+ </listitem>
+ <listitem>
+ <para>Failure Retry Interval</para>
+ <para>This represents the amount of time in ms to wait between trying to recreate connections
+ to the source or target servers when the bridge has detected they have failed</para>
+ </listitem>
+ <listitem>
+ <para>Max Retries</para>
+ <para>This represents the number of times to attempt to recreate connections to the source
+ or target servers when the bridge has detected they have failed. The bridge will give up
+ after trying this number of times. <literal>-1</literal> represents 'try forever'</para>
+ </listitem>
+ <listitem>
+ <para>Quality Of Service</para>
+ <para>This parameter represents the desired quality of service mode</para>
+ <para>Possible values are:</para>
+ <itemizedlist>
+ <listitem><para><literal>AT_MOST_ONCE</literal></para></listitem>
+ <listitem><para><literal>DUPLICATES_OK</literal></para></listitem>
+ <listitem><para><literal>ONCE_AND_ONLY_ONCE</literal></para></listitem>
+ </itemizedlist>
+ <para>See <xref linkend="quality-of-service" /> for a explanation of these modes.</para>
+ </listitem>
+ <listitem>
+ <para>Max Batch Size</para>
+ <para>This represents the maximum number of messages to consume from the source
+ destination before sending them in a batch to the target destination.
+ Its value must <literal>>= 1</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Max Batch Time</para>
+ <para>This represents the maximum number of milliseconds to wait before sending
+ a batch to target, even if the number of messages consumed has not reached
+ <literal>MaxBatchSize</literal>. Its value must be <literal>-1</literal> to represent
+ 'wait forever', or <literal>>= 1</literal> to specify an actual time
+ </para>
+ </listitem>
+ <listitem>
+ <para>Subscription Name</para>
+ <para>If the source destination represents a topic, and you want to consume from the topic
+ using a durable subscription then this parameter represents the durable subscription name</para>
+ </listitem>
+ <listitem>
+ <para>Client ID</para>
+ <para>If the source destination represents a topic, and you want to consume from the topic
+ using a durable subscription then this attribute represents the the JMS client ID to use
+ when creating/looking up the durable subscription</para>
+ </listitem>
+ <listitem>
+ <para>Add MessageID In Header</para>
+ <para>If <literal>true</literal>, then the original message's message ID will be appended in the message sent
+ to the destination in the header <literal>JBM_BRIDGE_MSG_ID_LIST</literal>. If the message is bridged more
+ than once, each message ID will be appended. This enables a distributed request-response pattern to be used</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>
+ <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
+ <para>The configuration example above uses the default implementation provided by JBoss Messaging
+ that looks 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
- provide a new implementation simple implement <literal
+ <para>Again, similarly, these are used to create or lookup up the destinations.</para>
+ <para>In the configuration example above, we have used the default provided by JBoss Messaging that looks up the
+ destination using JNDI.</para>
+ <para>A new
+ implementation can be provided by implementing <literal
>org.jboss.messaging.jms.bridge.DestinationFactory</literal> interface.</para>
</section>
- <section>
+ <section id="quality-of-service">
<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>
+ <title>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
+ could be lost. Hence delivery will occur at most once.</para>
+ <para>This mode is available
for both persistent and non persistent messages.</para>
</section>
<section>
- <title>QOS_DUPLICATES_OK</title>
+ <title>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>
+ system recovers. I.e. the destination might receive duplicates after a failure.</para>
+ <para>This mode is available for both persistent and non persistent messages.</para>
</section>
<section>
- <title>QOS_ONCE_AND_ONLY_ONCE</title>
+ <title>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
@@ -719,19 +765,19 @@
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>
+ need to be XAConnectionFactory implementations. This is likely to be the slowest
+ mode since it requires extra persistence for the transaction logging.</para>
+ <para>This mode is only available for persistent messages.</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
+ semantics without using the ONCE_AND_ONLY_ONCE QoS level. This can be
+ done by using the 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
+ watertight as using ONCE_AND_ONLY_ONCE but may be a good choice
depending on your specific application.</para>
</note>
</section>
More information about the jboss-cvs-commits
mailing list