<!--
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 MQTT 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>MQTT Example</h1>
<p>This is a basic MQTT example that demonstrates how to setup and connect to an Apache Artemis broker and
send and receive messages using the MQTT protocol.</p>
<h2>Setting up the server</h2>
<p>This example will use the default out of the box configuration of Artemis you don't need to change anything to run
this example. Artemis ships with all protocols enabled on port 61616 and also MQTT on port 1883. To enable MQTT
on a different port you can add the following XML snippet to the 'acceptors' section of your broker.xml
configuration file (changing the port from 1883 to what ever you require).</p>
<pre class="prettyprint">
<!-- Escaped: <acceptor name="hornetq">tcp://0.0.0.0:1883?protocols=MQTT"></acceptor> -->
<acceptor name="hornetq">tcp://0.0.0.0:1883?protocols=MQTT"></acceptor>
</pre>
For more information on configuring protocol transports see the "Configuring Transports" section of the user
manual, specifically the section called "Single Port Support".
<h2>MQTT Clients</h2>
<p>There are a number of MQTT client implementations for various languages. The Paho project:
http://www.eclipse.org/paho/ offers a number of clients for languages such as C, Python, JavaScript and .Net and
is also a great resource for all things MQTT.
This example is actually based on the Fuse MQTT java client and was chosen as it is Apache 2.0 licensed and
available to download from maven central. The specific client used in the example is not of importance and is
used simply to demonstrate the features of MQTT as provided by Apache Artemis.</p>
<p>If you'd like to use the client demonstrated in this example, simple add the following dependency to your
pom.xml</p>
<pre class="prettyprint">
<dependency>
<groupId>org.fusesource.mqtt-client</groupId>
<artifactId>mqtt-client</artifactId>
<version>1.10</version>
</dependency>
</pre>
<h2>Example Step by Step</h2>
<o1>
<li>1. Connect to Artemis</li>
<p>We start by creating a connection to the Apache Artemis broker. In this example we specify to use TCP
protocol on localhost. By default Apache Artemis will start all protocols on port 61616, so we connect
to that port.</p>
<pre class="prettyprint">
MQTT mqtt = new MQTT();
mqtt.setHost("tcp://localhost:61616");
BlockingConnection connection = mqtt.blockingConnection();
connection.connect();
</pre>
<li>2. Create subscriptions</li>
<p>Subscriptions in MQTT are realised by subscribing to a particular Topic. Each Topic has an address
and a quality of service level (QoS level). Subscriptions also support wildcards. In the code below we
subscribe to a Topic with address "mqtt/example/publish", a wildcard address "test/#" which will
match anything starting with "test/" and also a wildcard "foo/+/bar", where + matches a single level of the hierarchy (foo/something/bar)</p>
<pre class="prettyprint">
Topic[] topics = { new Topic("mqtt/example/publish", QoS.AT_LEAST_ONCE), new Topic("test/#", QoS.EXACTLY_ONCE), new Topic("foo/+/bar", QoS.AT_LEAST_ONCE) };
connection.subscribe(topics);
</pre>
<li>3. Sending messages</li>
<p>There is no type system in MQTT, messages simply consist of a number of bytes. Below we send three messages with
UTF8 encoded strings (as a byte array). Notice the second message is sent to "test/test" which should match
the first wildcard subscription we defined previously. The third message is sent to "foo/1/bar", which matches the second wildcard subscription.</p>
<pre class="prettyprint">
String payload1 = "This is message 1";
String payload2 = "This is message 2";
String payload3 = "This is message 3";
connection.publish("mqtt/example/publish", payload1.getBytes(), QoS.AT_LEAST_ONCE, false);
connection.publish("mqtt/test", payload2.getBytes(), QoS.AT_MOST_ONCE, false);
connection.publish("foo/1/bar", payload3.getBytes(), QoS.AT_MOST_ONCE, false);
</pre>
<li>4. Receiving messages</li>
<p>Since we have subscribed to a number of topics and sent messages to them, the client should now receive
2 messages. We are not using callbacks here on message receive so we specifically call receive to get
the messages. Once we receive the message we convert the payload consisting of bytes back to a UTF8
encoded string and print the result.</p>
<pre class="prettyprint">
Message message1 = connection.receive(5, TimeUnit.SECONDS);
Message message2 = connection.receive(5, TimeUnit.SECONDS);
Message message3 = connection.receive(5, TimeUnit.SECONDS);
System.out.println(new String(message1.getPayload()));
System.out.println(new String(message2.getPayload()));
System.out.println(new String(message3.getPayload()));
</pre>
</o1>
<h2>Result</h2>
This example has shown you how to set up the basics of MQTT including how to connect to the Artemis broker and
how to send and receive messages including subscriptions using wildcard addresses.
</body>
</html>
8703d9d51d