activemq-artemis/docs/user-manual/en/diverts.xml

<?xml version="1.0" encoding="UTF-8"?>

<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES;
]>

<chapter id="diverts">
    <title>Diverting and Splitting Message Flows</title>
    <para>ActiveMQ 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 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 <emphasis>splitting</emphasis> 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 <literal>Transformer</literal>. If specified,
        all diverted messages will have the opportunity of being transformed by the <literal
            >Transformer</literal>.</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 forwards 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>activemq-configuration.xml</literal> file. There can
        be zero or more diverts in the file.</para>
    <para>Please see <xref linkend="divert-example" /> 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">
   &lt;address>jms.topic.priceUpdates&lt;/address>
   &lt;forwarding-address>jms.queue.priceForwarding&lt;/forwarding-address>
   &lt;filter string="office='New York'"/>
   &lt;transformer-class-name>
      org.apache.activemq.jms.example.AddForwardingTimeTransformer
   &lt;/transformer-class-name>
   &lt;exclusive>true&lt;/exclusive>
&lt;/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 messages 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 ActiveMQ
            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 to the old address</para>
        <para>You can therefore think of non-exclusive diverts as <emphasis>splitting</emphasis> a
            message flow.</para>
        <para>Non exclusive diverts can be configured in the same way 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">
    &lt;address>jms.queue.orders&lt;/address>
    &lt;forwarding-address>jms.topic.spyTopic&lt;/forwarding-address>
    &lt;exclusive>false&lt;/exclusive>
&lt;/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>