Skip to content

Latest commit

 

History

History
748 lines (598 loc) · 24.6 KB

README.md

File metadata and controls

748 lines (598 loc) · 24.6 KB
Raw

HiveMQ MQTT Client

Maven Central javadoc GitHub Workflow Status (branch)

MQTT 5.0 and 3.1.1 compatible and feature-rich high-performance Java client library with different API flavours and backpressure support.

Features

  • All MQTT 3.1.1 and MQTT 5.0 features
  • API flavors:
    • Reactive: Reactive Streams compatible, RxJava and Reactor APIs available
    • Asynchronous API: futures and callbacks
    • Blocking API: for quick start and testing
    • Switch flexibly between flavours and use them concurrently
    • Flavours are clearly separated but have a consistent API style
  • Backpressure support:
    • QoS 1 and 2
    • QoS 0 (dropping incoming messages, if necessary)
    • Bringing MQTT flow control and reactive pull backpressure together
  • Transports:
    • TCP
    • SSL/TLS
      • All TLS versions up to TLS 1.3 are supported
      • TLS mutual authentication
      • TLS Server Name Indication (SNI)
      • TLS Session Resumption
      • Default and customizable hostname verification
    • WebSocket, Secure WebSocket
    • Proxy: SOCKS4, SOCKS5, HTTP CONNECT
    • All possible combinations
  • Automatic and configurable thread management
  • Automatic and configurable reconnect handling and message redelivery
  • Automatic and configurable resubscribe if the session expired
  • Manual message acknowledgment
    • Selectively enable manual acknowledgment for specific streams
    • Acknowledge messages that are emitted to multiple streams independently per stream (the client aggregates the acknowledgments before sending MQTT acknowledgments)
    • Order of manual acknowledgment does not matter (the client automatically ensures the order of MQTT acknowledgments for 100% compatibility with the MQTT specification)
  • Lifecycle listeners
    • When connected
    • When disconnected or connection failed
  • MQTT 5 specific:
    • Pluggable Enhanced Authentication support (additional to MQTT specification: server-triggered re-authentication)
    • Automatic Topic Alias mapping
    • Interceptors for QoS flows

Users

BMW CarIT    joynr    openHAB    Eclipse Ditto    Open Smart Grid Platform    CorreoMQTT    HiveMQ Spring Boot Starter    HiveMQ Spring Boot Starter    HiveMQ Spring Boot Starter

If you use the HiveMQ MQTT Client in a project that is not listed here, feel free to open an issue or pull request.

How to use

Java 8 or higher is required.

Dependency

Gradle

If you use Gradle, just include the following inside your build.gradle(.kts) file.

dependencies {
  implementation("com.hivemq:hivemq-mqtt-client:1.3.0")
}

For optional features you can choose to include additional modules:

dependencies {
  implementation(platform("com.hivemq:hivemq-mqtt-client-websocket:1.3.0"))
  implementation(platform("com.hivemq:hivemq-mqtt-client-proxy:1.3.0"))
  implementation(platform("com.hivemq:hivemq-mqtt-client-epoll:1.3.0"))
  implementation("com.hivemq:hivemq-mqtt-client-reactor:1.3.0")
}

Maven

If you use Maven, just include the following inside your pom.xml file.

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client</artifactId>
            <version>1.3.0</version>
        </dependency>
    </dependencies>
    ...
</project>

NOTE: You have to set the compiler version to 1.8 or higher.

<project>
    ...
    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
    ...
</project>

For optional features you can choose to include additional modules:

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client-websocket</artifactId>
            <version>1.3.0</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client-proxy</artifactId>
            <version>1.3.0</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client-epoll</artifactId>
            <version>1.3.0</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client-reactor</artifactId>
            <version>1.3.0</version>
        </dependency>
    </dependencies>
    ...
</project>

Shaded version

If you are experiencing problems with transitive dependencies, you can try the shaded version. This version packs the transitive dependencies which are only used internal under a different package name. The shaded version includes the websocket, proxy and epoll modules. To use the shaded version just append -shaded to the artifact name.

Gradle

dependencies {
  implementation("com.hivemq:hivemq-mqtt-client-shaded:1.3.0")
}

Maven

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>com.hivemq</groupId>
            <artifactId>hivemq-mqtt-client-shaded</artifactId>
            <version>1.3.0</version>
        </dependency>
    </dependencies>
    ...
</project>

Snapshots

Snapshots can be obtained using JitPack.

Gradle

repositories {
  ...
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation("com.github.hivemq.hivemq-mqtt-client:hivemq-mqtt-client:develop-SNAPSHOT")

  // snapshots for optional modules
  implementation(platform("com.github.hivemq.hivemq-mqtt-client:hivemq-mqtt-client-websocket:develop-SNAPSHOT"))
  implementation(platform("com.github.hivemq.hivemq-mqtt-client:hivemq-mqtt-client-proxy:develop-SNAPSHOT"))
  implementation(platform("com.github.hivemq.hivemq-mqtt-client:hivemq-mqtt-client-epoll:develop-SNAPSHOT"))
  implementation("com.github.hivemq.hivemq-mqtt-client:hivemq-mqtt-client-reactor:develop-SNAPSHOT")
}

Maven

<project>
    ...
    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>
    
    <dependencies>
        <dependency>
            <groupId>com.github.hivemq.hivemq-mqtt-client</groupId>
            <artifactId>hivemq-mqtt-client</artifactId>
            <version>develop-SNAPSHOT</version>
        </dependency>
    </dependencies>

    <!-- snapshots for optional modules -->
    <dependencies>
        <dependency>
            <groupId>com.github.hivemq.hivemq-mqtt-client</groupId>
            <artifactId>hivemq-mqtt-client-websocket</artifactId>
            <version>develop-SNAPSHOT</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.github.hivemq.hivemq-mqtt-client</groupId>
            <artifactId>hivemq-mqtt-client-proxy</artifactId>
            <version>develop-SNAPSHOT</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.github.hivemq.hivemq-mqtt-client</groupId>
            <artifactId>hivemq-mqtt-client-epoll</artifactId>
            <version>develop-SNAPSHOT</version>
            <type>pom</type>
        </dependency>
    </dependencies>
    <dependencies>
        <dependency>
            <groupId>com.github.hivemq.hivemq-mqtt-client</groupId>
            <artifactId>hivemq-mqtt-client-reactor</artifactId>
            <version>develop-SNAPSHOT</version>
        </dependency>
    </dependencies>
    ...
</project>

Change the artifact name to hivemq-mqtt-client-shaded to get snapshots of the shaded version.

JitPack works for all branches and also specific commits. Just specify <branch>-SNAPSHOT or the first 10 digits of the commit id in the version.

General principles

  • API and implementation are clearly separated. All classes inside internal packages must not be used directly.
  • The API is mostly fluent and uses fluent builders to create clients, configurations and messages.
  • The API is designed to be consistent:
    • The same principles are used throughout the library.
    • The MQTT 3 and 5 interfaces are as consistent as possible with only version-specific differences.

Creation of clients

Base classes: Mqtt3Client, Mqtt5Client

Mqtt5Client client = MqttClient.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .useMqttVersion5()
        .build();
Mqtt3Client client = MqttClient.builder()...useMqttVersion3().build();

Or if the version is known upfront:

Mqtt5Client client = Mqtt5Client.builder()...build();
Mqtt3Client client = Mqtt3Client.builder()...build();

For each API style exists a specific build...() method.

API flavours

Each API style has its own interface to separate them clearly. At any time it is possible to switch the API style.

Blocking API

  • Builder method: buildBlocking()
  • Switch method: client.toBlocking()

Examples

Subscribe example
final Mqtt5BlockingClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildBlocking();

client.connect();

try (final Mqtt5Publishes publishes = client.publishes(MqttGlobalPublishFilter.ALL)) {

    client.subscribeWith().topicFilter("test/topic").qos(MqttQos.AT_LEAST_ONCE).send();

    publishes.receive(1, TimeUnit.SECONDS).ifPresent(System.out::println);
    publishes.receive(100, TimeUnit.MILLISECONDS).ifPresent(System.out::println);

} finally {
    client.disconnect();
}
Publish example
Mqtt5BlockingClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildBlocking();

client.connect();
client.publishWith().topic("test/topic").qos(MqttQos.AT_LEAST_ONCE).payload("1".getBytes()).send();
client.disconnect();

Connect

client.connect();

Or with customized properties of the Connect message:

client.connectWith().keepAlive(10).send();

Or with pre-built Connect message:

Mqtt5Connect connectMessage = Mqtt5Connect.builder().keepAlive(10).build();
client.connect(connectMessage);

Publish

client.publishWith()
        .topic("test/topic")
        .qos(MqttQos.AT_LEAST_ONCE)
        .payload("payload".getBytes())
        .send();

Or with pre-built Publish message:

Mqtt5Publish publishMessage = Mqtt5Publish.builder()
        .topic("test/topic")
        .qos(MqttQos.AT_LEAST_ONCE)
        .payload("payload".getBytes())
        .build();
client.publish(publishMessage);

Subscribe

client.subscribeWith().topicFilter("test/topic").qos(MqttQos.EXACTLY_ONCE).send();

Or with pre-built Subscribe message:

Mqtt5Subscribe subscribeMessage = Mqtt5Subscribe.builder()
        .topicFilter("test/topic")
        .qos(MqttQos.EXACTLY_ONCE)
        .build();
client.subscribe(subscribeMessage);

Unsubscribe

client.unsubscribeWith().topicFilter("test/topic").send();

Or with pre-built Unsubscribe message:

Mqtt5Unsubscribe unsubscribeMessage = Mqtt5Unsubscribe.builder().topicFilter("test/topic").build();
client.unsubscribe(unsubscribeMessage);

Consume messages

try (Mqtt5BlockingClient.Mqtt5Publishes publishes = client.publishes(MqttGlobalPublishFilter.ALL)) {
    Mqtt5Publish publishMessage = publishes.receive();
    // or with timeout
    Optional<Mqtt5Publish> publishMessage = publishes.receive(10, TimeUnit.SECONDS);
    // or without blocking
    Optional<Mqtt5Publish> publishMessage = publishes.receiveNow();
}

publishes must be called before subscribe to ensure no message is lost. It can be called before connect to receive messages of a previous session.

Disconnect

client.disconnect();

Or with customized properties of the DISCONNECT message (only MQTT 5):

client.disconnectWith().reasonString("test").send();

Or with pre-built Disconnect message (only MQTT 5):

Mqtt5Disconnect disconnectMessage = Mqtt5Disconnect.builder().reasonString("test").build();
client.disconnect(disconnectMessage);

Reauth (only MQTT 5)

client.reauth();

Async API

  • Builder method: buildAsync()
  • Switch method: client.toAsync()

Examples

Subscribe example
Mqtt5BlockingClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildBlocking();

client.connect();

client.toAsync().subscribeWith()
        .topicFilter("test/topic")
        .qos(MqttQos.AT_LEAST_ONCE)
        .callback(System.out::println)
        .send();
Publish example
Mqtt5AsyncClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildAsync();

client.connect()
        .thenCompose(connAck -> client.publishWith().topic("test/topic").payload("1".getBytes()).send())
        .thenCompose(publishResult -> client.disconnect());

Connect

connect(), connectWith() and connect(Mqtt3/5Connect) method calls are analog to the Blocking API but return CompletableFuture.

Publish

publishWith() and publish(Mqtt3/5Publish) method calls are analog to the Blocking API but return CompletableFuture.

Subscribe

subscribeWith() and subscribe(Mqtt3/5Subscribe) method calls are analog to the Blocking API but return CompletableFuture.

Additionally messages can be consumed per subscribe:

client.subscribeWith()
        .topicFilter("test/topic")
        .qos(MqttQos.EXACTLY_ONCE)
        .callback(System.out::println)
        .executor(executor) // optional
        .send();

Or with pre-built Subscribe message:

Mqtt5Subscribe subscribeMessage = Mqtt5Subscribe.builder()
        .topicFilter("test/topic")
        .qos(MqttQos.EXACTLY_ONCE)
        .build();
client.subscribe(subscribeMessage, System.out::println);
client.subscribe(subscribeMessage, System.out::println, executor);

Unsubscribe

unsubscribeWith() and unsubscribe(Mqtt3/5Unsubscribe) method calls are analog to the Blocking API but return CompletableFuture.

Consume messages

Messages can either be consumed per subscribe (described above) or globally:

client.publishes(MqttGlobalPublishFilter.ALL, System.out::println);

Or with executing the callback on a specified executor:

client.publishes(MqttGlobalPublishFilter.ALL, System.out::println, executor);

publishes must be called before subscribe to ensure no message is lost. It can be called before connect to receive messages of a previous session.

Disconnect

disconnect(), disconnectWith() and disconnect(Mqtt5Disconnect) method calls are analog to the Blocking API but return CompletableFuture.

Reauth (only MQTT 5)

reauth() method call is analog to the Blocking API but returns CompletableFuture.

Reactive API

  • Builder method: buildRx()
  • Switch method: client.toRx()

Examples

Subscribe example
Mqtt5RxClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildRx();

// As we use the reactive API, the following line does not connect yet, but returns a reactive type.
// e.g. Single is something like a lazy and reusable future. Think of it as a source for the ConnAck message.
Single<Mqtt5ConnAck> connAckSingle = client.connect();

// Same here: the following line does not subscribe yet, but returns a reactive type.
// FlowableWithSingle is a combination of the single SubAck message and a Flowable of Publish messages.
// A Flowable is an asynchronous stream that enables backpressure from the application over the client to the broker.
FlowableWithSingle<Mqtt5Publish, Mqtt5SubAck> subAckAndMatchingPublishes = client.subscribeStreamWith()
        .topicFilter("a/b/c").qos(MqttQos.AT_LEAST_ONCE)
        .addSubscription().topicFilter("a/b/c/d").qos(MqttQos.EXACTLY_ONCE).applySubscription()
        .applySubscribe();

// The reactive types offer many operators that will not be covered here.
// Here we register callbacks to print messages when we received the CONNACK, SUBACK and matching PUBLISH messages.
Completable connectScenario = connAckSingle
        .doOnSuccess(connAck -> System.out.println("Connected, " + connAck.getReasonCode()))
        .doOnError(throwable -> System.out.println("Connection failed, " + throwable.getMessage()))
        .ignoreElement();

Completable subscribeScenario = subAckAndMatchingPublishes
        .doOnSingle(subAck -> System.out.println("Subscribed, " + subAck.getReasonCodes()))
        .doOnNext(publish -> System.out.println(
                "Received publish" + ", topic: " + publish.getTopic() + ", QoS: " + publish.getQos() +
                        ", payload: " + new String(publish.getPayloadAsBytes())))
        .ignoreElements();

// Reactive types can be easily and flexibly combined
connectScenario.andThen(subscribeScenario).blockingAwait();
Publish example
Mqtt5RxClient client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker.hivemq.com")
        .buildRx();

// As we use the reactive API, the following line does not connect yet, but returns a reactive type.
Completable connectScenario = client.connect()
        .doOnSuccess(connAck -> System.out.println("Connected, " + connAck.getReasonCode()))
        .doOnError(throwable -> System.out.println("Connection failed, " + throwable.getMessage()))
        .ignoreElement();

// Fake a stream of Publish messages with an incrementing number in the payload
Flowable<Mqtt5Publish> messagesToPublish = Flowable.range(0, 10_000)
        .map(i -> Mqtt5Publish.builder()
                .topic("a/b/c")
                .qos(MqttQos.AT_LEAST_ONCE)
                .payload(("test " + i).getBytes())
                .build())
        // Emit 1 message only every 100 milliseconds
        .zipWith(Flowable.interval(100, TimeUnit.MILLISECONDS), (publish, i) -> publish);

// As we use the reactive API, the following line does not publish yet, but returns a reactive type.
Completable publishScenario = client.publish(messagesToPublish)
        .doOnNext(publishResult -> System.out.println(
                "Publish acknowledged: " + new String(publishResult.getPublish().getPayloadAsBytes())))
        .ignoreElements();

// As we use the reactive API, the following line does not disconnect yet, but returns a reactive type.
Completable disconnectScenario = client.disconnect().doOnComplete(() -> System.out.println("Disconnected"));

// Reactive types can be easily and flexibly combined
connectScenario.andThen(publishScenario).andThen(disconnectScenario).blockingAwait();

Connect

connect(), connectWith() and connect(Mqtt3/5Connect) method calls are analog to the Async and Blocking API but return Single<ConnAck>.

Publish

publish takes a reactive stream of Publish messages (Flowable) and returns a reactive stream of Publish results (Flowable).

The Reactive API is usually not used for publishing single messages. Nevertheless it is possible with the following code.

Single<Mqtt5PublishResult> result =
        client.publish(Flowable.just(Mqtt5Publish.builder()
                .topic("test/topic")
                .qos(MqttQos.AT_LEAST_ONCE)
                .payload("payload".getBytes())
                .build())).singleOrError();

Subscribe

subscribeWith() and subscribe(Mqtt3/5Subscribe) method calls are analog to the Async and Blocking API but return Single<SubAck>.

Additionally messages can be consumed per subscribe:

Flowable<Mqtt5Publish> result =
        client.subscribeStreamWith()
                .topicFilter("test/topic")
                .qos(MqttQos.EXACTLY_ONCE)
                .applySubscribe()
                .doOnSingle(subAck -> System.out.println("subscribed"))
                .doOnNext(publish -> System.out.println("received publish"));

Or with pre-built Subscribe message:

Mqtt5Subscribe subscribeMessage = Mqtt5Subscribe.builder()
        .topicFilter("test/topic")
        .qos(MqttQos.EXACTLY_ONCE)
        .build();
Flowable<Mqtt5Publish> result =
        client.subscribeStreamWith(subscribeMessage)
                .doOnSingle(subAck -> System.out.println("subscribed"))
                .doOnNext(publish -> System.out.println("received publish"));

Unsubscribe

unsubscribeWith() and unsubscribe(Mqtt3/5Unsubscribe) method calls are analog to the Async and Blocking API but return Single<UnsubAck>.

Consume messages

Messages can either be consumed per subscribe (described above) or globally:

Flowable<Mqtt5Publish> result =
        client.publishes(MqttGlobalPublishFilter.ALL).doOnNext(System.out::println);

publishes must be called before subscribe to ensure no message is lost. It can be called before connect to receive messages of a previous session.

Disconnect

disconnect(), disconnectWith() and disconnect(Mqtt5Disconnect) method calls are analog to the Async and Blocking API but return Completable.

Reauth (only MQTT 5)

reauth() method call is analog to the Async and Blocking API but returns Completable.

Versioning

Semantic Versioning is used.

All code inside com.hivemq.client.internal packages must not be used directly. It can change at any time and is not part of the public API.

Interfaces annotated with DoNotImplement must not be implemented. The implementation is provided by the library. This allows the library to later add methods to the interface without breaking backwards compatibility with implementing classes.

Contributing

If you want to contribute to HiveMQ MQTT Client, see the contribution guidelines.

License

HiveMQ MQTT Client is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.