<!--
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 Core Bridge 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>Core Bridge Example</h1>
<p>This example demonstrates a core bridge deployed on one server, which consumes messages from a
local queue and forwards them to an address on a second server.</p>
<p>Core bridges are used to create message flows between any two ActiveMQ Artemis servers which are remotely separated.
Core bridges are resilient and will cope with temporary connection failure allowing them to be an ideal
choice for forwarding over unreliable connections, e.g. a WAN.</p>
<p>They can also be configured with an optional filter expression, and will only forward messages that
match that filter.</p>
<p>Furthermore they can be configured to use an optional Transformer class. A user-defined Transformer class
can be specified which is called at forwarding time. This gives the user the opportunity to transform
the message in some ways, e.g. changing its properties or body</p>
<p>ActiveMQ Artemis also includes a <b>JMS Bridge</b>. This is similar to a core bridge, but uses the JMS API
and can be used to bridge between any two JMS 1.1 compliant messaging systems. The core bridge is limited to bridging
between ActiveMQ Artemis instances, but may provide better performance than the JMS bridge. The JMS bridge is covered in
a separate example.</p>
<p>For more information on bridges, please see the ActiveMQ Artemis user manual.</p>
<p>In this example we will demonstrate a simple sausage factory for aardvarks.</p>
<p>We have a JMS queue on server 0 named <code>sausage-factory</code>, and we have a
JMS queue on server 1 named <code>mincing-machine</code></p>
<p>We want to forward any messages that are sent to the <code>sausage-factory</code> queue on server 0, to the <code>mincing-machine</code>
on server 1.</p>
<p>We only want to make aardvark sausages, so we only forward messages where the property "name" is set
to "aardvark". It is known that other things, such are Sasquatches are also sent to the <code>sausage-factory</code> and we
want to reject those.</p>
<p>Moreover it is known that Aardvarks normally wear blue hats, and it's important that we only make sausages using
Aardvarks with green hats, so on the way we are going transform the property "hat" from "green" to "blue".</p>
<p>Here's a snippet from <code>broker.xml</code> showing the bridge configuration</p>
<pre class="prettyprint">
<code>
<bridge name="my-bridge">
<queue-name>jms.queue.sausage-factory</queue-name>
<forwarding-address>jms.queue.mincing-machine</forwarding-address>
<filter string="name='aardvark'"/>
<transformer-class-name>org.apache.activemq.artemis.jms.example.HatColourChangeTransformer</transformer-class-name>
<reconnect-attempts>-1</reconnect-attempts>
<static-connectors>
<connector-ref>remote-connector</connector-ref>
</static-connectors>
</bridge>
</code>
</pre>
<h2>Example step-by-step</h2>
<p><i>To run the example, simply type <code>mvn verify -Pexample</code> from this directory</i></p>
<ol>
<li>We create an initial context for looking up JNDI on node 0</li>
<pre class="prettyprint">
<code>
ic0 = getContext(0);
</code>
</pre>
<li>We look up the sausage-factory queue from node 0</li>
<pre class="prettyprint">
<code>Queue sausageFactory = (Queue)ic0.lookup("/queue/sausage-factory");</code>
</pre>
<li>We look up a JMS ConnectionFactory object from node 0</li>
<pre class="prettyprint">
<code>ConnectionFactory cf0 = (ConnectionFactory)ic0.lookup("/ConnectionFactory");</code>
</pre>
<li>We create an initial context for looking up JNDI on node 1</li>
<pre class="prettyprint">
<code>ic1 = getContext(1);</code>
</pre>
<li>We look up the mincing-machine queue on node 1</li>
<pre class="prettyprint">
<code>Queue mincingMachine = (Queue)ic1.lookup("/queue/mincing-machine");
</code>
</pre>
<li>We look up a JMS ConnectionFactory object from node 1</li>
<pre class="prettyprint">
<code>
ConnectionFactory cf1 = (ConnectionFactory)ic1.lookup("/ConnectionFactory");
</code>
</pre>
<li>We create a JMS Connection connection0 which is a connection to server 0</li>
<pre class="prettyprint">
<code>
connection0 = cf0.createConnection();
</code>
</pre>
<li>We create a JMS Connection connection1 which is a connection to server 1</li>
<pre class="prettyprint">
<code>
connection1 = cf1.createConnection();
</code>
</pre>
<li>We create a JMS Session on server 0</li>
<pre class="prettyprint">
<code>
Session session0 = connection0.createSession(false, Session.AUTO_ACKNOWLEDGE);
</code>
</pre>
<li>We create a JMS Session on server 1</li>
<pre class="prettyprint">
<code>
Session session1 = connection1.createSession(false, Session.AUTO_ACKNOWLEDGE);
</code>
</pre>
<li>We start the connection to ensure delivery occurs on them</li>
<pre class="prettyprint">
<code>
connection1.start();
</code>
</pre>
<li>We create a JMS MessageConsumer object on server 1</li>
<pre class="prettyprint">
<code>
MessageConsumer consumer = session1.createConsumer(mincingMachine);
</code>
</pre>
<li>We create a JMS MessageProducer object on server 0.</li>
<pre class="prettyprint">
<code>
MessageProducer producer = session0.createProducer(sausageFactory);</code>
</pre>
<li>We create and send a message representing an aardvark with a green hat to the sausage-factory
on node 0</li>
<pre class="prettyprint">
<code>
Message message = session0.createMessage();
message.setStringProperty("name", "aardvark");
message.setStringProperty("hat", "green");
producer.send(message);
</code>
</pre>
<li>We successfully receive the aardvark message from the mincing-machine one node 1. The aardvark's
hat is now blue since it has been transformed!</li>
<pre class="prettyprint">
<code>
Message receivedMessage = consumer.receive(5000);
</code>
</pre>
<li>We create and send another message, this time representing a sasquatch with a mauve hat to the
sausage-factory on node 0. This won't be bridged to the mincing-machine since we only want aardvarks, not sasquatches.</li>
<pre class="prettyprint">
<code>
message = session0.createMessage();
message.setStringProperty("name", "sasquatch");
message.setStringProperty("hat", "mauve");
producer.send(message);
</code>
</pre>
<li>We don't receive the sasquatch message since it's not an aardvark!</li>
<pre class="prettyprint">
<code>
receivedMessage = (TextMessage)consumer.receive(1000);
</code>
</pre>
<li>And finally (no pun intended), <b>always</b> remember to close your JMS resources after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>
<pre class="prettyprint">
<code>
finally
{
if (connection0 != null)
{
connection0.close();
}
if (connection1 != null)
{
connection1.close();
}
if (ic0 != null)
{
ic0.close();
}
if (ic1 != null)
{
ic1.close();
}
}
</code>
</pre>
</ol>
</body>
</html>
d48b4f4770