Skip to content

Commit

Permalink
MTM-58341 Update MQTT Service client usage documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@schmiel-cumulocity
schmiel-cumulocity authored and Sławomir Chmiel committed Apr 19, 2024
1 parent 7403f68 commit 8eb7904
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 44 deletions.
35 changes: 18 additions & 17 deletions content/device-integration/mqtt-service-bundle/implementation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
51 changes: 24 additions & 27 deletions content/device-integration/mqtt-service-bundle/java-client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<dependencies>` node:
```xml
<dependency>
<groupId>com.cumulocity.client.mqtt</groupId>
<artifactId>mqtt-service-websocket</artifactId>
<groupId>com.cumulocity.sdk.mqtt</groupId>
<artifactId>mqtt-service-ws</artifactId>
<version>${c8y.version}</version>
</dependency>
```
Expand All @@ -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();
```

0 comments on commit 8eb7904

Please sign in to comment.