115 lines
7.9 KiB
XML
115 lines
7.9 KiB
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>
|
||
<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.apache.activemq.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 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>
|
||
<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>
|