Class: Paho::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/paho/client.rb

Overview

Enables an application to communicate with an MQTT server using non-blocking methods.

It provides applications a simple programming interface to all features of the MQTT version 3.1 specification including:

  • connect

  • publish

  • subscribe

  • unsubscribe

  • disconnect

MqttClient provides a set of non-blocking methods that return control to the invoking application after initial validation of parameters and state. The main processing is performed in the background so as not to block the application program's thread. This non- blocking approach is handy when the application needs to carry on processing while the MQTT action takes place.

For instance connecting to an MQTT server can take time, using the non-blocking connect method allows an application to display a busy indicator while the connect action takes place in the background. Non blocking methods are particularly useful in event oriented programs and graphical programs where invoking methods that take time to complete on the the main or GUI thread can cause problems. The non-blocking interface can also be used in blocking form.

There are two forms of non-blocking method:

IMqttToken token = asyncClient.method(params)

In this form the method returns a token that can be used to track the progress of the action (method). The method provides a waitForCompletion() method that once invoked will block until the action completes. Once completed there are method on the token that can be used to check if the action completed successfully or not.

For example to wait until a connect completes:

 IMqttToken conToken;
   conToken = asyncClient.client.connect(conToken);
... do some work...
   conToken.waitForCompletion();

To turn a method into a blocking invocation the following form can be used:

IMqttToken token;
token = asyncClient.method(parms).waitForCompletion();

IMqttToken token method(parms, Object userContext, IMqttActionListener callback)

In this form a callback is registered with the method. The callback will be notified when the action succeeds or fails. The callback is invoked on the thread managed by the MQTT client so it is important that processing is minimised in the callback. If not the operation of the MQTT client will be inhibited. For example to be notified (called back) when a connect completes:

IMqttToken conToken;
    conToken = asyncClient.connect("some context",new new MqttAsyncActionListener() {
                public void onSuccess(IMqttToken asyncActionToken) {
                        log("Connected");
                }

                public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
                        log ("connect failed" +exception);
                }
          });

An optional context object can be passed into the method which will then be made available in the callback. The context is stored by the MQTT client) in the token which is then returned to the invoker. The token is provided to the callback methods where the context can then be accessed.

To understand when the delivery of a message is complete either of the two methods above can be used to either wait on or be notified when the publish completes. An alternative is to use the MqttCallback.deliveryComplete(IMqttDeliveryToken) method which will also be notified when a message has been delivered to the requested quality of service.

Constant Summary collapse

MAX_MSG_SIZE =
268_435_456

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(server_uri, client_id, opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • server_uri (String)

    The server URL, e.g. 'tcp://localhost:1883'

  • client_id (String)

    The user client id


105
106
107
108
109
110
111
# File 'lib/paho/client.rb', line 105

def initialize(server_uri, client_id, opts = {})
  @opts = opts

  @client = Paho::Eclipse::MqttClient.new(server_uri,  client_id, nil)
rescue Java::OrgEclipsePahoClientMqttv3::MqttException => ex
  raise Paho::Exception.new(ex)
end

Class Method Details

.generate_client_idObject


98
99
100
# File 'lib/paho/client.rb', line 98

def generate_client_id
  Paho::Eclipse::MqttClient.generateClientId
end

Instance Method Details

#callback=(cb) ⇒ Object


125
126
127
# File 'lib/paho/client.rb', line 125

def callback=(cb)
  @client.setCallback(cb)
end

#client_idObject


86
# File 'lib/paho/client.rb', line 86

def_delegator :@client, :getClientId, :client_id

#closeObject

Close the client Releases all resource associated with the client. After the client has been closed it cannot be reused. For instance attempts to connect will fail.


116
117
118
# File 'lib/paho/client.rb', line 116

def close

end

#connect(options = nil) ⇒ Object


120
121
122
# File 'lib/paho/client.rb', line 120

def connect(options = nil)
  @client.connect(options)
end

#disconnect(opts = {}) ⇒ Object


130
131
132
# File 'lib/paho/client.rb', line 130

def disconnect(opts = {})

end

#disconnect!(quiesce_timeout = 30, disconnect_timeout = 10) ⇒ Object

Disconnects from the server forcibly to reset all the states.

Because the client is able to establish the TCP/IP connection to a none MQTT server and it will certainly fail to send the disconnect packet. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting and wait for a maximum of 10 seconds for sending the disconnect packet to server.

Parameters:

  • quiesce_timeout (Integer) (defaults to: 30)

    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.

  • disconnect_timeout (Integer) (defaults to: 10)

    The amount of time in milliseconds to allow send disconnect packet to server.


144
145
146
147
148
# File 'lib/paho/client.rb', line 144

def disconnect!(quiesce_timeout = 30, disconnect_timeout = 10)
  @client.disconnectForcibly(quiesce_timeout, disconnect_timeout)
rescue Java::OrgEclipsePahoClientMqttv3::MqttException => ex
  raise Paho::Exception.new(ex)
end

#server_uriObject


89
# File 'lib/paho/client.rb', line 89

def_delegator :@client, :getServerURI, :server_uri

#subscribe(topic, qos = Paho::Message::QOS) ⇒ Object


151
152
153
# File 'lib/paho/client.rb', line 151

def subscribe(topic, qos = Paho::Message::QOS)

end