Package org.eclipse.paho.client.mqttv3

Contains a programming interface enabling applications to communicate with an MQTT server.

See: Description

Interface Summary

Interface	Description
IMqttActionListener	Implementors of this interface will be notified when an asynchronous action completes.
IMqttAsyncClient	Enables an application to communicate with an MQTT server using non-blocking methods.
IMqttClient	Enables an application to communicate with an MQTT server using blocking methods.
IMqttDeliveryToken	Provides a mechanism for tracking the delivery of a message.
IMqttMessageListener	Implementers of this interface will be notified when a message arrives.
IMqttToken	Provides a mechanism for tracking the completion of an asynchronous task.
MqttCallback	Enables an application to be notified when asynchronous events related to the client occur.
MqttCallbackExtended	Extension of MqttCallback to allow new callbacks without breaking the API for existing applications.
MqttClientPersistence	Represents a persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.
MqttPersistable	Represents an object used to pass data to be persisted across the MqttClientPersistence interface.
MqttPingSender	Represents an object used to send ping packet to MQTT broker every keep alive interval.

Class Summary

Class	Description
BufferedMessage	A BufferedMessage contains an MqttWire Message and token it allows both message and token to be buffered when the client is in resting state
DisconnectedBufferOptions	Holds the set of options that govern the behaviour of Offline (or Disconnected) buffering of messages
MqttAsyncClient	Lightweight client for talking to an MQTT server using non-blocking methods that allow an operation to run in the background.
MqttClient	Lightweight client for talking to an MQTT server using methods that block until an operation completes.
MqttConnectOptions	Holds the set of options that control how the client connects to a server.
MqttDeliveryToken	Provides a mechanism to track the delivery progress of a message.
MqttMessage	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[].
MqttToken	Provides a mechanism for tracking the completion of an asynchronous action.
MqttTopic	Represents a topic destination, used for publish/subscribe messaging.
TimerPingSender	Default ping sender implementation

Exception Summary

Exception	Description
MqttException	Thrown if an error occurs communicating with the server.
MqttPersistenceException	This exception is 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 a programming interface enabling applications to communicate with an MQTT server.

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:

• Where the network is expensive, has low bandwidth or is unreliable such as mobile and vsat networks
• When run on an embedded or mobile device with limited processor, memory or battery

Features of the protocol include:

• The publish/subscribe message pattern to provide one-to-many message distribution and decoupling of applications
• A messaging transport that is agnostic to the content of the payload
• The use of TCP/IP to provide network connectivity
• The use of SSL/TLS to provide network security and trust
• Three qualities of service for message delivery which are maintained across network, client and server breaks.
  • "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.
  • "At least once", where messages are assured to arrive but duplicates may occur.
  • "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.
  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
• A small transport overhead (the fixed-length header is just 2 bytes), and protocol exchanges minimised to reduce network traffic
• A mechanism to notify interested parties to an abnormal disconnection of a client using the Last Will and Testament feature

The basic means of operating the client is:

1. Create an instance of MqttClient or MqttAsyncClient, providing the address of an MQTT server and a unique client identifier.
2. connect to the server
3. Exchange messages with the server:
   • publish messages to the server specifying a topic as the destination on the server
   • subscribe to one more topics. 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 callback
4. disconnect from the server.

The programming model and concepts like the protocol are small and easy to use. Key concepts to use when creating MQTT application include:

• 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.
• 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 MqttDefaultFilePersistence is used.
• When connecting the cleansession option has a big impact on the operation of the client. If set to false:
  • Message delivery will match the quality of service specified when the message was published even across failures of the network, client or server
  • 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.
  If set to true:
  • 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.
  • 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.
  • 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
• When subscribing for messages the subscription can be for an absolute topic or a wildcarded topic.
• When unsubscribing the topic to be unsubscribed must match one specified on an earlier subscribe.
• There are two MQTT client libraries to choose from:
  1. MqttAsyncClient 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:
     • Use the waitForCompletion call on the token returned from the operation. This will block until the operation completes.
     • Pass a IMqttActionListener to the operation. The listener will then be called back when the operation completes.
     • Set a MqttCallback 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.
  2. MqttClient where methods block until the operation has completed.
• For both the blocking and non-blocking clients some operations are asynchronous. This includes:
  • Notification that a new message has arrived: messageArrived.
  • Notification that the connection to the server has broken: connectionLost.
  • Notification that a message has been delivered to the server: deliveryComplete.
  A client registers interest in these notifications by registering a MqttCallback on the client
• There are a number of programs that demonstrate the different modes of writing MQTT applications
  • org.eclipse.paho.sample.mqttv3app.Sample uses the blocking client interface
  • org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack uses the asynchronous client with callbacks which are notified when an operation completes
  • org.eclipse.paho.sample.mqttv3app.SampleAsyncWait uses the asynchronous client and shows how to use the token returned from each operation to block until the operation completes.
• MqttConnectOptions can be used to override the default connection options. This includes:
  • Setting the cleansession flag
  • Specifying a list of MQTT servers that the client can attempt to connect to
  • Set a keepalive interval
  • Setting the last will and testament
  • Setting security credentials