diff options
Diffstat (limited to 'libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html')
| -rw-r--r-- | libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html b/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html new file mode 100644 index 0000000..abd1447 --- /dev/null +++ b/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html @@ -0,0 +1,422 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--NewPage-->
+<HTML>
+<HEAD>
+<!-- Generated by javadoc (build 1.4.2) on Tue Oct 02 23:24:47 BST 2012 -->
+<TITLE>
+org.eclipse.paho.client.mqttv3 (MQTT v3 Client API)
+</TITLE>
+
+<META NAME="keywords" CONTENT="org.eclipse.paho.client.mqttv3 package">
+
+<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">
+
+<SCRIPT type="text/javascript">
+function windowTitle()
+{
+ parent.document.title="org.eclipse.paho.client.mqttv3 (MQTT v3 Client API)";
+}
+</SCRIPT>
+
+</HEAD>
+
+<BODY BGCOLOR="white" onload="windowTitle();">
+
+ +<!-- ========= START OF TOP NAVBAR ======= -->
+<A NAME="navbar_top"><!-- --></A> +<A HREF="#skip-navbar_top" title="Skip navigation links"></A> +<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
+<TR>
+<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
+<A NAME="navbar_top_firstrow"><!-- --></A> +<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
+ <TR ALIGN="center" VALIGN="top">
+ <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <A HREF="#main"><FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../serialized-form.html"><FONT CLASS="NavBarFont1"><B>Serialized</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
+ </TR>
+</TABLE>
+</TD>
+<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
+</EM>
+</TD>
+</TR>
+
+<TR>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ PREV PACKAGE
+ NEXT PACKAGE</FONT></TD>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ <A HREF="../../../../../index.html" target="_top"><B>FRAMES</B></A>
+ <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
+ <SCRIPT type="text/javascript">
+ <!--
+ if(window==top) {
+ document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
+ }
+ //-->
+</SCRIPT>
+<NOSCRIPT>
+ <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>
+</NOSCRIPT> +
+</FONT></TD>
+</TR>
+</TABLE>
+<A NAME="skip-navbar_top"></A> +<!-- ========= END OF TOP NAVBAR ========= -->
+
+<HR>
+<A NAME="main"></A>
+<H2>
+Package org.eclipse.paho.client.mqttv3
+</H2>
+Contains an API for connecting to a server which implements the MQTT V3
+protocol.
+
+
+<P>
+<B>See:</B>
+<BR>
+ <A HREF="#package_description"><B>Description</B></A>
+<P>
+ +<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN=2><FONT SIZE="+2">
+<B>Interface Summary</B></FONT></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3">MqttCallback</A></B></TD>
+<TD>Asynchronous message listener. </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClientPersistence.html" title="interface in org.eclipse.paho.client.mqttv3">MqttClientPersistence</A></B></TD>
+<TD>Represents a persistent data store, used to store outbound and inbound messages while they + are in flight, enabling delivery to the QOS specified. </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttDeliveryToken.html" title="interface in org.eclipse.paho.client.mqttv3">MqttDeliveryToken</A></B></TD>
+<TD>Provides a mechanism for tracking the delivery of messages. + + </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttPersistable.html" title="interface in org.eclipse.paho.client.mqttv3">MqttPersistable</A></B></TD>
+<TD>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. + </TD>
+</TR>
+</TABLE>
+
+
+<P>
+ +<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN=2><FONT SIZE="+2">
+<B>Class Summary</B></FONT></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html" title="class in org.eclipse.paho.client.mqttv3">MqttClient</A></B></TD>
+<TD>Lightweight client for talking to a server via the MQTT version 3 + protocol. </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttConnectOptions.html" title="class in org.eclipse.paho.client.mqttv3">MqttConnectOptions</A></B></TD>
+<TD>Stores options used when connecting to a server.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttDefaultFilePersistence.html" title="class in org.eclipse.paho.client.mqttv3">MqttDefaultFilePersistence</A></B></TD>
+<TD>An implementation of the <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClientPersistence.html" title="interface in org.eclipse.paho.client.mqttv3"><CODE>MqttClientPersistence</CODE></A> interface that provides + file based persistence. + + </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttMessage.html" title="class in org.eclipse.paho.client.mqttv3">MqttMessage</A></B></TD>
+<TD>An MQTT message. </TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttTopic.html" title="class in org.eclipse.paho.client.mqttv3">MqttTopic</A></B></TD>
+<TD>Represents a topic destination, used for publish/subscribe messaging.</TD>
+</TR>
+</TABLE>
+
+
+<P>
+ +<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN=2><FONT SIZE="+2">
+<B>Exception Summary</B></FONT></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttException.html" title="class in org.eclipse.paho.client.mqttv3">MqttException</A></B></TD>
+<TD>Thrown if an error occurs communicating with the server.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttPersistenceException.html" title="class in org.eclipse.paho.client.mqttv3">MqttPersistenceException</A></B></TD>
+<TD>This exception should be thrown by the implementor of the persistence + interface if there is a problem reading or writing persistent data.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD WIDTH="15%"><B><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttSecurityException.html" title="class in org.eclipse.paho.client.mqttv3">MqttSecurityException</A></B></TD>
+<TD>Thrown when a client is not authorized to perform an operation, or + if there is a problem with the security configuration.</TD>
+</TR>
+</TABLE>
+
+
+<P>
+<A NAME="package_description"><!-- --></A><H2>
+Package org.eclipse.paho.client.mqttv3 Description
+</H2>
+
+<P>
+Contains an API for connecting to a server which implements the MQTT V3
+protocol.
+
+<p>
+The MQ Telemetry Transport (MQTT) is a lightweight publish/subscribe protocol
+flowing over TCP/IP for remote sensors and control devices through low
+bandwidth communications. MQTT is used by specialized applications on
+small footprint devices that require a low bandwidth communication,
+typically for remote data acquisition and process control.
+</p>
+<p>
+A typical system might comprise several hundred client devices communicating
+with a single server or "broker", where each client is identified
+by a unique ID.
+</p>
+<p>The basic means of operating the client is as follows:</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>, providing
+ the address of the server and a unique client identifier.</li>
+ <li><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html#connect(org.eclipse.paho.client.mqttv3.MqttConnectOptions)"><CODE>Connect</CODE></A> to the server</li>
+ <li>Exchange messages with the server.
+ <ul>
+ <li>Send <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttMessage.html" title="class in org.eclipse.paho.client.mqttv3"><CODE>messages</CODE></A> to the server,
+ via <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttTopic.html" title="class in org.eclipse.paho.client.mqttv3"><CODE>topics</CODE></A>.</li>
+ <li>Receive messages from the server. This is done asynchronously
+ using
+ <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html#subscribe(java.lang.String, int)"><CODE>subscriptions</CODE></A>,
+ combined with a <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html#setCallback(org.eclipse.paho.client.mqttv3.MqttCallback)"><CODE>callback</CODE></A>.
+ </li>
+ </ul>
+ </li>
+<li><A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttClient.html#disconnect()"><CODE>Disconnect</CODE></A> from the server.</li>
+</ol>
+</p>
+<h3>Examples</h3>
+<h4>Publish a message, at most once</h4>
+<p>In the following code snippet, a simple message is published to the server,
+using defaults wherever possible.</p>
+<code><pre> MqttClient client = new MqttClient("tcp://localhost:1883", "SampleClient");
+ client.connect();
+ MqttMessage message = new MqttMessage("Hello world");
+ message.setQos(0);
+ client.getTopic("foo/bar").publish(message);
+ client.disconnect();</pre></code>
+
+<p>This is the fastest way of publishing messages,
+but is also the least reliable. There is no assurance that the message will actually be
+delivered, and no exception will be thrown if the server refuses the message, or if the
+network connection fails.</p>
+
+<h4>Publish a message, once and only once (single threaded)</h4>
+<p>In the following code snippet, a message is published to the server
+at QoS 2, which is the most reliable delivery mechanism.
+In order to achieve this, the message needs to be persisted by the client.
+A default implementation of persistence is provided by <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttDefaultFilePersistence.html" title="class in org.eclipse.paho.client.mqttv3"><CODE>MqttDefaultFilePersistence</CODE></A>.
+This will be used by the client unless an alternative is supplied.</p>
+<p>Publishing reliably is more complex, and most of the code is used to handle
+error conditions. The key thing to notice is the two-stage delivery: the first
+stage gives the message to the client. After this, the client is responsible for
+delivering the message to the server. The second stage is about determining
+success or failure.</p>
+
+<code><pre>
+ MqttClient client = null;
+ try {
+ // Create a client to communicate with a broker at the specified address
+ client = new MqttClient("tcp://localhost:1883", "SampleClient");
+ // Connect to the broker
+ client.connect();
+ } catch (MqttException ex) {
+ System.err.println("Could not connect");
+ }
+
+ if ((client != null) && client.isConnected()) {
+ MqttTopic topic = client.getTopic("foo/bar");
+ MqttDeliveryToken token = null;
+ // Create message and set quality of service to deliver the message once
+ MqttMessage message = new MqttMessage("Hello world");
+ message.setQos(2);
+
+ try {
+ // Give the message to the client for publishing. For QoS 2,
+ // this will involve multiple network calls, which will happen
+ // asynchronously after this method has returned.
+ token = topic.publish(message);
+ }
+ catch (MqttException ex) {
+ // Client has not accepted the message due to a failure
+ // Depending on the exception's reason code, we could always retry
+ System.err.println("Failed to send message");
+ }
+
+ if (token != null) {
+ boolean keepTrying = true;
+ do {
+ try {
+ // Wait for the message delivery to complete
+ token.waitForCompletion();
+ System.out.println("Message delivery complete");
+ }
+ catch (MqttException deliveryException) {
+ int reasonCode = deliveryException.getReasonCode();
+ // TODO: Retry the message, or decide to stop trying
+ System.err.println("Message delivery failed");
+ if (client.isConnected() == false) {
+ try {
+ // Re-connect to the server
+ client.connect();
+ }
+ catch (MqttException connectException) {
+ // Can't reconnect, so give up. If and when the
+ // client does reconnect, the message delivery
+ // will automatically continue
+ keepTrying = false;
+ }
+ }
+ }
+ } while (!token.isComplete() && keepTrying);
+ }
+ }</pre></code>
+
+<h4>Publish a message, once and only once (multi-threaded)</h4>
+<p>In the following code snippet, a message is published to the server
+at QoS 2, which is the most reliable delivery mechanism.
+The application uses a <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html" title="interface in org.eclipse.paho.client.mqttv3"><CODE>callback</CODE></A> to asynchronously be notified
+when delivery of a message has been <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttCallback.html#deliveryComplete(org.eclipse.paho.client.mqttv3.MqttDeliveryToken)"><CODE>completed</CODE></A>.</p>
+
+<p>
+A default implementation of persistence is provided by <A HREF="../../../../../org/eclipse/paho/client/mqttv3/MqttDefaultFilePersistence.html" title="class in org.eclipse.paho.client.mqttv3"><CODE>MqttDefaultFilePersistence</CODE></A>.
+This will be used by the client unless an alternative is supplied.</p>
+
+<code><pre>
+public class SampleClient implements MqttCallback {
+ public void run() {
+ MqttClient client = null;
+ try {
+ // Create a client to communicate with a broker at the specified address
+ client = new MqttClient("tcp://localhost:1883", "SampleClient");
+
+ // Connect to the broker
+ client.connect();
+
+ // Setup a callback
+ client.setCallback(this);
+
+ } catch (MqttException ex) {
+ System.err.println("Could not connect");
+ }
+
+ if ((client != null) && client.isConnected()) {
+ MqttTopic topic = client.getTopic("foo/bar");
+ // Create message and set quality of service to deliver the message once
+ MqttMessage message = new MqttMessage("Hello world");
+ message.setQos(2);
+
+ try {
+ // Give the message to the client for publishing. For QoS 2, this
+ // will involve multiple network calls, which will happen
+ // asynchronously after this method has returned.
+ topic.publish(message);
+ } catch (MqttException ex) {
+ // Client has not accepted the message due to a failure
+ // Depending on the exception's reason code, we could always retry
+ System.err.println("Failed to send message");
+ }
+ }
+ }
+
+ public void connectionLost(Throwable cause) {
+ // TODO: Implement reconnection logic
+ System.err.println("Connection lost");
+ }
+
+ public void deliveryComplete(MqttDeliveryToken token) {
+ System.out.println("Delivery complete");
+ }
+
+ public void messageArrived(MqttTopic topic, MqttMessage message) throws Exception {
+ }
+}</pre></code>
+<P>
+
+<P>
+<HR>
+
+ +<!-- ======= START OF BOTTOM NAVBAR ====== -->
+<A NAME="navbar_bottom"><!-- --></A> +<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> +<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
+<TR>
+<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
+<A NAME="navbar_bottom_firstrow"><!-- --></A> +<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
+ <TR ALIGN="center" VALIGN="top">
+ <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <A HREF="#main"><FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../serialized-form.html"><FONT CLASS="NavBarFont1"><B>Serialized</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
+ </TR>
+</TABLE>
+</TD>
+<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
+</EM>
+</TD>
+</TR>
+
+<TR>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ PREV PACKAGE
+ NEXT PACKAGE</FONT></TD>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ <A HREF="../../../../../index.html" target="_top"><B>FRAMES</B></A>
+ <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
+ <SCRIPT type="text/javascript">
+ <!--
+ if(window==top) {
+ document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
+ }
+ //-->
+</SCRIPT>
+<NOSCRIPT>
+ <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>
+</NOSCRIPT> +
+</FONT></TD>
+</TR>
+</TABLE>
+<A NAME="skip-navbar_bottom"></A> +<!-- ======== END OF BOTTOM NAVBAR ======= -->
+
+<HR>
+
+</BODY>
+</HTML>
|