Upgrade Guide: Migrating to mica-mqtt 2.4.x with New Maven Coordinates

1. Introduction

Dromara mica-mqtt 2.4.2-M1 has been released, and the final 2.4.2 version will be released this weekend. Starting from the 2.4.x series, the Maven groupId has been moved to

org.dromara.mica-mqtt

and the package name to

org.dromara.mica.mqtt

. All other usage remains compatible. Upgrading to 2.4.x is strongly recommended.

Because the old documentation was scattered across modules, a new documentation site has been added: https://mica-mqtt.dromara.org

2. Changelog

v2.4.2-M1 – 2025-01-17

mica-mqtt client adjusts reconnection and resubscription logic (gitee #IBIE27) – thanks @cyber.

mica-mqtt client solon and spring boot plugins add MQTT5.0 sessionExpiryIntervalSecs configuration (gitee #IBIE27) – thanks @cyber.

DefaultMqttClientSession removes final modifier for easier inheritance.

ClientId bound to context; can be obtained via

context.getId()

(gitee #IBHHB1) – thanks @cv.

MqttServerCustomizer and MqttClientCustomizer extracted to mica-mqtt-server and mica-mqtt-client for easier component packaging (gitee #IBIJDF) – thanks @cyber.

v2.4.1 – 2025-01-04

MQTT server unified topic subscription/publish authentication logs for easier troubleshooting.

MQTT server adds PROXY protocol v1 support; Nginx can enable

tcp proxy_protocol on;

to forward source IP.

Fixed documentation Maven coordinates error.

Fixed issue where global lazy-loaded topics could not be subscribed in Spring Boot projects (gitee #IBFIV8) – thanks @xixuanhao.

v2.4.0 – 2024-12-07

HTTP API adds

stats

,

clients

list and

client

detail endpoints.

MqttServer and MqttServerTemplate add

getClientInfo

,

getClients

client info interfaces.

Add

getSubscriptions

to retrieve client subscription list.

Add

getStat

statistics interface.

Adjusted Maven groupId from

net.dreamlu

to

org.dromara.mica-mqtt

.

Adjusted package name from

net.dreamlu.iot.mqtt

to

org.dromara.mica.mqtt

, other parts unchanged.

Switched to Central Sonatype; snapshots no longer published.

Fixed subscription send timing issue (gitee #IB72L6) – thanks @江上烽.

3. Migration Guide

3.1 Change Maven groupId

Replace

<groupId>net.dreamlu</groupId>

with

<groupId>org.dromara.mica-mqtt</groupId>

. Example:

<code>&lt;dependency&gt;
    &lt;groupId&gt;net.dreamlu&lt;/groupId&gt;
    &lt;artifactId&gt;mica-mqtt-client-spring-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;2.3.9&lt;/version&gt;
&lt;/dependency&gt;
</code>

New dependency:

<code>&lt;dependency&gt;
    &lt;groupId&gt;org.dromara.mica-mqtt&lt;/groupId&gt;
    &lt;artifactId&gt;mica-mqtt-client-spring-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;2.4.2-M1&lt;/version&gt;
&lt;/dependency&gt;
</code>

3.2 Enable IDEA automatic package optimization

3.3 Open the error code

3.4 Delete old erroneous imports

Example, delete the following imports:

<code>import net.dreamlu.iot.mqtt.spring.client.MqttClientSubscribe;
import net.dreamlu.iot.mqtt.spring.client.MqttClientTemplate;
</code>

IDEA will automatically import the new packages:

Then rebuild and run.

4. Open Source Repository

Gitee: https://gitee.com/dromara/mica-mqtt

GitHub: https://github.com/dromara/mica-mqtt

GitCode: https://gitcode.com/dromara/mica-mqtt

5. Best Practices

BladeX IoT platform is a highly integrated IoT solution covering device management, data collection, real‑time monitoring, data analysis, and open API services.

It has iterated through four versions, supporting popular time‑series databases such as TDengine, InfluxDB 1.x, InfluxDB 2.x, and IoTDB, with excellent batch ingestion performance.

Interface overview:

Official site: https://iot.bladex.cn/

Demo site: https://iot.javablade.com