org.eclipse.paho.client.mqttv3 源码研究

在线api传送门

描述

包含一个编程接口，使应用程序能够与 MQTT 服务器进行通信。

MQ 遥测传输 (MQTT) 是一种基于代理的轻量级发布/订阅消息传递协议，旨在开放、简单、轻量级且易于实现。这些特性使其非常适合在受限环境中使用，例如但不限于：

• 网络昂贵、带宽低或不可靠的地方，例如移动和 vsat 网络
• 在处理器、内存或电池有限的嵌入式或移动设备上运行时

协议的特点

• 发布/订阅消息模式，提供一对多的消息分发和应用程序的解耦
  与有效负载内容无关的消息传输
• 使用 TCP/IP 提供网络连接
• 使用 SSL/TLS 提供网络安全和信任
• 跨网络、客户端和服务器中断维护的消息传递的三种服务质量。
  • “最多一次”，根据底层 TCP/IP 网络的最大努力传递消息。可能会发生消息丢失或重复。例如，此级别可用于环境传感器数据，其中单个读数是否丢失并不重要，因为下一个读数将很快发布。
  • “至少一次”，确保消息到达但可能会出现重复。
  • “Exactly once”，保证消息只到达一次。例如，此级别可用于重复或丢失消息可能导致应用不正确费用的计费系统。
    即使网络连接中断，或者客户端或服务器在传递消息时停止，也可以满足消息传递的服务质量
• 很小的传输开销（固定长度的标头只有 2 个字节），并且协议交换最小化以减少网络流量
• 使用最后遗嘱和遗嘱功能通知相关方客户端异常断开连接的机制

操作客户端的基本手段

1. 创建MqttClientor 的实例MqttAsyncClient，提供 MQTT 服务器的地址和唯一的客户端标识符。
2. connect到服务器
3. 与服务器交换消息：
   publish messages到服务器，将 a 指定topic为服务器上的目标
   subscribe来一个topics。服务器会将它收到的关于这些主题的任何消息发送给客户端。当消息通过callback
4. disconnect从服务器。

关键概念

编程模型和协议等概念很小且易于使用。创建 MQTT 应用程序时要使用的关键概念包括：

1. 每个连接到 MQTT 服务器的客户端实例都必须具有唯一的客户端标识符。如果具有相同 ID 的客户端的第二个实例连接到服务器，则第一个实例将断开连接。

2. 为了使消息传递可靠并能够承受正常和异常的网络中断以及客户端和服务器中断，客户端必须在传递消息时使用持久存储来保存消息。这是使用基于文件的持久存储的默认情况 MqttDefaultFilePersistence。

3. 连接时的 cleansession 选项对客户端的操作有很大的影响。

如果设置为false：

• 即使网络、客户端或服务器出现故障，消息传递也将与发布消息时指定的服务质量相匹配

• 当客户端未连接时，服务器将代表客户端存储活动订阅的消息。服务器将在下次连接时将这些消息传递给客户端。

如果设置为true:

• 存储在客户端和与客户端相关的服务器上的任何状态都将在连接完全启动之前被清除。先前会话的订阅将被取消订阅，并且先前会话中仍在进行中的任何消息都将被删除。

• 当客户端由于应用程序请求断开连接或网络故障而断开连接时，与客户端相关的状态将被清除，就像在连接时一样。

• 如果在传递消息时保持连接，则仅将消息传递到发布时请求的服务质量

4. 订阅消息时，订阅可以是绝对主题或通配主题。
5. 取消订阅时，要取消订阅的主题必须与先前订阅中指定的主题匹配。
6. 有两个 MQTT 客户端库可供选择：

• MqttAsyncClient它提供了一个非阻塞接口，其中方法在请求的操作完成之前返回。可以通过以下几种方式监控操作的完成情况：
  对操作返回的令牌使用waitForCompletion 调用。这将阻塞直到操作完成。
  • 将 a 传递IMqttActionListener 给操作。操作完成后，侦听器将被回调。
  • 在客户端上设置一个MqttCallback。当消息到达、消息已传送到服务器以及与服务器的连接丢失时，它将被通知。
• MqttClientwhere 方法阻塞，直到操作完成。

7. 对于阻塞和非阻塞客户端，一些操作是异步的。这包括：

• 收到新消息的通知： messageArrived。
• 与服务器的连接已断开的通知： connectionLost。
• 消息已发送到服务器的通知： deliveryComplete。
  MqttCallback客户端通过在客户端上注册来注册对这些通知的兴趣

8. 有许多程序演示了编写 MQTT 应用程序的不同模式

• org.eclipse.paho.sample.mqttv3app.Sample使用阻塞客户端接口
• org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack使用带有回调的异步客户端，当操作完成时会收到通知
• org.eclipse.paho.sample.mqttv3app.SampleAsyncWait使用异步客户端并展示如何使用从每个操作返回的令牌来阻塞直到操作完成。

8. MqttConnectOptions可用于覆盖默认连接选项。这包括：

• 设置 cleansession 标志
• 指定客户端可以尝试连接的 MQTT 服务器列表
• 设置保活间隔
• 订立遗嘱
• 设置安全凭证

API

接口

Interface	Description
IMqttActionListener	当异步操作完成时，将通知此接口的实现者。
IMqttAsyncClient	使应用程序能够使用非阻塞方法与 MQTT 服务器通信.
IMqttClient	使应用程序能够使用阻塞方法与 MQTT 服务器通信.
IMqttDeliveryToken	提供用于跟踪消息传递的机制.
IMqttMessageListener	当消息到达时，将通知此接口的实现者.
IMqttToken	提供一种跟踪异步任务完成情况的机制.
MqttCallback	使应用程序能够在与客户端相关的异步事件发生时得到通知。
MqttCallbackExtended	扩展 MqttCallback 以允许新的回调而不破坏现有应用程序的 API.
MqttClientPersistence	表示持久性数据存储，用于在出站和入站消息在飞行时存储它们，从而能够传递到指定的 QoS.
MqttPersistable	表示用于传递要跨 MqttClientPersistence 接口持久化的数据的对象.
MqttPingSender	表示用于在每个保持活动间隔向 MQTT 代理发送 ping 数据包的对象。

类

Class	Description
BufferedMessage	BufferedMessage 包含一个 MqttWire 消息和令牌，它允许在客户端处于静止状态时缓冲消息和令牌
DisconnectedBufferOptions	包含一组选项，这些选项控制消息的脱机（或断开连接）缓冲行为
MqttAsyncClient	使用允许操作在后台运行的非阻塞方法与 MQTT 服务器通信的轻量级客户端。
MqttClient	轻量级客户端，用于使用阻塞直到操作完成的方法与 MQTT 服务器通信。
MqttConnectOptions	包含控制客户端如何连接到服务器的选项集.
MqttDeliveryToken	提供一种机制来跟踪消息的传递进度.
MqttMessage	MQTT 消息包含应用程序有效负载和指定如何传递消息的选项 该消息包括表示为字byte[] 的“有效负载”（消息的正文）.
MqttToken	提供一种机制来跟踪异步操作的完成情况.
MqttTopic	表示主题目标，用于发布/订阅消息.
TimerPingSender	默认 ping 发送方实现

异常类

Exception	Description
MqttException	如果与服务器通信发生错误则抛出.
MqttPersistenceException	如果在读取或写入持久性数据时出现问题，则持久性接口的实现者会抛出此异常.
MqttSecurityException	当客户端无权执行操作或安全配置有问题时抛出.