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:

<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
    <version>2.3.9</version>
</dependency>

New dependency:

<dependency>
    <groupId>org.dromara.mica-mqtt</groupId>
    <artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
    <version>2.4.2-M1</version>
</dependency>

3.2 Enable IDEA automatic package optimization

3.3 Open the error code

3.4 Delete old erroneous imports

Example, delete the following imports:

import net.dreamlu.iot.mqtt.spring.client.MqttClientSubscribe;
import net.dreamlu.iot.mqtt.spring.client.MqttClientTemplate;

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