Interface MqttClient

public interface MqttClient
An MQTT client

  • Method Details

    • create

      static MqttClient create(Vertx vertx, MqttClientOptions options)
      Return an MQTT client instance
      Parameters:
      vertx - Vert.x instance
      options - MQTT client options
      Returns:
      MQTT client instance

    • create

      static MqttClient create(Vertx vertx)
      Return an MQTT client instance using the default options
      Parameters:
      vertx - Vert.x instance
      Returns:
      MQTT client instance

    • connect

      Future<MqttConnAckMessage> connect(int port, String host)
      Connects to an MQTT server calling connectHandler after connection
      Parameters:
      port - port of the MQTT server
      host - hostname/ip address of the MQTT server
      Returns:
      a future notified when the connect call ends

    • connect

      Future<MqttConnAckMessage> connect(int port, String host, String serverName)
      Connects to an MQTT server calling connectHandler after connection
      Parameters:
      port - port of the MQTT server
      host - hostname/ip address of the MQTT server
      serverName - the SNI server name
      Returns:
      a future notified when the connect call ends

    • connect

      Future<MqttConnAckMessage> connect(int port, String host, String serverName, Map<String,String> userProperties)
      Connects to an MQTT server calling connectHandler after connection
      Parameters:
      port - port of the MQTT server
      host - hostname/ip address of the MQTT server
      serverName - the SNI server name
      userProperties - Connect User Properties
      Returns:
      a future notified when the connect call ends

    • disconnect

      Future<Void> disconnect()
      Disconnects from the MQTT server
      Returns:
      a Future of the asynchronous result

    • disconnect

      Future<Void> disconnect(MqttDisconnectReasonCode code, MqttProperties properties)
      Disconnects from the MQTT server
      Parameters:
      code - reason code for the disconnect
      properties - MQTT properties
      Returns:
      a Future of the asynchronous result

    • publish

      Future<Integer> publish(String topic, Buffer payload, MqttQoS qosLevel, boolean isDup, boolean isRetain)
      Sends the PUBLISH message to the remote MQTT server
      Parameters:
      topic - topic on which the message is published
      payload - message payload
      qosLevel - QoS level
      isDup - if the message is a duplicate
      isRetain - if the message needs to be retained
      Returns:
      a Future completed after PUBLISH packet sent with packetid (not when QoS 0)

    • publish

      Future<Integer> publish(String topic, Buffer payload, MqttQoS qosLevel, boolean isDup, boolean isRetain, MqttProperties properties)
      Sends the PUBLISH message to the remote MQTT server with MQTT 5.0 properties
      Parameters:
      topic - topic on which the message is published
      payload - message payload
      qosLevel - QoS level
      isDup - if the message is a duplicate
      isRetain - if the message needs to be retained
      properties - MQTT 5.0 properties (e.g. message expiry, content type, response topic, user properties)
      Returns:
      a Future completed after PUBLISH packet sent with packetid (not when QoS 0)

    • publish

      Future<Integer> publish(int id, String topic, Buffer payload, MqttQoS qosLevel, boolean isDup, boolean isRetain)
      Sends the PUBLISH message to the remote MQTT server with a specific message ID
      Parameters:
      id - the message ID
      topic - topic on which the message is published
      payload - message payload
      qosLevel - QoS level
      isDup - if the message is a duplicate
      isRetain - if the message needs to be retained
      Returns:
      a Future completed after PUBLISH packet sent with packetid (not when QoS 0)

    • publishRelease

      Future<Void> publishRelease(int publishMessageId)
      Sends the PUBREL message to the remote MQTT server. This can be used when a PUBREL message expires
      Parameters:
      publishMessageId - identifier of the PUBLISH message to acknowledge
      Returns:
      a reference to this, so the API can be used fluently

    • publishCompletionHandler

      MqttClient publishCompletionHandler(Handler<Integer> publishCompletionHandler)
      Sets a handler which will be called each time the publishing of a message has been completed.

      For a message that has been published using

      • QoS 0 this means that the client has successfully sent the corresponding PUBLISH packet,
      • QoS 1 this means that a corresponding PUBACK has been received from the server,
      • QoS 2 this means that a corresponding PUBCOMP has been received from the server.
      Parameters:
      publishCompletionHandler - handler called with the packetId
      Returns:
      current MQTT client instance

    • publishAckMessageHandler

      MqttClient publishAckMessageHandler(Handler<MqttPubAckMessage> handler)
      Sets a handler which will be called each time a PUBACK is received from the server.

      MQTT 5.0: the handler receives the full typed message including reason code and properties. This handler fires alongside the existing publishCompletionHandler(Handler).

      Parameters:
      handler - handler called with the PUBACK message
      Returns:
      current MQTT client instance

    • publishRecMessageHandler

      MqttClient publishRecMessageHandler(Handler<MqttPubRecMessage> handler)
      Sets a handler which will be called each time a PUBREC is received from the server.

      MQTT 5.0: the handler receives the full typed message including reason code and properties, before the client sends PUBREL.

      Parameters:
      handler - handler called with the PUBREC message
      Returns:
      current MQTT client instance

    • publishCompMessageHandler

      MqttClient publishCompMessageHandler(Handler<MqttPubCompMessage> handler)
      Sets a handler which will be called each time a PUBCOMP is received from the server.

      MQTT 5.0: the handler receives the full typed message including reason code and properties. This handler fires alongside the existing publishCompletionHandler(Handler).

      Parameters:
      handler - handler called with the PUBCOMP message
      Returns:
      current MQTT client instance

    • publishCompletionExpirationHandler

      MqttClient publishCompletionExpirationHandler(Handler<Integer> publishCompletionExpirationHandler)
      Sets a handler which will be called when the client does not receive a PUBACK or PUBREC/PUBCOMP for a message published using QoS 1 or 2 respectively.

      The time to wait for an acknowledgement message can be configured using MqttClientOptions.setAckTimeout(int). If the client receives a PUBACK/PUBREC/PUBCOMP for a message after its completion has expired, the handler registered using publishCompletionUnknownPacketIdHandler(Handler) will be invoked.

      Note that this behavior is outside the scope of the MQTT 3.1.1 specification. The client's default behavior is therefore to wait forever for the server's corresponding acknowledgement.

      Parameters:
      publishCompletionExpirationHandler - the handler to call with the ID of the expired packet
      Returns:
      current MQTT client instance

    • publishAcknowledge

      Future<Void> publishAcknowledge(int publishMessageId, MqttPubAckReasonCode reasonCode, MqttProperties properties)
      Sends PUBACK packet to server
      Parameters:
      publishMessageId - identifier of the PUBLISH message to acknowledge
      reasonCode - reason code
      properties - MQTT properties
      Returns:
      a Future completed after PUBACK packet sent

    • publishReceived

      Future<Void> publishReceived(int publishMessageId, MqttPubRecReasonCode reasonCode, MqttProperties properties)
      Sends PUBREC packet to server
      Parameters:
      publishMessageId - identifier of the PUBLISH message to acknowledge
      reasonCode - reason code
      properties - MQTT properties
      Returns:
      a Future completed after PUBREC packet sent

    • publishRelease

      Future<Void> publishRelease(int publishMessageId, MqttPubRelReasonCode reasonCode, MqttProperties properties)
      Sends PUBREL packet to server
      Parameters:
      publishMessageId - identifier of the PUBLISH message to acknowledge
      reasonCode - reason code
      properties - MQTT properties
      Returns:
      a Future completed after PUBREL packet sent

    • publishComplete

      Future<Void> publishComplete(int publishMessageId, MqttPubCompReasonCode reasonCode, MqttProperties properties)
      Sends PUBCOMP packet to server
      Parameters:
      publishMessageId - identifier of the PUBLISH message to acknowledge
      reasonCode - reason code
      properties - MQTT properties
      Returns:
      a Future completed after PUBCOMP packet sent

    • publishCompletionUnknownPacketIdHandler

      MqttClient publishCompletionUnknownPacketIdHandler(Handler<Integer> publishCompletionPhantomHandler)
      Sets a handler which will be called when the client receives a PUBACK/PUBREC/PUBCOMP with an unknown packet ID.
      Parameters:
      publishCompletionPhantomHandler - the handler to call with the unknown packet ID
      Returns:
      current MQTT client instance

    • publishHandler

      MqttClient publishHandler(Handler<MqttPublishMessage> publishHandler)
      Sets handler which will be called each time server publish something to client
      Parameters:
      publishHandler - handler to call
      Returns:
      current MQTT client instance

    • subscribeCompletionHandler

      MqttClient subscribeCompletionHandler(Handler<MqttSubAckMessage> subscribeCompletionHandler)
      Sets handler which will be called after SUBACK packet receiving
      Parameters:
      subscribeCompletionHandler - handler to call. List inside is a granted QoS array
      Returns:
      current MQTT client instance

    • subscribe

      Future<Integer> subscribe(String topic, int qos)
      Subscribes to the topic with a specified QoS level
      Parameters:
      topic - topic you subscribe on
      qos - QoS level
      Returns:
      a Future completed after SUBSCRIBE packet sent with packetid

    • subscribe

      Future<Integer> subscribe(Map<String,Integer> topics)
      Subscribes to the topics with related QoS levels
      Parameters:
      topics - topics and related QoS levels to subscribe to
      Returns:
      a Future completed after SUBSCRIBE packet sent with packetid

    • subscribe

      Future<Integer> subscribe(Map<String,Integer> topics, MqttProperties properties)
      Subscribes to the topics with related QoS levels
      Parameters:
      topics - topics and related QoS levels to subscribe to
      properties - MQTT properties
      Returns:
      a Future completed after SUBSCRIBE packet sent with packetid

    • subscribe

      Future<Integer> subscribe(List<MqttTopicSubscription> subscriptions, MqttProperties properties)
      Subscribes to a list of topics with MQTT 5.0 subscription options (No Local, Retain As Published, Retain Handling) and optional properties. Each MqttTopicSubscription carries the topic filter and a MqttSubscriptionOption that encodes QoS plus the v5 options.
      Parameters:
      subscriptions - list of topic subscriptions with options
      properties - MQTT properties (e.g. Subscription Identifier)
      Returns:
      a Future completed after SUBSCRIBE packet sent with packetid

    • unsubscribeCompletionHandler

      MqttClient unsubscribeCompletionHandler(Handler<Integer> unsubscribeCompletionHandler)
      Sets handler which will be called after UNSUBACK packet receiving
      Parameters:
      unsubscribeCompletionHandler - handler to call with the packetid
      Returns:
      current MQTT client instance

    • unsubscribeCompletionMessageHandler

      MqttClient unsubscribeCompletionMessageHandler(Handler<MqttUnsubAckMessage> unsubscribeCompletionMessageHandler)
      Sets handler which will be called after UNSUBACK packet receiving
      Parameters:
      unsubscribeCompletionMessageHandler - handler to call with the unsubscribe message
      Returns:
      current MQTT client instance

    • unsubscribe

      Future<Integer> unsubscribe(String topic)
      Unsubscribe from receiving messages on given topic
      Parameters:
      topic - Topic you want to unsubscribe from
      Returns:
      a Future completed after UNSUBSCRIBE packet sent with packetid

    • unsubscribe

      Future<Integer> unsubscribe(List<String> topics)
      Unsubscribe from receiving messages on given list of topic
      Parameters:
      topics - list of topics you want to unsubscribe from
      Returns:
      a Future completed after UNSUBSCRIBE packet sent with packetid

    • unsubscribe

      Future<Integer> unsubscribe(List<String> topics, MqttProperties properties)
      Unsubscribe from receiving messages on given list of topic
      Parameters:
      topics - list of topics you want to unsubscribe from
      properties - MQTT properties
      Returns:
      a Future completed after UNSUBSCRIBE packet sent with packetid

    • pingResponseHandler

      MqttClient pingResponseHandler(Handler<Void> pingResponseHandler)
      Sets handler which will be called after PINGRESP packet receiving
      Parameters:
      pingResponseHandler - handler to call
      Returns:
      current MQTT client instance

    • exceptionHandler

      MqttClient exceptionHandler(Handler<Throwable> handler)
      Set an exception handler for the client, that will be called when an error happens in internal netty structures. io.netty.handler.codec.DecoderException can be one of the cause
      Parameters:
      handler - the exception handler
      Returns:
      current MQTT client instance

    • disconnectMessageHandler

      MqttClient disconnectMessageHandler(Handler<MqttDisconnectMessage> handler)
      Sets a handler that will be called when the server sends a DISCONNECT packet.

      This fires before closeHandler(Handler) and only for server-initiated disconnects (not when the client calls disconnect()). The handler receives the reason code and properties from the server's DISCONNECT packet.

      Parameters:
      handler - handler to call with the disconnect message
      Returns:
      current MQTT client instance

    • authenticationExchangeHandler

      MqttClient authenticationExchangeHandler(Handler<MqttAuthenticationExchangeMessage> handler)
      Sets a handler that will be called when the server sends an AUTH packet (MQTT 5.0 Enhanced Authentication, see §3.15).

      The handler receives the reason code, the authentication method, the authentication data and the full set of MQTT properties from the server's AUTH packet. The user can then reply with authenticationExchange(MqttAuthenticateReasonCode, MqttProperties).

      Parameters:
      handler - handler to call with the AUTH message
      Returns:
      current MQTT client instance

    • authenticationExchange

      Future<Void> authenticationExchange(MqttAuthenticateReasonCode reasonCode, MqttProperties properties)
      Send an AUTH packet to the server.

      Used to continue an Enhanced Authentication exchange started in CONNECT, or to request re-authentication on an already-established session. Available only when the client is configured for MQTT 5.0.

      Parameters:
      reasonCode - authenticate reason code
      properties - MQTT properties (typically AUTHENTICATION_METHOD and AUTHENTICATION_DATA)
      Returns:
      a Future completed when the packet has been written

    • closeHandler

      MqttClient closeHandler(Handler<Void> closeHandler)
      Set a handler that will be called when the connection with server is closed
      Parameters:
      closeHandler - handler to call
      Returns:
      current MQTT client instance

    • ping

      MqttClient ping()
      This method is needed by the client in order to avoid server closes the connection due to the keep alive timeout if client has no messages to send
      Returns:
      current MQTT client instance

    • pause

      void pause()
      Pause the reading channel, so no new byte are read from the server. Available after connection is established.

      This simply delegates to NetSocket.pause().

    • resume

      void resume()
      Resume the reading channel. see pause() Available after connection is established.

      This simply delegates to NetSocket.resume().

    • clientId

      String clientId()
      Returns:
      the client identifier

    • isConnected

      boolean isConnected()
      Returns:
      if the connection between client and remote server is established/open