From cc8ace92f17c8e5aef7d68ff316e5cd038cd36b5 Mon Sep 17 00:00:00 2001 From: Nathan Lasseter Date: Wed, 22 May 2013 15:34:00 +0100 Subject: Initial Commit --- .../org/eclipse/paho/client/mqttv3/MqttClient.html | 959 +++++++++++++++++++++ 1 file changed, 959 insertions(+) create mode 100644 libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/MqttClient.html (limited to 'libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/MqttClient.html') diff --git a/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/MqttClient.html b/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/MqttClient.html new file mode 100644 index 0000000..3a14a1a --- /dev/null +++ b/libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/MqttClient.html @@ -0,0 +1,959 @@ + + + + + + +MqttClient (MQTT v3 Client API) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Package   Class  Use  Tree  Serialized  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ + +

+ +org.eclipse.paho.client.mqttv3 +
+Class MqttClient

+
+java.lang.Object
+  extended byorg.eclipse.paho.client.mqttv3.MqttClient
+
+
+
All Implemented Interfaces:
org.eclipse.paho.client.mqttv3.internal.DestinationProvider
+
+
+
+
public class MqttClient
extends java.lang.Object
implements org.eclipse.paho.client.mqttv3.internal.DestinationProvider
+ +

+Lightweight client for talking to a server via the MQTT version 3 + protocol. The client allows an application to use publish/subscribe + messaging. +

+ +

+

+ +

+ + + + + + + + + + + + + + + + + + + +
+Constructor Summary
MqttClient(java.lang.String serverURI, + java.lang.String clientId) + +
+          Creates an MqttClient to connect to the specified address, using the + specified client identifier.
MqttClient(java.lang.String serverURI, + java.lang.String clientId, + MqttClientPersistence persistence) + +
+          Creates an MqttClient to connect to the specified address, using the + specified client identifer and persistence implementation.
+  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Method Summary
+ voidconnect() + +
+          Connects to a server using the default options. +
+ voidconnect(MqttConnectOptions options) + +
+          Connects to a server using the specified options. +
+ voiddisconnect() + +
+          Disconnects from the server, which quiesces for up to a + maximum of thirty seconds, to allow the client to finish any work it + currently has.
+ voiddisconnect(long quiesceTimeout) + +
+          Disconnects from the server. +
+static java.lang.StringgenerateClientId() + +
+          Returns a randomly generated client identifier based on the current user's login + name and the system time. +
+ java.lang.StringgetClientId() + +
+          Returns the client ID used by this client.
+ MqttDeliveryToken[]getPendingDeliveryTokens() + +
+          Returns the delivery tokens for any outstanding publish operations.
+ java.lang.StringgetServerURI() + +
+          Returns the address of the server used by this client, as a URI. +
+ MqttTopicgetTopic(java.lang.String topic) + +
+          Gets a topic object which can be used to publish messages. +
+ booleanisConnected() + +
+          Determines if this client is currently connected to the + server.
+ voidsetCallback(MqttCallback callback) + +
+          Sets the callback listener to use for asynchronously received + messages. +
+ voidsubscribe(java.lang.String topicFilter) + +
+          Subscribes to a topic, which may include wildcards, using the default + options.
+ voidsubscribe(java.lang.String[] topicFilters) + +
+          Subscribes to multiple topics, each of which may include wildcards, + using the default options.
+ voidsubscribe(java.lang.String[] topicFilters, + int[] qos) + +
+          Subscribes to multiple topics, each of which may include wildcards, + using the specified options.
+ voidsubscribe(java.lang.String topicFilter, + int qos) + +
+          Subscribes to a topic, which may include wildcards, using the specified + options.
+ voidunsubscribe(java.lang.String topicFilter) + +
+          Unsubscribes from a topic.
+ voidunsubscribe(java.lang.String[] topicFilters) + +
+          Unsubscribes from multiple topics.
+  + + + + + + + +
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
+  +

+ + + + + + + + + + + +
+Constructor Detail
+ +

+MqttClient

+
+public MqttClient(java.lang.String serverURI,
+                  java.lang.String clientId)
+           throws MqttException
+
+
Creates an MqttClient to connect to the specified address, using the + specified client identifier. The address + should be a URI, using a scheme of either "tcp://" for a TCP connection + or "ssl://" for a TCP connection secured by SSL/TLS. For example: +
    +
  • tcp://localhost:1883
    • +
  • ssl://localhost:8883
    • +
+

+ If the port is not specified, it will + default to 1883 for "tcp://" URIs, and 8883 for "ssl://" URIs. +

+

+ The client identifier should be unique across all clients connecting to the same + server. A convenience method is provided to generate a random client id that + should satisfy this criteria - generateClientId(). As the client identifier + is used by the server to identify a client when it reconnects, the client must use the + same identifier between connections if durable subscriptions are to be used. +

+

+ In Java SE, SSL can be configured in one of several ways, which the + client will use in the following order: +

+ + +

In Java ME, the platform settings are used for SSL connections.

+ +

A default instance of MqttDefaultFilePersistence is used by + the client. To specify a different persistence implementation, or to turn + off persistence, use the MqttClient(String, String, MqttClientPersistence) constructor. +

+

Parameters:
serverURI - the address to connect to, specified as a URI
clientId - the client ID to use +
Throws: +
java.lang.IllegalArgumentException - if the URI does not start with + "tcp://", "ssl://" or "local://". +
java.lang.IllegalArgumentException - if the clientId is null or is greater than 23 characters in length +
MqttException - if any other problem was encountered
+
+ +

+MqttClient

+
+public MqttClient(java.lang.String serverURI,
+                  java.lang.String clientId,
+                  MqttClientPersistence persistence)
+           throws MqttException
+
+
Creates an MqttClient to connect to the specified address, using the + specified client identifer and persistence implementation. The address + should be a URI, using a scheme of either "tcp://" for a TCP connection + or "ssl://" for a TCP connection secured by SSL/TLS. For example: +
    +
  • tcp://localhost:1883
    • +
  • ssl://localhost:8883
    • +
  • local://FirstBroker
    • +
+

+ If the port is not specified, it will + default to 1883 for "tcp://" URIs, and 8883 for "ssl://" URIs. +

+

+ The client identifier should be unique across all clients connecting to the same + server. A convenience method is provided to generate a random client id that + should satisfy this criteria - generateClientId(). As the client identifier + is used by the server to identify a client when it reconnects, the client must use the + same identifier between connections if durable subscriptions are to be used. +

+

+ In Java SE, SSL can be configured in one of several ways, which the + client will use in the following order: +

+ + +

In Java ME, the platform settings are used for SSL connections.

+ + The persistence mechanism is used to enable reliable messaging. + For qualities of server (QoS) 1 or 2 to work, messages must be persisted + to disk by both the client and the server. If this is not done, then + a failure in the client or server will result in lost messages. It + is the application's responsibility to provide an implementation of the + MqttClientPersistence interface, which the client can use to + persist messages. If the application is only sending QoS 0 messages, + then this is not needed. + +

An implementation of file-based persistence is provided in the + class MqttDefaultFilePersistence. + If no persistence is needed, it can be explicitly set to null.

+

+

Parameters:
serverURI - the address to connect to, specified as a URI
clientId - the client ID to use
persistence - the persistence mechanism to use. +
Throws: +
java.lang.IllegalArgumentException - if the URI does not start with + "tcp://", "ssl://" or "local://". +
java.lang.IllegalArgumentException - if the clientId is null or is greater than 23 characters in length +
MqttException - if any other problem was encountered
+ + + + + + + + +
+Method Detail
+ +

+connect

+
+public void connect()
+             throws MqttSecurityException,
+                    MqttException
+
+
Connects to a server using the default options. + It is recommended to call setCallback(MqttCallback) prior to + connecting. +

+

+
+
+
+ +
Throws: +
MqttSecurityException +
MqttException
+
+
+
+ +

+connect

+
+public void connect(MqttConnectOptions options)
+             throws MqttSecurityException,
+                    MqttException
+
+
Connects to a server using the specified options. + It is recommended to call setCallback(MqttCallback) prior to + connecting. +

+

+
+
+
+ +
Throws: +
MqttSecurityException +
MqttException
+
+
+
+ +

+disconnect

+
+public void disconnect()
+                throws MqttException
+
+
Disconnects from the server, which quiesces for up to a + maximum of thirty seconds, to allow the client to finish any work it + currently has. +

+

+
+
+
+ +
Throws: +
MqttException
See Also:
disconnect(long)
+
+
+
+ +

+disconnect

+
+public void disconnect(long quiesceTimeout)
+                throws MqttException
+
+
Disconnects from the server. + This method must not be called from inside MqttCallback methods. +

+ Firstly, the client will wait for all MqttCallback methods to + complete. It will then quiesce for the specified time, to allow for + work which has already been accepted to complete - for example, it will + wait for the QoS 2 flows from earlier publications to complete. After + the quiesce timeout, the client will disconnect from the server. When + the client is next connected, any QoS 1 or 2 messages which have not + completed will be retried.

+

+

+
+
+
+
Parameters:
quiesceTimeout - the amount of time in milliseconds to allow for existing work to finish + before disconnecting. A value of zero or less means the client will + not quiesce. +
Throws: +
MqttException
+
+
+
+ +

+isConnected

+
+public boolean isConnected()
+
+
Determines if this client is currently connected to the + server. +

+

+
+
+
+ +
Returns:
true if connected, false otherwise.
+
+
+
+ +

+getClientId

+
+public java.lang.String getClientId()
+
+
Returns the client ID used by this client. +

+

+
+
+
+ +
Returns:
the client ID used by this client.
+
+
+
+ +

+getServerURI

+
+public java.lang.String getServerURI()
+
+
Returns the address of the server used by this client, as a URI. + The format is the same as specified on the constructor. +

+

+
+
+
+ +
Returns:
the server's address, as a URI String.
See Also:
MqttClient(String, String)
+
+
+
+ +

+getTopic

+
+public MqttTopic getTopic(java.lang.String topic)
+
+
Gets a topic object which can be used to publish messages. +

When you build an application, + the design of the topic tree should take into account the following principles + of topic name syntax and semantics:

+ +
    +
  • A topic must be at least one character long.
    • +
  • Topic names are case sensitive. For example, ACCOUNTS and Accounts are + two different topics.
    • +
  • Topic names can include the space character. For example, Accounts + payable is a valid topic.
    • +
  • A leading "/" creates a distinct topic. For example, /finance is + different from finance. /finance matches "+/+" and "/+", but + not "+".
    • +
  • Do not include the null character (Unicode \x0000) in + any topic.
    • +
+ +

The following principles apply to the construction and content of a topic + tree:

+ +
    +
  • The length is limited to 64k but within that there are no limits to the + number of levels in a topic tree.
    • +
  • There can be any number of root nodes; that is, there can be any number + of topic trees.
    • +
+

+

+

+
Specified by:
getTopic in interface org.eclipse.paho.client.mqttv3.internal.DestinationProvider
+
+
+
Parameters:
topic - the topic to use, for example "finance/stock/ibm". +
Returns:
an MqttTopic object, which can be used to publish messages to + the topic. +
Throws: +
java.lang.IllegalArgumentException - if the topic contains a '+' or '#' + wildcard character.
+
+
+
+ +

+subscribe

+
+public void subscribe(java.lang.String topicFilter)
+               throws MqttException,
+                      MqttSecurityException
+
+
Subscribes to a topic, which may include wildcards, using the default + options. The setCallback(MqttCallback) method should be called + before this method, otherwise any received messages will be discarded. +

+

+
+
+
+ +
Throws: +
MqttException +
MqttSecurityException
See Also:
subscribe(String[], int[])
+
+
+
+ +

+subscribe

+
+public void subscribe(java.lang.String[] topicFilters)
+               throws MqttException,
+                      MqttSecurityException
+
+
Subscribes to multiple topics, each of which may include wildcards, + using the default options. The setCallback(MqttCallback) method should be called + before this method, otherwise any received messages will be discarded. +

+

+
+
+
+ +
Throws: +
MqttException +
MqttSecurityException
See Also:
subscribe(String[], int[])
+
+
+
+ +

+subscribe

+
+public void subscribe(java.lang.String topicFilter,
+                      int qos)
+               throws MqttException,
+                      MqttSecurityException
+
+
Subscribes to a topic, which may include wildcards, using the specified + options. The setCallback(MqttCallback) method should be called + before this method, otherwise any received messages will be discarded. +

+

+
+
+
+
Parameters:
topicFilter - the topic to subscribe to, which can include wildcards.
qos - the quality of service at which to subscribe. +
Throws: +
MqttException +
MqttSecurityException
See Also:
subscribe(String[], int[])
+
+
+
+ +

+subscribe

+
+public void subscribe(java.lang.String[] topicFilters,
+                      int[] qos)
+               throws MqttException,
+                      MqttSecurityException
+
+
Subscribes to multiple topics, each of which may include wildcards, + using the specified options. The setCallback(MqttCallback) method should be called + before this method, otherwise any received messages will be discarded. + +

The "topic filter" string used when subscribing + may contain special characters, which allow you to subscribe to multiple topics + at once.

+

The topic level separator is used to introduce structure into the topic, and + can therefore be specified within the topic for that purpose. The multi-level + wildcard and single-level wildcard can be used for subscriptions, but they + cannot be used within a topic by the publisher of a message. +

+
Topic level separator
+
The forward slash (/) is used to separate each level within + a topic tree and provide a hierarchical structure to the topic space. The + use of the topic level separator is significant when the two wildcard characters + are encountered in topics specified by subscribers.
+ +
Multi-level wildcard
+

The number sign (#) is a wildcard character that matches + any number of levels within a topic. For example, if you subscribe to finance/stock/ibm/#, you receive + messages on these topics:

   finance/stock/ibm
   finance/stock/ibm/closingprice
   finance/stock/ibm/currentprice
+

+

The multi-level wildcard + can represent zero or more levels. Therefore, finance/# can also match + the singular finance, where # represents zero levels. The topic + level separator is meaningless in this context, because there are no levels + to separate.

+ +

The multi-level wildcard can + be specified only on its own or next to the topic level separator character. + Therefore, # and finance/# are both valid, but finance# is + not valid. The multi-level wildcard must be the last character + used within the topic tree. For example, finance/# is valid but finance/#/closingprice is + not valid.

+ +
Single-level wildcard
+

The plus sign (+) is a wildcard character that matches only one topic + level. For example, finance/stock/+ matches finance/stock/ibm and finance/stock/xyz, + but not finance/stock/ibm/closingprice. Also, because the single-level + wildcard matches only a single level, finance/+ does not match finance.

+ +

Use + the single-level wildcard at any level in the topic tree, and in conjunction + with the multilevel wildcard. Specify the single-level wildcard next to the + topic level separator, except when it is specified on its own. Therefore, + and finance/+ are + both valid, but finance+ is not valid. The single-level + wildcard can be used at the end of the topic tree or within the topic tree. + For example, finance/+ and finance/+/ibm are both valid.

+
+
+

+

+

+
+
+
+
Parameters:
topicFilters - the topics to subscribe to, which can include wildcards.
qos - the qualities of service levels at which to subscribe. +
Throws: +
MqttException - if there was an error registering the subscription. +
java.lang.IllegalArgumentException - if the two supplied arrays are not the same size. +
MqttSecurityException
+
+
+
+ +

+unsubscribe

+
+public void unsubscribe(java.lang.String topicFilter)
+                 throws MqttException
+
+
Unsubscribes from a topic. +

+

+
+
+
+
Parameters:
topicFilter - the topic to unsubscribe from. +
Throws: +
MqttException
+
+
+
+ +

+unsubscribe

+
+public void unsubscribe(java.lang.String[] topicFilters)
+                 throws MqttException
+
+
Unsubscribes from multiple topics. +

+

+
+
+
+
Parameters:
topicFilters - the topics to unsubscribe from. +
Throws: +
MqttException
+
+
+
+ +

+setCallback

+
+public void setCallback(MqttCallback callback)
+                 throws MqttException
+
+
Sets the callback listener to use for asynchronously received + messages. + The + MqttCallback.messageArrived(MqttTopic, MqttMessage) + method will be called back whenever a message arrives. +

+

+
+
+
+
Parameters:
callback - the class to callback when a message arrives. +
Throws: +
MqttException
+
+
+
+ +

+generateClientId

+
+public static java.lang.String generateClientId()
+
+
Returns a randomly generated client identifier based on the current user's login + name and the system time. +

When cleanSession is set to false, an application should ensure it uses the + same client identifier when it reconnects to the server to resume state and maintain + assured message delivery.

+

+

+
+
+
+ +
Returns:
a generated client identifier
See Also:
MqttConnectOptions.setCleanSession(boolean)
+
+
+
+ +

+getPendingDeliveryTokens

+
+public MqttDeliveryToken[] getPendingDeliveryTokens()
+
+
Returns the delivery tokens for any outstanding publish operations. +

+

+
+
+
+
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Package   Class  Use  Tree  Serialized  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ + + -- cgit v1.2.1