MQTT Client Library Encyclopedia - HiveMQ MQTT Client
Written by Clive Jevons
Category: MQTT MQTT Client Library
Published: February 25, 2019
|HiveMQ MQTT Client|
|License||Apache License 2.0|
|API Style||Synchronous, Asynchronous and Reactive|
The HiveMQ MQTT Client library was created in order to provide a fast, low-overhead, high-throughput and modern MQTT library for Java by building on modern frameworks like Netty for handling networking and RxJava for handling the asynchronous streaming of messages. It was created with backend applications in mind, but can be used in any Java based project.
The library provides three distinct flavours of API: blocking, asynchronous and reactive. This means you can choose a programming style which best meets your use-case. For example, for a very simple application which just starts up, sends some messages in order and shuts down again, the blocking API fits very well. For backend applications the asynchronous API will fit for most scenarios. If you want full access to all of the features the library provides, then the reactive API is the way to go.
Another very interesting feature of the HiveMQ MQTT Client is its backpressure handling, which can be used in conjunction with MQTT 5 brokers in order to communicate that the incoming load is to high and ask the producers to throttle their output back, for example.
|Offline Message Buffering|
The following is a quick summary of the basic usage of the asynchronous API with a MQTT 3 broker. The full documentation can be found here: https://hivemq.github.io/hivemq-mqtt-client
The HiveMQ MQTT Client library is available as a Maven artifact, so the easiest way to include it in your project is by referencing it in your dependencies. In gradle this would be:
Creating the Client
The HiveMQ MQTT Client API is often based around a builder pattern and a fluent API based approach. Here’s how that looks when building the client:
As you can probably see from the method names, you end up specifying which version of MQTT you want to use as well as which style of API you want to use while you are building the client. However, you can later transform the client to any of the other API styles by using the methods
toBlocking as needed.
Once we’ve created the client, we can trigger a connect to the broker and also define callbacks to handle success and error cases when the connection is completed.
As the inline comments in the code example suggest, the completion callback can be used to handle connection failures, e.g. logging the error, and also a successful connection, e.g. subscribe to some topics or start publishing your own messages.
Connecting with Authentication
This example shows how to provide simple authentication credentials:
Connecting with Will
Similar to the way you connect with authentication, the fluent API provides the possibility of specifying the Will:
In order to build and execute a publish you would use code similar to this:
Adding a callback to handle the completion of the publish is entirely optional and will depend on your use-case.
Publish retained message
.retain(true) when you’re building the publish in order to have it be retained.
When creating a subscription, you provide a callback which is used for each incoming message via the
.callback(...) builder method, and you can optionally also provide a callback on the returned completable future in order to handle the completion of the actual subscription (using
To unsubscribe from a topic, simply call:
You can optionally also use, e.g.,
whenComplete on the returned completable future in order to handle the completion of the unsubscribe operation.
disconnect() on the client object created previously.
SSL / TLS
In order to use SSL / TLS for connecting to the broker, you simply specify its usage while building the client. The simplest way is to use the default config:
But you can also customise the configuration. The following shows providing custom key manager and trust manager factories: