120 lines
6.8 KiB
HTML
120 lines
6.8 KiB
HTML
<!--
|
|
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>
|