Introduction to HiveMQ MQTT Client
When building Java applications that use MQTT, developers need a library that balances simplicity with production-grade reliability. The HiveMQ MQTT Client, developed by the HiveMQ team, offers a modern solution supporting both MQTT 3.1.1 and MQTT 5. Its flexible API styles—blocking, asynchronous, and reactive—make it adaptable to various programming models.
This guide demonstrates core functionality: connecting to a public MQTT broker, subscribing to topics, publishing messages, and verifying delivery. By the end, you’ll understand how to integrate this library into your IoT or messaging projects.
Getting Started: Project Setup
To begin, add the HiveMQ MQTT Client dependency to your Maven project:
<dependency>
<groupId>com.hivemq</groupId>
<artifactId>hivemq-mqtt-client</artifactId>
<version>1.3.12</version>
</dependency>The latest version is available on Maven Central. This dependency enables access to the library’s fluent builder API for configuring connections and operations.
Creating MQTT Clients
The HiveMQ library supports two primary client types for different use cases:
Asynchronous Client for Message Handling
For non-blocking message reception, create an asynchronous client:
Mqtt5AsyncClient subscriber = Mqtt5Client.builder()
.identifier("baeldung-sub-" + UUID.randomUUID())
.serverHost("broker.hivemq.com")
.serverPort(1883)
.buildAsync();This client uses a unique identifier and connects to the public HiveMQ broker. The buildAsync() method creates an MQTT 5 client instance ready for event-driven message handling.
Blocking Client for Synchronous Operations
For straightforward message publishing, use a blocking client:
Mqtt5BlockingClient publisher = Mqtt5Client.builder()
.identifier("baeldung-pub-" + UUID.randomUUID())
.serverHost("broker.hivemq.com")
.serverPort(1883)
.buildBlocking();The buildBlocking() method creates a synchronous client ideal for simple publish operations without callback handling.
Connecting and Managing Messages
Establishing Broker Connections
Connect both clients to the public broker:
subscriber.connect().join();
publisher.connect();The asynchronous client uses join() to wait for connection completion, while the blocking client connects synchronously.
Subscribing and Receiving Messages
Subscribe to a topic using the asynchronous client:
subscriber.subscribeWith()
.topicFilter("test/topic")
.callback(message -> {
System.out.println("Received: " + new String(message.getPayload()));
})
.send();This code registers a callback to handle incoming messages on the “test/topic” channel.
Publishing Messages
Publish a message using the blocking client:
publisher.publishWith()
.topic("test/topic")
.payload("Hello MQTT 5".getBytes())
.send();The send() method ensures synchronous delivery of the message to the specified topic.
Conclusion and Next Steps
The HiveMQ MQTT Client simplifies MQTT integration in Java applications with its flexible API and robust feature set. By combining asynchronous and blocking clients, developers can build scalable IoT solutions or real-time messaging systems.
Ready to deepen your MQTT expertise? Explore our MQTT 5 Deep Dive eBook to master advanced topics like QoS levels, retained messages, and secure connections. Start building smarter IoT applications today!
