How mica-mqtt 2.5.4 Simplifies Dynamic Topic Parsing with Native Annotation Support

We are excited to announce the official release of mica-mqtt 2.5.4.

In IoT and real‑time messaging, designing MQTT topics is crucial. Dynamic topics such as /devices/${productId}/${deviceId}/events previously required manual string splitting, which was cumbersome and error‑prone.

✨ Core Highlight: Native Annotation Support for Topic Variable Parsing

Version 2.5.4 adds native Topic variable parsing to the @MqttClientSubscribe client annotation and the @MqttServerFunction server annotation, allowing flexible handling of dynamic topics and cleaner code.

Client @MqttClientSubscribe

For example, to subscribe to all topics matching /sys/${productKey}/${deviceName}/thing/sub/register, define a method with a Map<String, String> parameter. When a message arrives with topic /sys/prod-123/dev-007/thing/sub/register, mica-mqtt automatically parses the variables and injects them into the topicVars argument.

/** 
 * Subscription method, optional parameters must be more than 2,
 * @param topic optional topic parameter
 * @param topicVars parsed variables from topic template ${productKey} (v2.5.4 support), must be Map<String, String>
 * @param payload message payload as byte array, optional, also supports object form with default JSON serialization
 */
@MqttClientSubscribe("/sys/${productKey}/${deviceName}/thing/sub/register")
public void thingSubRegister(String topic, Map<String, String> topicVars, byte[] payload) {
    // 1.3.8 and later support ${} variable replacement, which defaults to '+'
    log.info("topic:{} payload:{}", topic, new String(payload, StandardCharsets.UTF_8));
}

Server @MqttServerFunction

The server‑side function also receives Topic variable parsing, enabling easy extraction of device identifiers and product keys.

/**
 * MQTT message handling function, matches topic /test/+
 *
 * @param context   ChannelContext, optional
 * @param topic     Received topic name, optional
 * @param topicVars Parsed ${xxxx} variables from topic (v2.5.4 support), must be Map<String, String>
 * @param publishMessage Full MQTT publish message object, optional
 * @param message   Payload as byte array, optional, also supports object form with default JSON serialization
 */
@MqttServerFunction("/test/${xxxx}")
public void func3(ChannelContext context, String topic, Map<String, String> topicVars,
                  MqttPublishMessage publishMessage, byte[] message) {
    // Retrieve client node information
    Node clientNode = context.getClientNode();
    log.info("clientNode:{} topic:{} topicVars:{} publishMessage:{} message:{}",
             clientNode, topic, topicVars, publishMessage, new String(message));
}

🚀 Performance and Experience Optimizations

In addition to core features, 2.5.4 includes several performance and developer‑experience improvements:

Server subscription management upgrade : mica-mqtt-server now uses a Trie to manage MQTT subscriptions, greatly improving matching efficiency at large scale.

More flexible heartbeat detection : When the heartbeat timeout is ≤ 0, the server disables heartbeat checks, offering greater flexibility for specific scenarios.

Topic whitespace validation adjustment : Compatibility with brokers such as EMQX is improved by removing whitespace checks and adding log hints.

🛠️ Refactoring and Breaking Changes

Significant internal refactoring was performed to reduce code duplication and lay groundwork for future MQTT 5.0 property support.

Breaking changes requiring code updates include:

Annotation package relocation : @MqttServerFunction and @MqttClientSubscribe have moved to the mica-mqtt-common package.

Codec package adjustments : Classes and methods in mica-mqtt-codec have been renamed and restructured.

Utility method removal : The isValidPublishTopicName method in MqttCodecUtil is removed; use isTopicFilter for validation.

🍻 Conclusion

mica-mqtt 2.5.4 is a milestone release that elevates developer experience with native, easy‑to‑use Topic variable parsing, delivering higher efficiency and enjoyment for IoT and messaging applications. We encourage all users to upgrade and explore these exciting changes.