Merge pull request #12 from ayeshLK/master

Update API documentation

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Purpose
+
+## Examples
+
+## Checklist
+- [ ] Linked to an issue
+- [ ] Updated the changelog
+- [ ] Added tests
+- [ ] Updated the spec
+- [ ] Checked native-image compatibility

README.md

@@ -1,2 +1,93 @@
-# module-ballerinax-ibm.ibmmq
-Ballerina IBM MQ client connector module.
+# Ballerina `ibm.ibmmq` Library
+
+[![Build](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/build-timestamped-master.yml)
+[![codecov](https://codecov.io/gh/ballerina-platform/module-ballerinax-ibm.ibmmq/branch/main/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerinax-ibm.ibmmq)
+[![Trivy](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/trivy-scan.yml)
+[![GraalVM Check](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/actions/workflows/build-with-bal-test-graalvm.yml)
+[![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerinax-ibm.ibmmq.svg)](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/commits/main)
+
+The `ballerinax/ibm.ibmmq` library provides an API to connect to an IBM MQ server using Ballerina.
+
+This library is created with minimal deviation from the IBM MQ java client API to make it easy for the developers who are used to working with the IBM MQ java client.
+
+Currently, the following IBM MQ API Classes are supported through this package.
+
+- QueueManager
+- Queue
+- Destination (Queue, Topic)
+- Message
+
+## Issues and projects 
+
+Issues and Projects tabs are disabled for this repository as this is part of the Ballerina Standard Library. To report bugs, request new features, start new discussions, view project boards, etc., go to the [Ballerina Standard Library parent repository](https://github.com/ballerina-platform/ballerina-standard-library). 
+
+This repository only contains the source code for the library.
+
+## Build from the source
+
+### Set up the prerequisites
+
+* Download and install Java SE Development Kit (JDK) version 17 (from one of the following locations).
+
+   * [Oracle](https://www.oracle.com/java/technologies/downloads/)
+
+   * [OpenJDK](https://adoptium.net/)
+
+        > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.
+
+2. Download and install [Docker](https://www.docker.com/). This is required to run the tests.
+
+### Build the source
+
+Execute the commands below to build from the source.
+
+1. To build the library:
+   ```    
+   ./gradlew clean build
+   ```
+
+2. To run the tests:
+   ```
+   ./gradlew clean test
+   ```
+3. To build the library without the tests:
+   ```
+   ./gradlew clean build -x test
+   ```
+4. To debug library implementation:
+   ```
+   ./gradlew clean build -Pdebug=<port>
+   ```
+5. To debug the library with Ballerina language:
+   ```
+   ./gradlew clean build -PbalJavaDebug=<port>
+   ```
+6. Publish ZIP artifact to the local `.m2` repository:
+   ```
+   ./gradlew clean build publishToMavenLocal
+   ```
+7. Publish the generated artifacts to the local Ballerina central repository:
+   ```
+   ./gradlew clean build -PpublishToLocalCentral=true
+   ```
+8. Publish the generated artifacts to the Ballerina central repository:
+   ```
+   ./gradlew clean build -PpublishToCentral=true
+   ```
+
+## Contribute to Ballerina
+
+As an open source project, Ballerina welcomes contributions from the community. 
+
+For more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).
+
+## Code of conduct
+
+All the contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).
+
+## Useful links
+
+* For more information go to the [`ibm.ibmmq` library](https://lib.ballerina.io/ballerinax/ibm.ibmmq/latest).
+* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).
+* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
+* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.

ballerina/Module.md

@@ -0,0 +1,14 @@
+## Overview
+
+The `ballerinax/ibm.ibmmq` module provides an API to connect to an IBM MQ server using Ballerina.
+
+This module is created with minimal deviation from the IBM MQ java client API to make it easy for the developers who are used to working with the IBM MQ java client.
+
+Currently, the following IBM MQ API Classes are supported through this package.
+
+- QueueManager
+- Queue
+- Destination (Queue, Topic)
+- Message
+
+## Samples

ballerina/Package.md

@@ -0,0 +1,14 @@
+## Package overview
+
+The `ballerinax/ibm.ibmmq` package provides an API to connect to an IBM MQ server using Ballerina.
+
+This package is created with minimal deviation from the IBM MQ java client API to make it easy for the developers who are used to working with the IBM MQ java client.
+
+Currently, the following IBM MQ API Classes are supported through this package.
+
+- QueueManager
+- Queue
+- Destination (Queue, Topic)
+- Message
+
+## Samples

ballerina/constants.bal

@@ -14,38 +14,92 @@
 // specific language governing permissions and limitations
 // under the License.
 
-// Option to indicate whether the topic is being opened for either publication or subscription.
-public const OPEN_AS_SUBSCRIPTION = 1;
-public const OPEN_AS_PUBLICATION = 2;
-
-// Options that control the opening of the queue for a consumer.
-public const MQOO_BROWSE = 8;
-public const MQOO_INPUT_AS_Q_DEF = 1;
-public const MQOO_INPUT_EXCLUSIVE = 4;
-public const MQOO_INPUT_SHARED = 2;
-
-// Options that control the opening of the topic for either publication or subscription.
-public const MQOO_ALTERNATE_USER_AUTHORITY = 4096;
-public const MQOO_BIND_AS_Q_DEF = 0;
-public const MQOO_FAIL_IF_QUIESCING = 8192;
-public const MQOO_OUTPUT = 16;
-public const MQOO_PASS_ALL_CONTEXT = 512;
-public const MQOO_PASS_IDENTITY_CONTEXT = 256;
-public const MQOO_SET_ALL_CONTEXT = 2048;
-public const MQOO_SET_IDENTITY_CONTEXT = 1024;
-public const MQSO_CREATE = 2;
-
-// Options related to the the get message in a topic.
-public const MQGMO_WAIT = 1;
-public const MQGMO_NO_WAIT = 0;
-public const MQGMO_SYNCPOINT = 2;
-public const MQGMO_NO_SYNCPOINT = 4;
-public const MQGMO_BROWSE_FIRST = 16;
-public const MQGMO_BROWSE_NEXT = 32;
-public const MQGMO_BROWSE_MSG_UNDER_CURSOR = 2048;
-public const MQGMO_MSG_UNDER_CURSOR = 256;
-public const MQGMO_LOCK = 512;
-public const MQGMO_UNLOCK = 1024;
-public const MQGMO_ACCEPT_TRUNCATED_MSG = 64;
-public const MQGMO_FAIL_IF_QUIESCING = 8192;
-public const MQGMO_CONVERT = 16384;
+# Open topic as a subscription.
+public const int OPEN_AS_SUBSCRIPTION = 1;
+
+# Open topic as a publication.
+public const int OPEN_AS_PUBLICATION = 2;
+
+# Open the queue to browse messages.
+public const int MQOO_BROWSE = 8;
+
+# Open the queue to get messages using the queue-defined default.
+public const int MQOO_INPUT_AS_Q_DEF = 1;
+
+# Open the queue to get messages with exclusive access.
+public const int MQOO_INPUT_EXCLUSIVE = 4;
+
+# Open the queue to get messages with shared access.
+public const int MQOO_INPUT_SHARED = 2;
+
+# Enables the AlternateUserId field in the ObjDesc parameter contains a user identifier to use to validate this MQOPEN call.
+public const int MQOO_ALTERNATE_USER_AUTHORITY = 4096;
+
+# The local queue manager binds the queue handle in the way defined by the DefBind queue attribute.
+public const int MQOO_BIND_AS_Q_DEF = 0;
+
+# The MQOPEN call fails if the queue manager is in quiescing state. This option is valid for all types of object.
+public const int MQOO_FAIL_IF_QUIESCING = 8192;
+
+# This allows the MQPMO_PASS_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue.
+public const int MQOO_PASS_ALL_CONTEXT = 512;
+
+# This allows the MQPMO_PASS_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue.
+public const int MQOO_PASS_IDENTITY_CONTEXT = 256;
+
+# This allows the MQPMO_SET_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue.
+public const int MQOO_SET_ALL_CONTEXT = 2048;
+
+# This allows the MQPMO_SET_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue.
+public const int MQOO_SET_IDENTITY_CONTEXT = 1024;
+
+# Open the queue to put messages.
+public const int MQOO_OUTPUT = 16;
+
+# The application waits until a suitable message arrives.
+public const int MQGMO_WAIT = 1;
+
+# The application does not wait if no suitable message is available.
+public const int MQGMO_NO_WAIT = 0;
+
+# The request is to operate within the normal unit-of-work protocols.
+public const int MQGMO_SYNCPOINT = 2;
+
+# The request is to operate outside the normal unit-of-work protocols.
+public const int MQGMO_NO_SYNCPOINT = 4;
+
+# When a queue is opened with the MQOO_BROWSE option, a browse cursor is established, positioned logically 
+# before the first message on the queue.
+public const int MQGMO_BROWSE_FIRST = 16;
+
+# Advance the browse cursor to the next message on the queue that satisfies the selection criteria specified 
+# on the MQGET call.
+public const int MQGMO_BROWSE_NEXT = 32;
+
+# Retrieve the message pointed to by the browse cursor nondestructively, regardless of the MQMO_* options 
+# specified in the MatchOptions field in MQGMO.
+public const int MQGMO_BROWSE_MSG_UNDER_CURSOR = 2048;
+
+# Retrieve the message pointed to by the browse cursor, regardless of the MQMO_* options specified in the 
+# MatchOptions field in MQGMO.
+public const int MQGMO_MSG_UNDER_CURSOR = 256;
+
+# Lock the message that is browsed, so that the message becomes invisible to any other handle open for the queue.
+public const int MQGMO_LOCK = 512;
+
+# Unlock a message. The message to be unlocked must have been previously locked by an MQGET call with the 
+# MQGMO_LOCK option.
+public const int MQGMO_UNLOCK = 1024;
+
+# If the message buffer is too small to hold the complete message, allow the MQGET call to fill the 
+# buffer with as much of the message as the buffer can hold.
+public const int MQGMO_ACCEPT_TRUNCATED_MSG = 64;
+
+# Force the MQGET call to fail if the queue manager is in the quiescing state.
+public const int MQGMO_FAIL_IF_QUIESCING = 8192;
+
+# Requests the application data to be converted.
+public const int MQGMO_CONVERT = 16384;
+
+# Subscribe Option create
+public const int MQSO_CREATE = 2;

ballerina/destination.bal

@@ -16,6 +16,7 @@
 
 import ballerina/jballerina.java;
 
+# IBM MQ destination client type.
 public type Destination distinct client object {
     remote function put(Message message) returns Error?;
 
@@ -24,38 +25,64 @@ public type Destination distinct client object {
     remote function close() returns Error?;
 };
 
+# IBM MQ Queue client.
 public isolated client class Queue {
     *Destination;
 
+    # Puts a message to an IBM MQ queue.
+    # 
+    # + message - IBM MQ message
+    # + return - An `ibmmq:Error` if the operation fails or else `()`
     remote function put(Message message) returns Error? =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Queue"
     } external;
 
+    # Retrieves a message from an IBM MQ queue.
+    # 
+    # + getMessageOptions - Options to control message retrieval
+    # + return - An `ibmmq:Message` if there is a message in the queue, `()` if there 
+    #           is no message or else `ibmmq:Error` if the operation fails
     remote function get(*GetMessageOptions getMessageOptions) returns Message|Error? =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Queue"
     } external;
 
+    # Closes the IBM MQ queue object. No further operations on this object are permitted after it is closed.
+    # 
+    # + return - An `ibmmq:Error` if the operation fails or else `()`
     remote function close() returns Error? =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Queue"
     } external;
 }
 
+# IBM MQ Topic client.
 public isolated client class Topic {
     *Destination;
 
+    # Puts a message to an IBM MQ topic.
+    # 
+    # + message - IBM MQ message
+    # + return - An `ibmmq:Error` if the operation fails or else `()`
     remote function put(Message message) returns Error? =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Topic"
     } external;
 
+    # Retrieves a message from an IBM MQ topic.
+    # 
+    # + getMessageOptions - Options to control message retrieval
+    # + return - An `ibmmq:Message` if there is a message in the topic, `()` if there 
+    #           is no message or else `ibmmq:Error` if the operation fails
     remote function get(*GetMessageOptions getMessageOptions) returns Message|Error?  =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Topic"
     } external;
 
+    # Closes the IBM MQ topic object. No further operations on this object are permitted after it is closed.
+    # 
+    # + return - An `ibmmq:Error` if the operation fails or else `()`
     remote function close() returns Error? =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.Topic"

ballerina/errors.bal

@@ -14,9 +14,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+# Represents a IBM MQ distinct error.
 public type Error distinct error<ErrorDetails>;
 
-# The error details type for the module.
+# The error details type for the IBM MQ module.
 #
 # + reasonCode - The reason code for the error
 # + errorCode - The error code for the error

ballerina/queue_manager.bal

@@ -16,8 +16,16 @@
 
 import ballerina/jballerina.java;
 
+# Represents an IBM MQ queue manager.
 public isolated class QueueManager {
 
+    # Initialize an IBM MQ queue manager.
+    # ```ballerina
+    # ibmmq:QueueManager queueManager = check new(name = "QM1", host = "localhost", channel = "DEV.APP.SVRCONN");
+    # ```
+    #
+    # + configurations - The configurations to be used when initializing the IBM MQ queue manager
+    # + return - The `ibmmq:QueueManager` or an `ibmmq:Error` if the initialization failed
     public isolated function init(*QueueManagerConfiguration configurations) returns Error? {
         check self.externInit(configurations);
     }
@@ -27,11 +35,31 @@ public isolated class QueueManager {
         'class: "io.ballerina.lib.ibm.ibmmq.QueueManager"
     } external;
 
+    # Establishes access to an IBM MQ queue on this queue manager.
+    # ```ballerina
+    # ibmmq:Queue queue = check queueManager.accessQueue("queue1", ibmmq:MQOO_OUTPUT);
+    # ```
+    # 
+    # + queueName - Name of the queue
+    # + options - The options which control the opening of the queue
+    # + return - The `ibmmq:Queue` object or an `ibmmq:Error` if the operation failed
     public isolated function accessQueue(string queueName, int options) returns Queue|Error =
     @java:Method {
         'class: "io.ballerina.lib.ibm.ibmmq.QueueManager"
     } external;
 
+    # Establishes access to an IBM MQ topic on this queue manager.
+    # ```ballerina
+    # ibmmq:Topic topic = check queueManager.accessTopic(
+    #   "dev", "DEV.BASE.TOPIC", ibmmq:OPEN_AS_PUBLICATION, ibmmq:MQOO_OUTPUT
+    # );
+    # ```
+    # 
+    # + topicName - The topic string to publish or subscribe against
+    # + topicString - The name of the topic object as defined on the local queue manager
+    # + openTopicOption - Indicates whether the topic is being opened for either publication or subscription
+    # + options - Options that control the opening of the topic for either publication or subscription
+    # + return - The `ibmmq:Topic` object or an `ibmmq:Error` if the operation failed
     public isolated function accessTopic(string topicName, string topicString, OPEN_TOPIC_OPTION openTopicOption,
             int options) returns Topic|Error =
     @java:Method {