org.eclipse.paho.client.mqttv3.package.html Maven / Gradle / Ivy

Go to download

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:

  Create an instance of {@link org.eclipse.paho.client.mqttv3.MqttClient} or 
	{@link org.eclipse.paho.client.mqttv3.MqttAsyncClient}, providing
	the address of an MQTT server and a unique client identifier.
  connect to the server
  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 
  
  
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 
    {@link org.eclipse.paho.client.mqttv3.persist.MqttDefaultFilePersistence MqttDefaultFilePersistence} is used. 
  
When connecting the {@link org.eclipse.paho.client.mqttv3.MqttConnectOptions#setCleanSession(boolean) 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:
  
    {@link org.eclipse.paho.client.mqttv3.IMqttAsyncClient 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 {@link org.eclipse.paho.client.mqttv3.IMqttToken#waitForCompletion waitForCompletion}
       call on the token returned from the operation. This will block 
        until the operation completes. 
      
Pass a {@link org.eclipse.paho.client.mqttv3.IMqttActionListener IMqttActionListener}
        to the operation. The listener will then be called back when the operation completes.
      
Set a {@link org.eclipse.paho.client.mqttv3.MqttCallback 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.
    
    
{@link org.eclipse.paho.client.mqttv3.IMqttClient 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:
      {@link org.eclipse.paho.client.mqttv3.MqttCallback#messageArrived messageArrived}.
    
Notification that the connection to the server has broken:
      {@link org.eclipse.paho.client.mqttv3.MqttCallback#connectionLost connectionLost}.
    
Notification that a message has been delivered to the server: 
      {@link org.eclipse.paho.client.mqttv3.MqttCallback#deliveryComplete deliveryComplete}.
  
  A client registers interest in these notifications by registering a 
  {@link org.eclipse.paho.client.mqttv3.MqttCallback MqttCallback} on the client
  
There are a number of programs that demonstrate the different modes of 
    writing MQTT applications
  
    {@link org.eclipse.paho.sample.mqttv3app.Sample} uses the blocking client interface
    
{@link org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack} uses the asynchronous client with
      callbacks which are notified when an operation completes
    
{@link 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.
  
  
{@link org.eclipse.paho.client.mqttv3.MqttConnectOptions 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