Add module.md and package.md documentations

README.md

@@ -1 +1,64 @@
-# module-mqtt
+# Ballerina Mqtt Library
+
+This package provides an implementation to interact with Mqtt servers via Mqtt client and listener.
+
+MQTT is a lightweight, publish-subscribe, machine to machine network protocol for message queue/message queuing service.
+
+### Publisher and subscriber
+#### Mqtt publisher
+A Mqtt publisher is a Mqtt client that publishes messages to the Mqtt server. When working with a Mqtt client, the first thing to do is to initialize the client.
+For the publisher to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a publisher client with the basic configuration.
+```ballerina
+import xlibb/mqtt;
+import ballerina/uuid;
+
+mqtt:ClientConfiguration clientConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    }
+};
+
+mqtt:Client mqttClient = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), clientConfiguration); // A unique id needs to be provided as the client id
+```
+Using the `publish` api of this client, messages can be sent to the Mqtt server.
+```ballerina
+check mqttClient->publish("mqtt/test", {payload: "This is Ballerina Mqtt client!!!".toBytes()});
+```
+#### Mqtt subscriber
+A Mqtt subscriber is a client responsible for reading messages from one or more topics in the server. When working with a Mqtt subscriber, the first thing to do is initialize the subscriber.
+For the subscriber to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a subscriber with the basic configuration.
+```ballerina
+mqtt:ListenerConfiguration listenerConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    },
+    manualAcks: false   // When set to false, the MQTT acknowledgements are not sent automatically by the subscriber
+};
+
+mqtt:Listener mqttSubscriber = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), "mqtt/test", listenerConfiguration);
+```
+This subscriber can be used in the `mqtt:Service` to listen to messages in `mqtt/test` topic.
+```ballerina
+service on mqttSubscriber {
+    remote function onMessage(mqtt:Message message, mqtt:Caller caller) returns error? {
+        log:printInfo(check string:fromBytes(message.payload));
+        check caller->complete();
+    }
+
+    remote function onError(mqtt:Error err) returns error? {
+        log:printError("Error occured ", err);
+    }
+
+    remote function onCompleted(mqtt:DeliveryToken token) returns error? {
+        log:printInfo(string`Message ${token.messageId.toString()} delivered`);
+        log:printInfo(check string:fromBytes(token.message.payload));
+    }
+}
+```
+The `mqtt:Caller` can be used to indicate that the application has completed processing the message by using `complete()` api.

ballerina/Ballerina.toml

@@ -1,7 +1,7 @@
 [package]
 org = "xlibb"
 name = "mqtt"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["xlibb"]
 keywords = ["mqtt"]
 repository = "https://github.com/xlibb/module-mqtt"
@@ -12,8 +12,8 @@ distribution = "2201.6.0"
 [[platform.java11.dependency]]
 groupId = "io.xlibb"
 artifactId = "mqtt"
-version = "0.1.0"
-path = "../native/build/libs/mqtt-native-0.1.0.jar"
+version = "0.1.1"
+path = "../native/build/libs/mqtt-native-0.1.1-SNAPSHOT.jar"
 
 # Azure dependencies
 [[platform.java11.dependency]]

ballerina/Dependencies.toml

@@ -156,7 +156,7 @@ modules = [
 [[package]]
 org = "xlibb"
 name = "mqtt"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
 	{org = "ballerina", name = "jballerina.java"},
 	{org = "ballerina", name = "lang.runtime"},

ballerina/Module.md

@@ -1,3 +1,63 @@
 ## Overview
+This module provides an implementation to interact with Mqtt servers via Mqtt client and listener.
 
-This module provides an implementation to interact with Mqtt Brokers via Mqtt client and listener.
+MQTT is a lightweight, publish-subscribe, machine to machine network protocol for message queue/message queuing service.
+
+### Publisher and subscriber
+#### Mqtt publisher
+A Mqtt publisher is a Mqtt client that publishes messages to the Mqtt server. When working with a Mqtt client, the first thing to do is to initialize the client.
+For the publisher to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a publisher client with the basic configuration.
+```ballerina
+import xlibb/mqtt;
+import ballerina/uuid;
+
+mqtt:ClientConfiguration clientConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    }
+};
+
+mqtt:Client mqttClient = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), clientConfiguration); // A unique id needs to be provided as the client id
+```
+Using the `publish` api of this client, messages can be sent to the Mqtt server.
+```ballerina
+check mqttClient->publish("mqtt/test", {payload: "This is Ballerina Mqtt client!!!".toBytes()});
+```
+#### Mqtt subscriber
+A Mqtt subscriber is a client responsible for reading messages from one or more topics in the server. When working with a Mqtt subscriber, the first thing to do is initialize the subscriber.
+For the subscriber to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a subscriber with the basic configuration.
+```ballerina
+mqtt:ListenerConfiguration listenerConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    },
+    manualAcks: false   // When set to false, the MQTT acknowledgements are not sent automatically by the subscriber
+};
+
+mqtt:Listener mqttSubscriber = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), "mqtt/test", listenerConfiguration);
+```
+This subscriber can be used in the `mqtt:Service` to listen to messages in `mqtt/test` topic.
+```ballerina
+service on mqttSubscriber {
+    remote function onMessage(mqtt:Message message, mqtt:Caller caller) returns error? {
+        log:printInfo(check string:fromBytes(message.payload));
+        check caller->complete();
+    }
+
+    remote function onError(mqtt:Error err) returns error? {
+        log:printError("Error occured ", err);
+    }
+
+    remote function onCompleted(mqtt:DeliveryToken token) returns error? {
+        log:printInfo(string`Message ${token.messageId.toString()} delivered`);
+        log:printInfo(check string:fromBytes(token.message.payload));
+    }
+}
+```
+The `mqtt:Caller` can be used to indicate that the application has completed processing the message by using `complete()` api.

ballerina/Package.md

@@ -1,2 +1,63 @@
 ## Overview
-This package provides an implementation to interact with Mqtt Brokers via Mqtt client and listener.
+This package provides an implementation to interact with Mqtt servers via Mqtt client and listener.
+
+MQTT is a lightweight, publish-subscribe, machine to machine network protocol for message queue/message queuing service.
+
+### Publisher and subscriber
+#### Mqtt publisher
+A Mqtt publisher is a Mqtt client that publishes messages to the Mqtt server. When working with a Mqtt client, the first thing to do is to initialize the client.
+For the publisher to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a publisher client with the basic configuration.
+```ballerina
+import xlibb/mqtt;
+import ballerina/uuid;
+
+mqtt:ClientConfiguration clientConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    }
+};
+
+mqtt:Client mqttClient = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), clientConfiguration); // A unique id needs to be provided as the client id
+```
+Using the `publish` api of this client, messages can be sent to the Mqtt server.
+```ballerina
+check mqttClient->publish("mqtt/test", {payload: "This is Ballerina Mqtt client!!!".toBytes()});
+```
+#### Mqtt subscriber
+A Mqtt subscriber is a client responsible for reading messages from one or more topics in the server. When working with a Mqtt subscriber, the first thing to do is initialize the subscriber.
+For the subscriber to work successfully, an active Mqtt server should be available.
+
+The code snippet given below initializes a subscriber with the basic configuration.
+```ballerina
+mqtt:ListenerConfiguration listenerConfiguration = {
+    connectionConfig: {
+        username: "ballerina",
+        password: "ballerinamqtt"
+    },
+    manualAcks: false   // When set to false, the MQTT acknowledgements are not sent automatically by the subscriber
+};
+
+mqtt:Listener mqttSubscriber = check new (mqtt:DEFAULT_URL, uuid:createType1AsString(), "mqtt/test", listenerConfiguration);
+```
+This subscriber can be used in the `mqtt:Service` to listen to messages in `mqtt/test` topic.
+```ballerina
+service on mqttSubscriber {
+    remote function onMessage(mqtt:Message message, mqtt:Caller caller) returns error? {
+        log:printInfo(check string:fromBytes(message.payload));
+        check caller->complete();
+    }
+
+    remote function onError(mqtt:Error err) returns error? {
+        log:printError("Error occured ", err);
+    }
+
+    remote function onCompleted(mqtt:DeliveryToken token) returns error? {
+        log:printInfo(string`Message ${token.messageId.toString()} delivered`);
+        log:printInfo(check string:fromBytes(token.message.payload));
+    }
+}
+```
+The `mqtt:Caller` can be used to indicate that the application has completed processing the message by using `complete()` api.

ballerina/build.gradle

@@ -148,7 +148,7 @@ publishing {
 updateTomlFiles.dependsOn copyStdlibs
 
 test.dependsOn startMqttServer
-test.finalizedBy stopMqttServer
+build.finalizedBy stopMqttServer
 
 build.dependsOn ":mqtt-native:build"
 build.dependsOn "generatePomFileForMavenPublication"

ballerina/constants.bal

@@ -0,0 +1 @@
+const DEFAULT_URL = "tcp://localhost:1883";

ballerina/tests/resources/docker-compose.yaml

@@ -4,6 +4,7 @@ services:
     mosquitto:
         image: 'eclipse-mosquitto:latest'
         hostname: mosquitto
+        container_name: mqtt-test-server
         ports:
             - '1883:1883'
             - '9001:9001'