<!--
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 Topic Hierarchy 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>Topic Hierarchy Example</h1>
<p>ActiveMQ Artemis supports topic hierarchies. With a topic hierarchy you can register a subscriber with a wild-card
and that subscriber will receive any messages routed to an address that match the wildcard.</p>
<p>ActiveMQ Artemis wild-cards can use the character '#' which means "match any number of words", and
the character '*' which means "match a single word". Words are delimited by the character "."</p>
<p>For example if I subscribe using the wild-card "news.europe.#", then that would match messages sent to the addresses
"news.europe", "news.europe.sport" and "news.europe.entertainment", but it does not match messages sent to the
address "news.usa.wrestling"</p>
<p>For more information on the wild-card syntax please consult the user manual.</p>
<h2>Example step-by-step</h2>
<p><i>To run the example, simply type <code>mvn verify -Pexample</code> from this directory</i></p>
<p>In this example we will define a hierarchy of topics in the file <code>activemq-jms.xml</code></p>
<pre class="prettyprint">
<code>
<topic name="news">
<entry name="/topic/news"/>
</topic>
<topic name="news.usa">
<entry name="/topic/news.usa"/>
</topic>
<topic name="news.usa.wrestling">
<entry name="/topic/news.wrestling"/>
</topic>
<topic name="news.europe">
<entry name="/topic/news.europe"/>
</topic>
<topic name="news.europe.sport">
<entry name="/topic/news.europe.sport"/>
</topic>
<topic name="news.europe.entertainment">
<entry name="/topic/news.europe.entertainment"/>
</topic>
</code>
</pre>
<p>Then we will create a subscriber using the wildcard "news.europe.#".</p>
<p>We will then send three messages: one to the address news.usa.wrestling, one to the address news.europe.sport,
and one to the address news.europe.entertainment.</p>
<p>We will verify that the message sent to news.usa.wrestling does not get received since it does not match,
but the messages sent to the other two addresses do get received since they match.</p>
<ol>
<li>Create an initial context to perform the JNDI lookup.</code></li>
<pre class="prettyprint">
<code>initialContext = getContext(0);</code>
</pre>
<li>Perform a lookup on the Connection Factory</li>
<pre class="prettyprint">
<code>ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");</code>
</pre>
<li>Create a JMS Connection</li>
<pre class="prettyprint">
<code>connection = cf.createConnection();</code>
</pre>
<li>Create a JMS Session</li>
<pre class="prettyprint">
<code>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</code>
</pre>
<li>Instantiate a topic representing the wildcard we're going to subscribe to.</li>
<pre class="prettyprint">
<code>Topic topicSubscribe = ActiveMQJMSClient.createActiveMQTopic("news.europe.#");</code>
</pre>
<li>Create a consumer (topic subscriber) that will consume using that wildcard.
The consumer will receive any messages sent to any topic that starts with news.europe</li>
<pre class="prettyprint">
<code>MessageConsumer messageConsumer = session.createConsumer(topicSubscribe);</code>
</pre>
<li>Create an anonymous producer. The sending address is specified at send time.</li>
<pre class="prettyprint">
<code>MessageProducer producer = session.createProducer(null);</code>
</pre>
<li>Instantiate some more topic objects corresponding to the individual topics
we're going to send messages to. You could look these up from JNDI if you wanted to.</li>
<pre class="prettyprint">
<code>
Topic topicNewsUsaWrestling = ActiveMQJMSClient.createActiveMQTopic("news.usa.wrestling");
Topic topicNewsEuropeSport = ActiveMQJMSClient.createActiveMQTopic("news.europe.sport");
Topic topicNewsEuropeEntertainment = ActiveMQJMSClient.createActiveMQTopic("news.europe.entertainment");</code>
</pre>
<li>Send a message destined for the usa wrestling topic.</li>
<pre class="prettyprint">
<code>
TextMessage messageWrestlingNews = session.createTextMessage("Hulk Hogan starts ballet classes");
producer.send(topicNewsUsaWrestling, messageWrestlingNews);
</code>
</pre>
<li>Send a message destined for the europe sport topic.</li>
<pre class="prettyprint">
<code>
TextMessage messageEuropeSport = session.createTextMessage("Lewis Hamilton joins European synchronized swimming team");
producer.send(topicNewsEuropeSport, messageEuropeSport);
</code>
</pre>
<li>Send a message destined for the europe entertainment topic</li>
<pre class="prettyprint">
<code>
TextMessage messageEuropeEntertainment = session.createTextMessage("John Lennon resurrected from dead");
producer.send(topicNewsEuropeEntertainment, messageEuropeEntertainment);
</code>
</pre>
<li>Start the connection</li>
<pre class="prettyprint">
<code>
connection.start();
</code>
</pre>
<li>We don't receive the usa wrestling message since we subscribed to news.europe.# and
that doesn't match news.usa.wrestling. However we do receive the Europe sport message, and the
europe entertainment message, since these match the wildcard.</li>
<pre class="prettyprint">
<code>
TextMessage messageReceived1 = (TextMessage)messageConsumer.receive(5000);
System.out.println("Received message: " + messageReceived1.getText());
TextMessage messageReceived2 = (TextMessage)messageConsumer.receive(5000);
System.out.println("Received message: " + messageReceived2.getText());
Message message = messageConsumer.receive(1000);
if (message != null)
{
return false;
}
System.out.println("Didn't received any more message: " + message);
</code>
</pre>
<li>Be sure to close our resources!</li>
<pre class="prettyprint">
<code>finally
{
if (initialContext != null)
{
initialContext.close();
}
if (connection != null)
{
connection.close();
}
}</code>
</pre>
</ol>
</body>
</html>
73c5f2e342