Introduction to HiveMQ MQTT Client

1. Introduction

When building Java applications that use MQTT, we need its client library that’s easy to use and well-suited for production. The HiveMQ MQTT Client, developed and maintained by the HiveMQ team, is a modern Java library that supports both MQTT 3.1.1 and MQTT 5.

The client provides multiple API styles, including blocking, asynchronous, and reactive, to support different programming models. Moreover, it exposes a fluent, builder-based API for configuring connections, subscriptions, and publish operations when interacting with an MQTT broker.

In this tutorial, we’ll demonstrate the library’s basic usage. Specifically, we’ll connect to a public MQTT broker, subscribe to a topic, publish a message, and verify message delivery using an integration test.

2. Project Setup

Before we create clients, we have to add the HiveMQ MQTT Client dependency to our project:

<dependency>
    <groupId>com.hivemq</groupId>
    <artifactId>hivemq-mqtt-client</artifactId>
    <version>1.3.12</version>
</dependency>

The latest version of the library module is available on Maven Central.

With the dependency in place, we can create an MQTT client and connect to a publicly available MQTT broker at broker.hivemq.com:1883.

3. Creating the Clients

To illustrate the different API styles of the HiveMQ MQTT Client, we’ll create two clients. We’ll use an asynchronous client to subscribe to topics and receive messages, and a blocking client to publish messages synchronously.

3.1. Creating an Asynchronous Client

First, let’s start with an asynchronous client that subscribes to topics and handles incoming messages in a non-blocking, event-driven way. This client type allows us to register callbacks that are invoked whenever a message arrives.

We’ll create it using the fluent builder API:

Mqtt5AsyncClient subscriber = Mqtt5Client.builder()
  .identifier("baeldung-sub-" + UUID.randomUUID())
  .serverHost(PUBLIC_BROKER_HOST)
  .serverPort(PUBLIC_BROKER_PORT)
  .buildAsync();

With a unique client identifier and the MQTT broker address configured, buildAsync() creates an asynchronous MQTT 5 client instance. Later, we’ll use this client to connect to the broker and subscribe to a topic.

3.2. Creating a Blocking Client

In contrast, we’ll use a blocking client for publishing messages. The blocking API executes operations synchronously, which works well when we don’t need to react to incoming messages.

Similarly, we’ll create the blocking client using the builder API:

Mqtt5BlockingClient publisher = Mqtt5Client.builder()
  .identifier("baeldung-pub-" + UUID.randomUUID())
  .serverHost(PUBLIC_BROKER_HOST)
  .serverPort(PUBLIC_BROKER_PORT)
  .buildBlocking();

After configuring a unique client identifier and the broker address, the call to buildBlocking() creates an MQTT 5 client instance. This client provides synchronous methods for connecting to the broker and publishing messages.

4. Connecting, Subscribing, and Publishing

Now that we have both clients, we can connect to the publicly available broker, subscribe to a topic, and publish a message.

4.1. Connecting to the Broker

First, we’ll connect both clients:

subscriber.connect()
  .join();
publisher.connect();

The asynchronous client returns a CompletableFuture when connecting, so we’ll wait for the connection to complete using join(). On the other hand, the blocking client connects synchronously and returns only after the connection is established.

4.2. Subscribing to a Topic

Next, we’ll register a handler on the asynchronous client to process incoming publishes. We’ll use a latch to let our test wait until the subscriber receives the message:

CountDownLatch latch = new CountDownLatch(1);
AtomicReference<String> receivedMessage = new AtomicReference<>();

subscriber.publishes(MqttGlobalPublishFilter.SUBSCRIBED, publish -> {
    String message = new String(publish.getPayloadAsBytes(), StandardCharsets.UTF_8);
    receivedMessage.set(message);
    latch.countDown();
});

The handler defines the message processing logic. When a message arrives, the callback extracts the payload and signals the test thread to continue.

With the handler in place, we can subscribe to our topic:

subscriber.subscribeWith()
  .topicFilter(topic)
  .send()
  .join();

This tells the broker which topic the client wants to receive messages from and waits for confirmation.

4.3. Publishing a Message

Finally, we’ll publish a message using the blocking client:

String payload = "Hello from Baeldung";

publisher.publishWith()
  .topic(topic)
  .payload(payload.getBytes(StandardCharsets.UTF_8))
  .send();

At this point, the broker forwards the published message to all subscribers of the topic. In our case, the callback registered on the asynchronous client receives the message and stores the payload.

5. Verifying Message Delivery

Lastly, to verify that the subscriber received the published message, we’ll add assertions in the test. After the subscriber callback runs, the test checks that the received payload matches the published value:

assertTrue(latch.await(2, TimeUnit.SECONDS));
assertEquals(payload, receivedMessage.get());

After the verification, we’ll disconnect both clients to close the connections to the broker and release resources:

publisher.disconnect();
subscriber.disconnect()
  .join();

As a result, disconnecting the clients releases network resources and completes the client lifecycle.

6. Conclusion

In this article, we introduced the HiveMQ MQTT Client and demonstrated how to connect to a public MQTT broker, subscribe to a topic, publish a message, and verify message delivery using an integration test.

Depending on the use case, developers can choose between blocking APIs for synchronous workflows, asynchronous APIs for event-driven applications, or reactive APIs for stream-based processing. This flexibility makes the HiveMQ MQTT Client suitable for a variety of Java applications.