[jboss-cvs] JBoss Messaging SVN: r6794 - in trunk: docs/user-manual/en/modules and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu May 14 10:22:42 EDT 2009
Author: timfox
Date: 2009-05-14 10:22:42 -0400 (Thu, 14 May 2009)
New Revision: 6794
Modified:
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/modules/core-bridges.xml
trunk/docs/user-manual/en/modules/duplicate-detection.xml
trunk/src/main/org/jboss/messaging/core/config/impl/ConfigurationImpl.java
trunk/src/main/org/jboss/messaging/core/config/impl/FileConfiguration.java
Log:
bridge chapter
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-14 14:05:03 UTC (rev 6793)
+++ trunk/docs/user-manual/en/master.xml 2009-05-14 14:22:42 UTC (rev 6794)
@@ -20,6 +20,7 @@
<!ENTITY diverts SYSTEM "modules/diverts.xml">
<!ENTITY logging SYSTEM "modules/logging.xml">
<!ENTITY scheduled-messages SYSTEM "modules/scheduled-messages.xml">
+ <!ENTITY filter-expressions SYSTEM "modules/filter-expressions.xml">
<!ENTITY flow-control SYSTEM "modules/flow-control.xml">
<!ENTITY undelivered-messages SYSTEM "modules/undelivered-messages.xml">
<!ENTITY message-expiry SYSTEM "modules/message-expiry.xml">
@@ -69,6 +70,7 @@
&diverts;
&logging;
&scheduled-messages;
+ &filter-expressions;
&flow-control;
&undelivered-messages;
&message-expiry;
Modified: trunk/docs/user-manual/en/modules/core-bridges.xml
===================================================================
--- trunk/docs/user-manual/en/modules/core-bridges.xml 2009-05-14 14:05:03 UTC (rev 6793)
+++ trunk/docs/user-manual/en/modules/core-bridges.xml 2009-05-14 14:22:42 UTC (rev 6794)
@@ -1,6 +1,182 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="core-bridges">
<title>Core Bridges</title>
- <para>blah</para>
-
+ <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>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>
Modified: trunk/docs/user-manual/en/modules/duplicate-detection.xml
===================================================================
--- trunk/docs/user-manual/en/modules/duplicate-detection.xml 2009-05-14 14:05:03 UTC (rev 6793)
+++ trunk/docs/user-manual/en/modules/duplicate-detection.xml 2009-05-14 14:22:42 UTC (rev 6794)
@@ -32,8 +32,14 @@
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 receieved a message
+ 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
@@ -41,9 +47,10 @@
<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>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>
...
Modified: trunk/src/main/org/jboss/messaging/core/config/impl/ConfigurationImpl.java
===================================================================
--- trunk/src/main/org/jboss/messaging/core/config/impl/ConfigurationImpl.java 2009-05-14 14:05:03 UTC (rev 6793)
+++ trunk/src/main/org/jboss/messaging/core/config/impl/ConfigurationImpl.java 2009-05-14 14:22:42 UTC (rev 6794)
@@ -140,6 +140,8 @@
public static final boolean DEFAULT_DIVERT_EXCLUSIVE = false;
public static final boolean DEFAULT_BRIDGE_DUPLICATE_DETECTION = true;
+
+ public static final int DEFAULT_BRIDGE_RECONNECT_ATTEMPTS = -1;
// Attributes -----------------------------------------------------------------------------
Modified: trunk/src/main/org/jboss/messaging/core/config/impl/FileConfiguration.java
===================================================================
--- trunk/src/main/org/jboss/messaging/core/config/impl/FileConfiguration.java 2009-05-14 14:05:03 UTC (rev 6793)
+++ trunk/src/main/org/jboss/messaging/core/config/impl/FileConfiguration.java 2009-05-14 14:22:42 UTC (rev 6794)
@@ -665,7 +665,7 @@
double retryIntervalMultiplier = DEFAULT_RETRY_INTERVAL_MULTIPLIER;
- int reconnectAttempts = ClientSessionFactoryImpl.DEFAULT_RECONNECT_ATTEMPTS;
+ int reconnectAttempts = ConfigurationImpl.DEFAULT_BRIDGE_RECONNECT_ATTEMPTS;
boolean failoverOnServerShutdown = ClientSessionFactoryImpl.DEFAULT_FAILOVER_ON_SERVER_SHUTDOWN;
More information about the jboss-cvs-commits
mailing list