Google Git
Sign in
eclipse / gerrit / www.eclipse.org / paho / b0d1f1dc4e00e95ae1282c5465b8ac347079ffc3 / . / files / javadoc / org / eclipse / paho / client / mqttv3 / package-summary.html
blob: 75c6084feb7b499a545745094caba52e0a939dee [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_101) on Thu Sep 01 13:59:14 BST 2016 -->
<title>org.eclipse.paho.client.mqttv3</title>
<meta name="date" content="2016-09-01">
<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="org.eclipse.paho.client.mqttv3";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../overview-summary.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-use.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-files/index-1.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Package</li>
<li><a href="../../../../../org/eclipse/paho/client/mqttv3/internal/package-summary.html">Next&nbsp;Package</a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../index.html?org/eclipse/paho/client/mqttv3/package-summary.html" target="_top">Frames</a></li>
<li><a href="package-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">
<h1 title="Package" class="title">Package&nbsp;org.eclipse.paho.client.mqttv3</h1>
<div class="docSummary">
<div class="block">Contains a programming interface enabling applications to communicate with an MQTT server.</div>
</div>
<p>See:&nbsp;<a href="#package.description">Description</a></p>
</div>
<div class="contentContainer">
<ul class="blockList">
<li class="blockList">
<table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation">
<caption><span>Interface Summary</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Interface</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttActionListener.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttActionListener</a></td>
<td class="colLast">
<div class="block">Implementors of this interface will be notified when an asynchronous action completes.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttAsyncClient.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttAsyncClient</a></td>
<td class="colLast">
<div class="block">Enables an application to communicate with an MQTT server using non-blocking methods.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttClient.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttClient</a></td>
<td class="colLast">
<div class="block">Enables an application to communicate with an MQTT server using blocking methods.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttDeliveryToken.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttDeliveryToken</a></td>
<td class="colLast">
<div class="block">Provides a mechanism for tracking the delivery of a message.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttMessageListener.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttMessageListener</a></td>
<td class="colLast">
<div class="block">Implementers of this interface will be notified when a message arrives.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttToken.html" title="interface in org.eclipse.paho.client.mqttv3">IMqttToken</a></td>
<td class="colLast">
<div class="block">Provides a mechanism for tracking the completion of an asynchronous task.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3">MqttCallback</a></td>
<td class="colLast">
<div class="block">Enables an application to be notified when asynchronous
events related to the client occur.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallbackExtended.html" title="interface in org.eclipse.paho.client.mqttv3">MqttCallbackExtended</a></td>
<td class="colLast">
<div class="block">Extension of <a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttCallback</code></a> to allow new callbacks
without breaking the API for existing applications.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttClientPersistence.html" title="interface in org.eclipse.paho.client.mqttv3">MqttClientPersistence</a></td>
<td class="colLast">
<div class="block">Represents a persistent data store, used to store outbound and inbound messages while they
are in flight, enabling delivery to the QoS specified.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttPersistable.html" title="interface in org.eclipse.paho.client.mqttv3">MqttPersistable</a></td>
<td class="colLast">
<div class="block">Represents an object used to pass data to be persisted across the
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttClientPersistence.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttClientPersistence</code></a>
interface.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttPingSender.html" title="interface in org.eclipse.paho.client.mqttv3">MqttPingSender</a></td>
<td class="colLast">
<div class="block">Represents an object used to send ping packet to MQTT broker
every keep alive interval.</div>
</td>
</tr>
</tbody>
</table>
</li>
<li class="blockList">
<table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation">
<caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Class</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/BufferedMessage.html" title="class in org.eclipse.paho.client.mqttv3">BufferedMessage</a></td>
<td class="colLast">
<div class="block">A BufferedMessage contains an MqttWire Message and token
it allows both message and token to be buffered when the client
is in resting state</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/DisconnectedBufferOptions.html" title="class in org.eclipse.paho.client.mqttv3">DisconnectedBufferOptions</a></td>
<td class="colLast">
<div class="block">Holds the set of options that govern the behaviour
of Offline (or Disconnected) buffering of messages</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttAsyncClient.html" title="class in org.eclipse.paho.client.mqttv3">MqttAsyncClient</a></td>
<td class="colLast">
<div class="block">Lightweight client for talking to an MQTT server using non-blocking methods
that allow an operation to run in the background.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html" title="class in org.eclipse.paho.client.mqttv3">MqttClient</a></td>
<td class="colLast">
<div class="block">Lightweight client for talking to an MQTT server using methods that block
until an operation completes.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttConnectOptions.html" title="class in org.eclipse.paho.client.mqttv3">MqttConnectOptions</a></td>
<td class="colLast">
<div class="block">Holds the set of options that control how the client connects to a server.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttDeliveryToken.html" title="class in org.eclipse.paho.client.mqttv3">MqttDeliveryToken</a></td>
<td class="colLast">
<div class="block">Provides a mechanism to track the delivery progress of a message.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttMessage.html" title="class in org.eclipse.paho.client.mqttv3">MqttMessage</a></td>
<td class="colLast">
<div class="block">An MQTT message holds the application payload and options
specifying how the message is to be delivered
The message includes a "payload" (the body of the message)
represented as a byte[].</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttToken.html" title="class in org.eclipse.paho.client.mqttv3">MqttToken</a></td>
<td class="colLast">
<div class="block">Provides a mechanism for tracking the completion of an asynchronous action.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttTopic.html" title="class in org.eclipse.paho.client.mqttv3">MqttTopic</a></td>
<td class="colLast">
<div class="block">Represents a topic destination, used for publish/subscribe messaging.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/TimerPingSender.html" title="class in org.eclipse.paho.client.mqttv3">TimerPingSender</a></td>
<td class="colLast">
<div class="block">Default ping sender implementation</div>
</td>
</tr>
</tbody>
</table>
</li>
<li class="blockList">
<table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation">
<caption><span>Exception Summary</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Exception</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttException.html" title="class in org.eclipse.paho.client.mqttv3">MqttException</a></td>
<td class="colLast">
<div class="block">Thrown if an error occurs communicating with the server.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttPersistenceException.html" title="class in org.eclipse.paho.client.mqttv3">MqttPersistenceException</a></td>
<td class="colLast">
<div class="block">This exception is thrown by the implementor of the persistence
interface if there is a problem reading or writing persistent data.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttSecurityException.html" title="class in org.eclipse.paho.client.mqttv3">MqttSecurityException</a></td>
<td class="colLast">
<div class="block">Thrown when a client is not authorized to perform an operation, or
if there is a problem with the security configuration.</div>
</td>
</tr>
</tbody>
</table>
</li>
</ul>
<a name="package.description">
<!-- -->
</a>
<h2 title="Package org.eclipse.paho.client.mqttv3 Description">Package org.eclipse.paho.client.mqttv3 Description</h2>
<div class="block">Contains a programming interface enabling applications to communicate with an MQTT server.
<p>
The MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe
messaging protocol designed to be open, simple, lightweight and easy to implement.
These characteristics make it ideal for use in constrained environments, for example,
but not limited to:
<ul>
<li>Where the network is expensive, has low bandwidth or is unreliable such as mobile and vsat networks
<li>When run on an embedded or mobile device with limited processor, memory or battery
</ul>
<p>Features of the protocol include:
<ul>
<li>The publish/subscribe message pattern to provide one-to-many message
distribution and decoupling of applications
<li>A messaging transport that is agnostic to the content of the payload
<li>The use of TCP/IP to provide network connectivity
<li>The use of SSL/TLS to provide network security and trust
<li>Three qualities of service for message delivery which are maintained across
network, client and server breaks.
<ul>
<li>"At most once", where messages are delivered according to the best efforts
of the underlying TCP/IP network. Message loss or duplication can occur.
This level could be used, for example, with ambient sensor data where it
does not matter if an individual reading is lost as the next one will be published soon after.
<li>"At least once", where messages are assured to arrive but duplicates may occur.
<li>"Exactly once", where message are assured to arrive exactly once. This
level could be used, for example, with billing systems where duplicate or
lost messages could lead to incorrect charges being applied.
</ul>
The quality of service for message delivery is met even if the network connection
breaks, or the client or the server stop while a message is being delivered
<li>A small transport overhead (the fixed-length header is just 2 bytes), and
protocol exchanges minimised to reduce network traffic
<li>A mechanism to notify interested parties to an abnormal disconnection of
a client using the Last Will and Testament feature
</ul>
<p>The basic means of operating the client is:</p>
<ol>
<li>Create an instance of <a href="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html" title="class in org.eclipse.paho.client.mqttv3"><code>MqttClient</code></a> or
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttAsyncClient.html" title="class in org.eclipse.paho.client.mqttv3"><code>MqttAsyncClient</code></a>, providing
the address of an MQTT server and a unique client identifier.</li>
<li><code>connect</code> to the server</li>
<li>Exchange messages with the server:
<ul>
<li><code>publish messages</code> to the server
specifying a <code>topic</code> as the destination on the server</li>
<li><code>subscribe</code> to one more <code>topics</code>. The server will send any messages
it receives on those topics to the client. The client will be informed when a message
arrives via a <code>callback</code>
</ul>
<li><code>disconnect</code> from the server.</li>
</ol>
<p>The programming model and concepts like the protocol are small and easy to use. Key concepts
to use when creating MQTT application include:
<ul>
<li>Every client instance that connects to an MQTT server must have a unique client identifier.
If a second instance of a client with the same ID connects to a server the first instance will be
disconnected.
<li>For message delivery to be reliable and withstand normal and abnormal network breaks together with client
and server outages the client must use a persistent store to hold messages while they are being delivered. This is
the default case where a file based persistent store
<a href="../../../../../org/eclipse/paho/client/mqttv3/persist/MqttDefaultFilePersistence.html" title="class in org.eclipse.paho.client.mqttv3.persist"><code>MqttDefaultFilePersistence</code></a> is used.
<li>When connecting the <a href="../../../../../org/eclipse/paho/client/mqttv3/MqttConnectOptions.html#setCleanSession-boolean-"><code>cleansession</code></a>
option has a big impact on the operation of the client. If set to false:
<ul>
<li>Message delivery will match the quality of service specified when the message was published even across
failures of the network, client or server
<li>The server will store messages for active subscriptions on behalf of the client when the client is not connected.
The server will deliver these messages to the client the next time it connects.
</ul>
If set to true:
<ul>
<li>Any state stored on the client and server related to the client will be cleansed
before the connection is fully started. Subscriptions from earlier sessions will be unsubscribed
and any messages still in-flight from previous sessions will be deleted.
<li>When the client disconnects either as the result of the application requesting a disconnect
or a network failure, state related to the client will be cleansed just as at connect time.
<li>Messages will only be delivered to the quality of service requested at publish time if
the connection is maintained while the message is being delivered
</ul>
<li>When subscribing for messages the subscription can be for an absolute topic or a wildcarded topic.
<li>When unsubscribing the topic to be unsubscribed must match one specified on an earlier subscribe.
<li>There are two MQTT client libraries to choose from:
<ol>
<li><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttAsyncClient.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttAsyncClient</code></a> which provides a non-blocking interface where
methods return before the requested operation has completed. The completion of the operation
can be monitored by in several ways:
<ul>
<li>Use the <a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttToken.html#waitForCompletion--"><code>waitForCompletion</code></a>
call on the token returned from the operation. This will block
until the operation completes.
<li>Pass a <a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttActionListener.html" title="interface in org.eclipse.paho.client.mqttv3"><code>IMqttActionListener</code></a>
to the operation. The listener will then be called back when the operation completes.
<li>Set a <a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttCallback</code></a> on the client. It
will be notified when a message arrives, a message have been delivered to the server and when the
connection to the server is lost.
</ul>
<li><a href="../../../../../org/eclipse/paho/client/mqttv3/IMqttClient.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttClient</code></a> where methods block until
the operation has completed.
</ol>
<li>For both the blocking and non-blocking clients some operations are asynchronous. This includes:
<ul>
<li>Notification that a new message has arrived:
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html#messageArrived-java.lang.String-org.eclipse.paho.client.mqttv3.MqttMessage-"><code>messageArrived</code></a>.
<li>Notification that the connection to the server has broken:
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html#connectionLost-java.lang.Throwable-"><code>connectionLost</code></a>.
<li>Notification that a message has been delivered to the server:
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html#deliveryComplete-org.eclipse.paho.client.mqttv3.IMqttDeliveryToken-"><code>deliveryComplete</code></a>.
</ul>
A client registers interest in these notifications by registering a
<a href="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3"><code>MqttCallback</code></a> on the client
<li>There are a number of programs that demonstrate the different modes of
writing MQTT applications
<ul>
<li><code>org.eclipse.paho.sample.mqttv3app.Sample</code> uses the blocking client interface
<li><code>org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack</code> uses the asynchronous client with
callbacks which are notified when an operation completes
<li><code>org.eclipse.paho.sample.mqttv3app.SampleAsyncWait</code> uses the asynchronous client and
shows how to use the token returned from each operation to block until the operation completes.
</ul>
<li><a href="../../../../../org/eclipse/paho/client/mqttv3/MqttConnectOptions.html" title="class in org.eclipse.paho.client.mqttv3"><code>MqttConnectOptions</code></a> can be used to override the
default connection options. This includes:
<ul>
<li>Setting the cleansession flag
<li>Specifying a list of MQTT servers that the client can attempt to connect to
<li>Set a keepalive interval
<li>Setting the last will and testament
<li>Setting security credentials
</ul>
</ul></div>
</div>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../overview-summary.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-use.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-files/index-1.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Package</li>
<li><a href="../../../../../org/eclipse/paho/client/mqttv3/internal/package-summary.html">Next&nbsp;Package</a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../index.html?org/eclipse/paho/client/mqttv3/package-summary.html" target="_top">Frames</a></li>
<li><a href="package-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>