<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<html>
<head>
<title>ActiveMQ Artemis Divert Example</title>
<link rel="stylesheet" type="text/css" href="../../../common/common.css" />
<link rel="stylesheet" type="text/css" href="../../../common/prettify.css" />
<script type="text/javascript" src="../../../common/prettify.js"></script>
</head>
<body onload="prettyPrint()">
<h1>Divert Example</h1>
<pre>To run the example, simply type <b>mvn verify</b> from this directory, <br>or <b>mvn -PnoServer verify</b> if you want to start and create the server manually.</pre>
<p>ActiveMQ Artemis diverts allow messages to be transparently "diverted" from one address to another
with just some simple configuration defined on the server side.</p>
<p>Diverts can be defined to be <b>exclusive</b> or <b>non-exclusive</b>.</p>
<p>With an <b>exclusive</b> divert the message is intercepted and does not get sent to the queues originally
bound to that address - it only gets diverted.</p>
<p>With a <b>non-exclusive</b> divert the message continues to go to the queues bound to the address,
but also a <b>copy</b> of the message gets sent to the address specified in the divert. Consequently non-exclusive
diverts can be used to "snoop" on another address</p>
<p>Diverts can also be configured to have an optional filter. If specified then only matching messages
will be diverted.</p>
<p>Diverts can be configured to apply a Transformer. If specified, all diverted messages will have the
opportunity of being transformed by the Transformer.</p>
<p>Diverts are a very sophisticated concept, which when combined with bridges can be used to create
interesting and complex routings. The set of diverts can be thought of as a type of <i>routing table</i>
for messages.</p>
<h2>Example step-by-step</h2>
<p>In this example we will imagine a fictitious company which has two offices; one in London and another in New York.</p>
<p>The company accepts orders for it's products only at it's London office, and also generates price-updates
for it's products, also only from it's London office. However only the New York office is interested in receiving
price updates for New York products. Any prices for New York products need to be forwarded to the New York office.</p>
<p>There is an unreliable WAN linking the London and New York offices.</p>
<p>The company also requires a copy of any order received to be available to be inspected by management.</p>
<p>In order to achieve this, we will create a queue <code>orderQueue</code> on the London server in to which orders arrive.</p>
<p>We will create a topic, <code>spyTopic</code> on the London server, and there will be two subscribers both in London.</p>
<p>We will create a <i>non-exclusive</i> divert on the London server which will siphon off a copy of each order
received to the topic <code>spyTopic</code>.</p>
<p>Here's the xml config for that divert, from <code>broker.xml</code></p>
<pre class="prettyprint">
<code>
<divert name="order-divert">
<address>jms.queue.orders</address>
<forwarding-address>jms.topic.spyTopic</forwarding-address>
<exclusive>false</exclusive>
</divert>
</code>
</pre>
<p>For the prices we will create a topic on the London server, <code>priceUpdates</code> to which all price updates
are sent. We will create another topic on the New York server <code>newYorkPriceUpdates</code> to which all New York
price updates need to be forwarded.</p>
<p>Diverts can only be used to divert messages from one <b>local</b> address to another <b>local</b> address
so we cannot divert directly to an address on another server.</p>
<p>Instead we divert to a local <i>store and forward queue</i> they we define in the configuration. This is just a normal queue
that we use for storing messages before forwarding to another node.</p>
<p>Here's the configuration for it:</p>
<pre class="prettyprint">
<code>
<queues>
<queue name="jms.queue.priceForwarding">
<address>jms.queue.priceForwarding</address>
</queue>
</queues>
</code>
</pre>
<p>Here's the configuration for the divert:</p>
<pre class="prettyprint">
<code>
<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.artemis.jms.example.AddForwardingTimeTransformer</transformer-class-name>
<exclusive>true</exclusive>
</divert>
</code>
</pre>
<p>Note we specify a filter in the divert, so only New York prices get diverted. We also specify a Transformer class
since we are going to insert a header in the message at divert time, recording the time the diversion happened.</p>
<p>And finally we define a bridge that moves messages from the local queue to the address on the New York server.
Bridges move messages from queues to remote addresses and are ideal to use when the target server may be stopped and
started independently, and/or the network might be unreliable. Bridges guarantee once and only once delivery
of messages from their source queues to their target addresses.</p>
<p>Here is the bridge configuration: </p>
<pre class="prettyprint">
<code>
<bridges>
<bridge name="price-forward-bridge">
<queue-name>jms.queue.priceForwarding</queue-name>
<forwarding-address>jms.topic.newYorkPriceUpdates</forwarding-address>
<reconnect-attempts>-1</reconnect-attempts>
<static-connectors>
<connector-ref>newyork-connector</connector-ref>
</static-connectors>
</bridge>
</bridges>
</code>
</pre>
</body>
</html>
221039e353