| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> |
| <!-- |
| 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. |
| Architecture |
| --> |
| <html lang="en"> |
| <head> |
| <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/> |
| <meta content="ActiveMQ's next generation of messaging" name="description"/> |
| <meta content="messaging,stomp,jms,activemq,apollo" name="keywords"/> |
| <meta content="Apollo" name="author"/> |
| <script src="../scripts/jquery.js"></script> |
| <link type="text/css" rel="stylesheet" href="../styles/impact/css/pygmentize.css"/> |
| <link type="text/css" rel="stylesheet" href="../styles/impact/css/site.css"/> |
| <title></title> |
| </head> |
| <body> |
| <div id="navigation"> |
| <div class="wrapper"> |
| <ul> |
| <li><a href="../index.html">Apollo 1.7.1</a></li> |
| <li><a href="../community/developers.html">Developers</a></li> |
| <li><a href="../community/index.html">Community</a></li> |
| <li><a href="../download.html">Download</a></li> |
| </ul> <div></div> |
| </div> |
| </div> |
| <div id="content"> |
| <div class="wrapper"> |
| <h1 id = "Apollo_1_7_1_MQTT_Protocol_Manual">Apollo 1.7.1 MQTT Protocol Manual</h1> |
| |
| <p><div class="toc"><ul style="list-style:none;"> |
| <li><a href="#The_MQTT_Protocol">The MQTT Protocol</a></li> |
| <li><ul style="list-style:none;"> |
| <li><a href="#MQTT_Protocol_Options">MQTT Protocol Options</a></li> |
| <li><a href="#Client_Libraries">Client Libraries</a></li> |
| <li><a href="#Connecting">Connecting</a></li> |
| <li><a href="#Destination_Types">Destination Types</a></li> |
| <li><a href="#Clean_Sessions">Clean Sessions</a></li> |
| <li><a href="#Topic_Retained_Messages">Topic Retained Messages</a></li> |
| <li><a href="#Last_Will_and_Testament_Message">Last Will and Testament Message</a></li> |
| <li><a href="#Reliable_Messaging">Reliable Messaging</a></li> |
| <li><ul style="list-style:none;"> |
| <li><a href="#At_Most_Once">At Most Once</a></li> |
| <li><a href="#At_Least_Once">At Least Once</a></li> |
| <li><a href="#Exactly_Once">Exactly Once</a></li> |
| </ul></li> |
| <li><a href="#Wildcard_Subscriptions">Wildcard Subscriptions</a></li> |
| <li><a href="#Keep_Alive">Keep Alive</a></li> |
| <li><a href="#Destination_Name_Restrictions">Destination Name Restrictions</a></li> |
| </ul></li> |
| </ul></div></p> |
| |
| <h2 id = "The_MQTT_Protocol">The MQTT Protocol</h2> |
| |
| <p>Apollo allows clients to connect using the MQTT which is an open-source protocol specification |
| intended for limited-resource devices on unreliable networks using a publish-subscribe domain. |
| These types of devices usually require a small footprint and are not well suited for text-based protocols such as |
| HTTP or STOMP or even traditional binary protocols such as Openwire or AMQP. MQTT is a compact binary protocol that |
| is optimized for these types of limited devices and unreliable networks.</p> |
| |
| <p>In previous releases, MQTT was supported in Apollo as a separate plugin. As of now, that plugin has become part |
| of the main development trunk and MQTT support is available out of the box without any other configuration or |
| packaging of third-party plugins.</p> |
| |
| <p>Since MQTT is a wire-level protocol, any client that implements the protocol should be able to connect to Apollo |
| and also interoperate with other MQTT-compatibe message brokers.</p> |
| |
| <p>To learn more about the details of MQTT, see <a href="http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html">the MQTT Specification</a></p> |
| |
| <h3 id = "MQTT_Protocol_Options">MQTT Protocol Options</h3> |
| |
| <p>To start using the MQTT protocol, use a valid MQTT v3.1 client and connect to the port on which Apollo is listening. |
| Apollo will do protocol detection and will automatically recognize the MQTT payloads and treat the connection |
| as an MQTT connection. You don't have to open a special port for MQTT (or STOMP, Openwire, AMQP, etc. they can |
| all be auto-detected). To force specific protocols over a certain connector there are two ways you can do this. |
| You can choose to not use protocol detection at all and set the connector to be specifically for mqtt:</p> |
| |
| <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> |
| <connector id="tcp" bind="tcp://0.0.0.0:61613" protocol="mqtt"/> |
| </code></pre></div> |
| |
| <p>Alternatively, you can limit which protocols can be “detected” using the <code><detect></code> configuration element like this:</p> |
| |
| <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> |
| <connector id="tcp" bind="tcp://0.0.0.0:61613"> |
| <detect protocols="mqtt openwire" /> |
| </connector> |
| </code></pre></div> |
| |
| <p>The <code>protocols</code> attribute in the <code><detect></code> element takes space delimited protoco values. |
| The <code>protocol</code> attribtue of the <code><connector></code> element takes a single protocol, not space delimited. It defaults to |
| <code>any</code></p> |
| |
| <p>If you wish to tune the MQTT defaults, you can use the <code>mqtt</code> configuration element within the <code>connector</code> element |
| in the <code>apollo.xml</code> configuration file :</p> |
| |
| <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> |
| <connector id="tcp" bind="tcp://0.0.0.0:61613"> |
| <mqtt max_message_length="1000" /> |
| </connector> |
| </code></pre></div> |
| |
| <p>The <code>mqtt</code> element supports the following configuration attributes:</p> |
| |
| <ul> |
| <li><code>max_message_length</code> : The size (in bytes) of the largest message that can be sent to the broker. Defaults to 100MB</li> |
| <li><code>protocol_filters</code> : A filter which can filter frames being sent/received to and from a client. It can modify the frame or even drop it.</li> |
| <li><code>die_delay</code> : How long after a connection is deemed to be “dead” before the connection actually closes; default: 5000ms</li> |
| </ul> |
| |
| <p>The mqtt configuration element can also be used to control how the destination |
| headers are parsed and interpreted. The supported attributes are:</p> |
| |
| <ul> |
| <li><code>queue_prefix</code> : a tag used to identify destination types; default: null</li> |
| <li><code>path_separator</code> : used to separate segments in a destination name; default: <code>/</code></li> |
| <li><code>any_child_wildcard</code> : indicate all child-level destinations that match the wildcard; default: <code>+</code></li> |
| <li><code>any_descendant_wildcard</code> : indicate destinations that match the wildcard recursively; default: <code>#</code></li> |
| <li><code>regex_wildcard_start</code> : pattern used to identify the start of a regex</li> |
| <li><code>regex_wildcard_end</code> : pattern used to identify the end of a regex</li> |
| <li><code>part_pattern</code> : allows you to specify a regex that constrains the naming of topics. default: <code>[ a-zA-Z0-9\_\-\%\~\:\(\)]+</code></li> |
| </ul> |
| |
| <h3 id = "Client_Libraries">Client Libraries</h3> |
| |
| <p>Apollo supports v3.1 of the MQTT protocol. The following clients will work:</p> |
| |
| <ul> |
| <li>Java : <a href="https://github.com/fusesource/mqtt-client">mqtt-client</a>, <a href="https://github.com/AlbinTheander/MeQanTT">MeQanTT</a></li> |
| <li>C : <a href="http://mosquitto.org/man/libmosquitto-3.html">libmosquitto</a></li> |
| <li>Erlang : <a href="https://github.com/squaremo/erlmqtt">erlmqtt</a>, <a href="http://code.google.com/p/my-mqtt4erl/">my-mqtt4erl</a></li> |
| <li>.NET : <a href="http://sourceforge.net/projects/mqttdotnet/">MQTTDotNet</a>, <a href="https://github.com/markallanson/nmqtt">nMQTT</a></li> |
| <li>Perl : <a href="https://github.com/beanz/net-mqtt-perl">net-mqtt-perl</a>, [anyevent-mqtt-perl]https://github.com/beanz/anyevent-mqtt-perl()</li> |
| <li>Python : <a href="https://github.com/iwanbk/nyamuk">nyamuk</a></li> |
| <li>Ruby : <a href="https://github.com/njh/ruby-mqtt">mqtt-ruby</a>, <a href="https://rubygems.org/gems/em-mqtt">ruby-em-mqtt</a></li> |
| <li>Javascript : <a href="http://ceit.uq.edu.au/content/simple-mqtt-cient-nodejs">Node.js MQTT Client</a></li> |
| <li>Delphi : <a href="http://jamiei.com/blog/code/mqtt-client-library-for-delphi/">TMQTTCLient</a></li> |
| <li>Device specific: <a href="http://knolleary.net/arduino-client-for-mqtt/">Arduino</a>, <a href="http://ceit.uq.edu.au/content/mqttclient-mbed-version-20">mbed</a>, <a href="http://github.com/njh/NanodeMQTT/">Nanode</a>, Netduino</li> |
| </ul> |
| |
| <p>To see an up-to-date listing of client libraries, please |
| <a href="http://mqtt.org/software">the MQTT website for its software</a> listings</p> |
| |
| <p>The Apollo distribution ships with an <code>examples</code> directory |
| where you can find some simple examples of how to use some of those |
| clients to send and receive messages from a broker instance.</p> |
| |
| <h3 id = "Connecting">Connecting</h3> |
| |
| <p>The default broker configuration secures access to the broker so that only |
| the <code>admin</code> user can connect. The default password for the <code>admin</code> user |
| is <code>password</code>.</p> |
| |
| <p>MQTT clients cannot specify a Virtual Host (see <a href="user-manual.html#Virtual_Hosts">the section on Virtual Hosts in the user guide</a>) |
| so the default virtual host will be used. This is usually the first Virtual Host defined in the Apollo.xml configuration |
| file.</p> |
| |
| <h3 id = "Destination_Types">Destination Types</h3> |
| |
| <p>The MQTT protocol is a publish/subscribe protocol. It does not permit true point-to-point messaging |
| achieved using Queues. Therefore Apollo allows only the use of Topics for MQTT messaging. |
| The concept of a subscription and durable subscription to Topics is similar to what you'd find in |
| other protocols and is controlled by the MQTT CONNECT frame's <code>clean session</code> attribute.</p> |
| |
| <h3 id = "Clean_Sessions">Clean Sessions</h3> |
| |
| <p>When a client sends a connect frame with the <code>clean session</code> flag set to cleared (false), any previously used session with |
| the same client_id will be re-used. This means while the client was away, that subscription could have received |
| messages. This is the equivalent of a durable subscription in Apollo.</p> |
| |
| <p>If the <code>clean session</code> flag is set (true), then a new session will be started and any sessions tha may have been |
| lingering would be removed. This is equivalent to a normal topic subscription in Apollo.</p> |
| |
| <h3 id = "Topic_Retained_Messages">Topic Retained Messages</h3> |
| |
| <p>If a message has been published with the retain flag set, then |
| the message will be 'remembered' by the topic so that if a new |
| subscription arrives, the last retained message is sent |
| to the subscription. For example if you're publishing |
| measurements and you want the last mesasurement published to |
| always be available to a client that subscribes to the topic, |
| you can set the retain flag on the PUBLISH frame.</p> |
| |
| <p>Note: retained messages are not retained between broker restarts for |
| Quality of Service setting of AT MOST ONCE (QoS=0).</p> |
| |
| <h3 id = "Last_Will_and_Testament_Message">Last Will and Testament Message</h3> |
| |
| <p>You can set a <code>will</code> message and assocaited QoS for the message when a client |
| first connects to Apollo. The will message is basically a message that |
| will only get sent if there is an unexpected error with the connection and it must be dropped. |
| This can be useful in situations where you have devices that could drop but |
| when they do, you want to know. So if a medical sensor client drops from the broker, |
| a will message could be sent to an “alarm” Topic and handled by the system as |
| a high-priority alert.</p> |
| |
| <h3 id = "Reliable_Messaging">Reliable Messaging</h3> |
| |
| <p>MQTT allows a client to publish a message with the following Quality of Service parameters (QoS):</p> |
| |
| <ul> |
| <li>At Most Once (QoS=0)</li> |
| <li>At Least Once (QoS=1)</li> |
| <li>Exactly Once (QoS=2)</li> |
| </ul> |
| |
| <h4 id = "At_Most_Once">At Most Once</h4> |
| |
| <p>This QoS will attempt to deliver the message to a client, but it will |
| have the lowest reliability of the three options. If you publish |
| with a QoS=0, At Most Once, then the broker will not send back an Ack |
| saying it received the message, nor will it retry if the broker fails. |
| This QoS is most similar to non-persistent messages in, for example, JMS.</p> |
| |
| <h4 id = "At_Least_Once">At Least Once</h4> |
| |
| <p>This QoS setting will ensure that the message is delivered at least once to |
| clients. When publishing with this setting, Apollo will send back |
| a PUBACK frame which acknowledges that the broker has received the message |
| and has taken “ownership” for delivering the message. If the client that |
| published the message with QoS=1 does not recieve the PUBACK in a specified |
| period of time, the client may wish to re-publish the message again with the |
| DUP flag set on the PUBLISH frame. It's possible the broker received the |
| first attempt to publish the message and subsequently published it to |
| listening clients. So if the PUBACK got lost somehwere and the client |
| sends the message again, there will be no duplicate detection, and the |
| broker will send the message again to the topic's subscribers.</p> |
| |
| <h4 id = "Exactly_Once">Exactly Once</h4> |
| |
| <p>This QoS is the strongest level of reliability afforded by the MQTT |
| protocol. This assures the publisher that its message will not only |
| get to its intended subscribers, but that the message will not be duplicated |
| as it could with QoS=1. This QoS, however, comes with increased network |
| overhead.</p> |
| |
| <p>When a message is published, the broker will store the message ID and |
| send the message to the Topic where it would be persisted if there are |
| any durable subscriptions. It will then send the PUBREC frame back to |
| the client implying the broker has received the message. At this point |
| the broker will expect the client to send the PUBREL frame to clear |
| the message ID from its session state and complete the send with the |
| broker sending a PUBCOMP.</p> |
| |
| <h3 id = "Wildcard_Subscriptions">Wildcard Subscriptions</h3> |
| |
| <p>Wild cards can be used in destination names when subscribing as a consumer. This allows you to subscribe |
| to multiple destinations or hierarchy of destinations.</p> |
| |
| <ul> |
| <li><code>/</code> is used to separate names in a path</li> |
| <li><code>+</code> is used to match any name in a path</li> |
| <li><code>#</code> is used to recursively match path names</li> |
| </ul> |
| |
| <p>For example using the above, these subscriptions are possible</p> |
| |
| <ul> |
| <li><code>PRICE/#</code> : Any price for any product on any exchange</li> |
| <li><code>PRICE/STOCK/#</code> : Any price for a stock on any exchange</li> |
| <li><code>PRICE/STOCK/NASDAQ/+</code> : Any stock price on NASDAQ</li> |
| <li><code>PRICE/STOCK/+/IBM</code> : Any IBM stock price on any exchange</li> |
| </ul> |
| |
| <h3 id = "Keep_Alive">Keep Alive</h3> |
| |
| <p>Apollo will only set a keep-alive/heart-beat monitor if the client has specified a <code>keepAlive</code> value in the |
| CONNECT frame. If one is specified, the actual value used by Apollo will be 1.5 * the keep alive value. This is |
| in keeping with the MQTT spec.</p> |
| |
| <h3 id = "Destination_Name_Restrictions">Destination Name Restrictions</h3> |
| |
| <p>Destination names are restricted to using the characters <code>a-z</code>, <code>A-Z</code>, <code>0-9</code>, |
| <code>_</code>, <code>-</code> <code>%</code>, <code>~</code>, <code>:</code>, ' ', '(', ')' or <code>.</code> in addition to composite separator <code>,</code> and the wild |
| card <code>*</code>. Any other characters must be UTF-8 and then URL encoded if you wish to |
| preserve their significance.</p> |
| <div></div> |
| </div> |
| </div> |
| </body> |
| </html> |