From a5cb2308f9244773d6379b325aca66432f15282a Mon Sep 17 00:00:00 2001 From: Slawomir Chmiel Date: Thu, 4 Apr 2024 10:03:32 +0200 Subject: [PATCH] MTM-58341 Update MQTT Service client usage documentation --- .../mqtt-service-bundle/implementation.md | 35 ++++++------- .../mqtt-service-bundle/java-client.md | 51 +++++++++---------- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/content/device-integration/mqtt-service-bundle/implementation.md b/content/device-integration/mqtt-service-bundle/implementation.md index 74eea5ae5c..aacf815f30 100644 --- a/content/device-integration/mqtt-service-bundle/implementation.md +++ b/content/device-integration/mqtt-service-bundle/implementation.md @@ -47,23 +47,24 @@ Only alphanumeric characters and slash (`/`) can be used in topic name. The original MQTT messages are re-packed into MQTT Service message format which includes the original payload and additional metadata fields. Assuming Java types, the packed message structure looks as follows: -`MqttMessage` -| Field name | Type | Description | -|:-----------|:-------------|:---------------------------| -| payload | byte[] | MQTT payload | -| metadata | MqttMetadata | Metadata from the MQTT message | - -`MqttMetadata` -| Field name | Type | Description | -|:-----------------------|:--------|:----------------------------------------------------------------------| -| clientId | String | Unique MQTT client identifier, usually used as an external identifier | -| messageId | int | Unique MQTT message ID per client, available only with QoS 1 and 2 | -| dupFlag | boolean | Indicates this message is a resend by the MQTT client | -| userProperties | Map | Reserved for future use of MQTT 5.0 features | -| payloadFormatIndicator | enum | Reserved for future use of MQTT 5.0 features | -| contentType | String | Reserved for future use of MQTT 5.0 features | -| correlationData | byte[] | Reserved for future use of MQTT 5.0 features | -| responseTopic | String | Reserved for future use of MQTT 5.0 features | +`MqttServiceMessage` +| Field name | Type | Description | +|:-----------|:--------------------|:-------------------------------| +| payload | byte[] | MQTT payload | +| metadata | MqttServiceMetadata | Metadata from the MQTT message | + +`MqttServiceMetadata` +| Field name | Type | Description | +|:-----------------------|:--------|:------------------------------------------------------------------------| +| clientId | String | Unique MQTT client identifier, usually used as an external identifier | +| messageId | int | Unique MQTT message ID per client, available only with QoS 1 and 2 | +| dupFlag | boolean | Indicates this message is a resend by the MQTT client | +| userProperties | Map | Reserved for future use of MQTT 5.0 features | +| payloadFormatIndicator | enum | Reserved for future use of MQTT 5.0 features | +| contentType | String | Reserved for future use of MQTT 5.0 features | +| correlationData | byte[] | Reserved for future use of MQTT 5.0 features | +| responseTopic | String | Reserved for future use of MQTT 5.0 features | +| topic | String | The name of the MQTT topic that the message was published by the client | The [Java Client](/device-integration/mqtt-service#java-client) contains classes representing the above model. diff --git a/content/device-integration/mqtt-service-bundle/java-client.md b/content/device-integration/mqtt-service-bundle/java-client.md index 8cde02c963..e168acc767 100644 --- a/content/device-integration/mqtt-service-bundle/java-client.md +++ b/content/device-integration/mqtt-service-bundle/java-client.md @@ -15,8 +15,8 @@ Follow the [Microservice SDK](/microservice-sdk/java/#add-repositories-and-depen To include MQTT Service Java Client into your project, add the following dependency inside the `` node: ```xml - com.cumulocity.client.mqtt - mqtt-service-websocket + com.cumulocity.sdk.mqtt + mqtt-service-ws ${c8y.version} ``` @@ -27,54 +27,51 @@ Example of publishing messages to the MQTT Service via WebSocket: // Message to be sent final String payload = "Hello World"; -// Construct a new MqttMessage and set the payload -final MqttMessage message = new MqttMessage(); +// Construct a new MqttServiceMessage and set the payload +final MqttServiceMessage message = new MqttServiceMessage(); message.setPayload(payload.getBytes()); -// Build MqttConfig with topic to which the message is to be sent -final MqttConfig config = MqttConfig.webSocket().topic(topic).build(); - -// Create an instance of MqttClient by specifying the server URI to connect to along with TokenApi -final MqttClient client = MqttClient.webSocket() +// Create an instance of MqttServiceApi by specifying the server URI to connect to along with TokenApi +final MqttServiceApi mqttServiceApi = MqttServiceApi.webSocket() .url(webSocketBaseUrl) .tokenApi(tokenApi) .build(); -// Build MqttPublisher and publish MqttMessage. Close the resource either by using a [try-with-resources block](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) as below or by calling publisher.close() explicitly -try (final MqttPublisher publisher = client.buildPublisher(config)) { +// Build PublisherConfig with topic to which the message is to be sent +final PublisherConfig config = PublisherConfig.publisherConfig().topic(topic).build(); + +// Build Publisher and publish MqttServiceMessage. Close the resource either by using a [try-with-resources block](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) as below or by calling publisher.close() explicitly +try (final Publisher publisher = mqttServiceApi.buildPublisher(config)) { publisher.publish(message); } catch (Exception e) { log.error("Could not sent message to {}", topic, e); } +mqttServiceApi.close(); ``` Example of subscribing to messages from the MQTT Service via WebSocket: ```java -// Build MqttConfig with topic and subscriber name -final MqttConfig config = MqttConfig.webSocket().topic(topic).subscriber(subscriberName).build(); - -// Create an instance of MqttClient by specifying the server URI to connect to along with TokenApi -final MqttClient client = MqttClient.webSocket() +// Create an instance of MqttServiceApi by specifying the server URI to connect to along with TokenApi +final MqttServiceApi mqttServiceApi = MqttServiceApi.webSocket() .url(webSocketBaseUrl) .tokenApi(tokenApi) .build(); -// Build MqttSubscriber -final MqttSubscriber subscriber = client.buildSubscriber(config); +// Build SubscriberConfig with topic and subscriber name +final SubscriberConfig config = SubscriberConfig.subscriberConfig().topic(topic).subscriber(subscriberName).build(); -// Subscribe by passing implementation of MqttMessageListener to handle events from the websocket server. -subscriber.subscribe(new MqttMessageListener() { - @Override - public void onMessage(MqttMessage message) { - log.info("Message Received: {}", new String(message.getPayload())); - } +// Build Subscriber +final Subscriber subscriber = mqttServiceApi.buildSubscriber(config); +// Subscribe by passing implementation of MessageListener to handle messages from the MQTT Service. +subscriber.subscribe(new MessageListener() { @Override - public void onError(Throwable t) { - log.error("WebSocket Error", t); + public void onMessage(MqttServiceMessage message) { + log.info("Message Received: {}", new String(message.getPayload())); } }); -// Close the resource after usage +// Close the resources after usage subscriber.close(); +mqttServiceApi.close(); ```