+org.eclipse.paho.client.mqttv3 (MQTT v3 Client API) +

From cc8ace92f17c8e5aef7d68ff316e5cd038cd36b5 Mon Sep 17 00:00:00 2001 From: Nathan Lasseter Date: Wed, 22 May 2013 15:34:00 +0100 Subject: Initial Commit --- .../paho/client/mqttv3/package-summary.html | 422 +++++++++++++++++++++ 1 file changed, 422 insertions(+) create mode 100644 libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html (limited to 'libs/org.eclipse.paho.client.mqttv3/org/eclipse/paho/client/mqttv3/package-summary.html') 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 @@ + + + + + + +org.eclipse.paho.client.mqttv3 (MQTT v3 Client API) + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + + + +

Package

Class

Use

Tree

Serialized

Deprecated

Index

Help

+ +

+ PREV PACKAGE + NEXT PACKAGE

+ FRAMES + NO FRAMES + + + +

+ + + +

+ +

+Package org.eclipse.paho.client.mqttv3 +

+Contains an API for connecting to a server which implements the MQTT V3 +protocol. + + +

+See: +
+ Description +

+ + + + + + + + + + + + + + + + + + + + + +
+Interface Summary
MqttCallback Asynchronous message listener.
MqttClientPersistence Represents a persistent data store, used to store outbound and inbound messages while they + are in flight, enabling delivery to the QOS specified.
MqttDeliveryToken Provides a mechanism for tracking the delivery of messages. + +
MqttPersistable Represents an object used to pass data to be persisted across the + MqttClientPersistence + interface. +
+ + +

+Interface Summary
MqttCallback	Asynchronous message listener.
MqttClientPersistence	Represents a persistent data store, used to store outbound and inbound messages while they + are in flight, enabling delivery to the QOS specified.
MqttDeliveryToken	Provides a mechanism for tracking the delivery of messages. + +
MqttPersistable	Represents an object used to pass data to be persisted across the + `MqttClientPersistence` + interface. +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
+Class Summary
MqttClient Lightweight client for talking to a server via the MQTT version 3 + protocol.
MqttConnectOptions Stores options used when connecting to a server.
MqttDefaultFilePersistence An implementation of the MqttClientPersistence interface that provides + file based persistence. + +
MqttMessage An MQTT message.
MqttTopic Represents a topic destination, used for publish/subscribe messaging.
+ + +

+Class Summary
MqttClient	Lightweight client for talking to a server via the MQTT version 3 + protocol.
MqttConnectOptions	Stores options used when connecting to a server.
MqttDefaultFilePersistence	An implementation of the `MqttClientPersistence` interface that provides + file based persistence. + +
MqttMessage	An MQTT message.
MqttTopic	Represents a topic destination, used for publish/subscribe messaging.

+ + + + + + + + + + + + + + + + + +
+Exception Summary
MqttException Thrown if an error occurs communicating with the server.
MqttPersistenceException This exception should be thrown by the implementor of the persistence + interface if there is a problem reading or writing persistent data.
MqttSecurityException Thrown when a client is not authorized to perform an operation, or + if there is a problem with the security configuration.
+ + +

+Exception Summary
MqttException	Thrown if an error occurs communicating with the server.
MqttPersistenceException	This exception should be thrown by the implementor of the persistence + interface if there is a problem reading or writing persistent data.
MqttSecurityException	Thrown when a client is not authorized to perform an operation, or + if there is a problem with the security configuration.

+Package org.eclipse.paho.client.mqttv3 Description +

+ +

+Contains an API for connecting to a server which implements the MQTT V3 +protocol. + +

+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. +

+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. +

The basic means of operating the client is as follows:

Create an instance of MqttClient, providing + the address of the server and a unique client identifier.
Connect to the server
Exchange messages with the server. +
- Send messages to the server, + via topics.
- Receive messages from the server. This is done asynchronously + using + subscriptions, + combined with a callback. +
+
Disconnect from the server.

Examples

Publish a message, at most once

In the following code snippet, a simple message is published to the server, +using defaults wherever possible.

	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();

+ +

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.

+ +

Publish a message, once and only once (single threaded)

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 MqttDefaultFilePersistence. +This will be used by the client unless an alternative is supplied.

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.

+ +

+	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);
+		}
+	}

+ +

Publish a message, once and only once (multi-threaded)

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 callback to asynchronously be notified +when delivery of a message has been completed.

+ +

+A default implementation of persistence is provided by MqttDefaultFilePersistence. +This will be used by the client unless an alternative is supplied.

+ +

+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 {
+	}
+}

+ +

+ + + + + + + + + + + + + + + +