[jboss-cvs] JBoss Messaging SVN: r6761 - trunk/docs/user-manual/en/modules.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Wed May 13 05:31:58 EDT 2009 

Author: timfox
Date: 2009-05-13 05:31:58 -0400 (Wed, 13 May 2009)
New Revision: 6761

Modified:
   trunk/docs/user-manual/en/modules/diverts.xml
Log:
diverts

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

More information about the jboss-cvs-commits mailing list