Skip to content

Commit

Permalink
Merge pull request #37 from ayeshLK/docs
Browse files Browse the repository at this point in the history 
Improve module documentation
  • Loading branch information
@ayeshLK
ayeshLK authored Feb 27, 2024
2 parents bcd7f6e + 9cf6012 commit a4f29b1
Show file tree
Hide file tree
Showing 13 changed files with 360 additions and 222 deletions.
187 changes: 115 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,105 +5,148 @@
[![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)
[![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.
[IBM MQ](https://www.ibm.com/products/mq) is a powerful messaging middleware platform designed for facilitating reliable
communication between disparate systems and applications. IBM MQ ensures the secure and orderly exchange of messages
asynchronously, decoupling senders and receivers for efficient and scalable communication. It supports both
point-to-point and publish/subscribe messaging models via queues and topics.

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.
The `ballerinax/ibm.ibmmq` package provides an API to connect to an IBM MQ server using Ballerina.

Currently, the following IBM MQ API Classes are supported through this package.
## Compatibility

- QueueManager
- Queue
- Destination (Queue, Topic)
- Message
| | Version |
|:---|:------------:|
|IBM MQ Server | **9.3 or earlier** |
|IBM MQ Client Connector* | **9.3.4.0** |

### IBM MQ queue
## Setup guide

IBM MQ queues are used for point-to-point messaging. In point-to-point messaging, a producer application sends a message to a queue, and a single consumer application retrieves the message from the queue.
To use the Ballerina IBM MQ connector, you need to have an IBM MQ instance running or possess an IBM MQ cloud account.
For setting up IBM MQ locally, you can refer to the [IBM MQ official documentation](https://www.ibm.com/docs/en/ibm-mq/9.3?topic=migrating-installing-uninstalling).
Alternatively, to use IBM MQ on the cloud, [sign up](https://cloud.ibm.com/registration) for an IBM MQ cloud account.

#### Producer
### Create a queue

1. Log into IBM MQ console. If you are running an IBM MQ server locally you can navigate to
[https://localhost:9443/ibmmq/console](https://localhost:9443/ibmmq/console) URL in your browser to access the IBM MQ console.
2. Click on the `Create a queue` link.

![Create a queue](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-ibm.ibmmq/main/docs/setup/resources/select-create-queue.png)

3. Select the queue type.

![Select the queue type](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-ibm.ibmmq/main/docs/setup/resources/select-queue-type.png)

4. Go back to the home page and click on the `Manage` link on the sidebar.

![Click on Manage](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-ibm.ibmmq/main/docs/setup/resources/click-manage-link.png)

5. Navigate to `Events` tab.

![Navigate to Events tab](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-ibm.ibmmq/main/docs/setup/resources/navigate-to-events-tab.png)

6. Click on `Create`.

![Click on create](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-ibm.ibmmq/main/docs/setup/resources/click-on-create.png)

## Quickstart

To use the IBM MQ connector in your Ballerina application, modify the .bal file as follows:

### Step 1: Import the connector

Import `ballerinax/ibm.ibmmq` module into your Ballerina project.

```ballerina
import ballerinax/ibm.ibmmq;
```

### Step 2: Instantiate a new connector

Create an `ibmmq:QueueManager` instance by giving IBM MQ configuration.

public function main() returns error? {
ibmmq:QueueManager queueManager = check new (
name = "QM1", host = "localhost", channel = "DEV.APP.SVRCONN"
);
ibmmq:Queue producer = check queueManager.accessQueue("DEV.QUEUE.1", ibmmq:MQOO_OUTPUT);
check producer->put({
payload: "This is a sample message to IBM MQ queue".toBytes()
});
check producer->close();
check queueManager.disconnect();
}
```ballerina
configurable string queueManagerName = ?;
configurable string host = ?;
configurable int port = ?;
configurable string channel = ?;
configurable string userID = ?;
configurable string password = ?;
ibmmq:QueueManager queueManager = check new (
name = queueManagerName, host = host, channel = channel, userID = userID, password = password
);
```

#### Consumer
Create an `ibmmq:Queue` or `ibmmq:Topic` using the `ibmmq:QueueManager` instance with relevant configurations.

```ballerina
import ballerinax/ibm.ibmmq;
import ballerina/io;
public function main() returns error? {
ibmmq:QueueManager queueManager = check new (
name = "QM1", host = "localhost", channel = "DEV.APP.SVRCONN"
);
ibmmq:Queue consumer = check queueManager.accessQueue(
"DEV.QUEUE.1", ibmmq:MQOO_INPUT_AS_Q_DEF);
while true {
ibmmq:Message? message = check consumer->get(options = ibmmq:MQGMO_WAIT);
if message is () {
continue;
}
io:println(string:fromBytes(message.payload));
}
}
configurable string queueName = ?;
ibmmq:Queue queue = check queueManager.accessQueue(queueName, ibmmq:MQOO_OUTPUT | ibmmq:MQOO_INPUT_AS_Q_DEF);
```

### IBM MQ topic
Create an `ibmmq:Topic` using the `ibmmq:QueueManager` instance with relevant configurations.

IBM MQ topics are used in the publish/subscribe (pub/sub) messaging model. In pub/sub, publishers send messages to topics, and subscribers subscribe to topics. When a publisher sends a message to a topic, the queue manager delivers the message to all subscribers that are subscribed to that topic.
```ballerina
configurable string topicName = ?;
configurable string topicString = ?;
#### Publisher
ibmmq:Topic topic = check queueManager.accessTopic(
topicName, topicString, ibmmq:MQOO_OUTPUT | ibmmq:MQOO_INPUT_AS_Q_DEF
);
```

### Step 3: Invoke the connector operations

Now, utilize the available connector operations.

#### Produce messages to an IBM MQ queue

```ballerina
import ballerinax/ibm.ibmmq;
check queue->put({
payload: "This is a sample message to IBM MQ queue".toBytes()
});
```

#### Produce messages to an IBM MQ topic

public function main() returns error? {
ibmmq:QueueManager queueManager = check new (
name = "QM1", host = "localhost", channel = "DEV.APP.SVRCONN"
);
ibmmq:Topic publisher = check queueManager.accessTopic(
"dev", "DEV.BASE.TOPIC", ibmmq:OPEN_AS_PUBLICATION, ibmmq:MQOO_OUTPUT);
check publisher->put({
payload: "This is a sample message to IBM MQ topic".toBytes()
});
check publisher->close();
check queueManager.disconnect();
}
```ballerina
check topic->put({
payload: "This is a sample message to IBM MQ topic".toBytes()
});
```

#### Subscriber
#### Retrieve messages from an IBM MQ queue

```ballerina
import ballerinax/ibm.ibmmq;
import ballerina/io;
public function main() returns error? {
ibmmq:QueueManager queueManager = check new(
name = "QM1", host = "localhost", channel = "DEV.APP.SVRCONN");
ibmmq:Topic subscriber = check queueManager.accessTopic(
"dev", "DEV.BASE.TOPIC", ibmmq:OPEN_AS_SUBSCRIPTION, ibmmq:MQSO_CREATE);
while true {
ibmmq:Message? message = check subscriber->get(options = ibmmq:MQGMO_WAIT);
if message is () {
continue;
}
io:println(string:fromBytes(message.payload));
}
}
ibmmq:Message? message = check queue->get();
```

#### Retrieve messages from an IBM MQ topic

```ballerina
ibmmq:Message? message = check topic->get();
```

### Examples

The following example shows how to use the `ibm.ibmmq` connector to produce and consume messages using an IBM MQ server.

1. [Produce messages](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/produce-messages) - Produce messages to an IBM MQ queue.

2. [Consume messages](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/consume-messages) - Consume messages from an IBM MQ queue.

3. [Securing IBM MQ client](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/ibmmq-client-security) - Initiate secure communication between an IBM MQ client and an IBM MQ server.

4. [Produce MQIIH headers](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/produce-mqiih-headers) - Produce IBM MQ messages to an IBM MQ queue with the MQIIH headers.

5. [Consume MQIIH headers](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/consume-mqiih-headers) - Consume messages with the MQIIH header from an IBM MQ queue.

6. [Produce MQRFH2 headers](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/produce-mqrfh2-headers) - Produce IBM MQ messages to an IBM MQ queue with the MQRFH2 headers.

7. [Consume MQIIH headers](https://github.com/ballerina-platform/module-ballerinax-ibm.ibmmq/tree/main/examples/consume-mqrfh2-headers) - Consume messages with the MQRFH2 header from an IBM MQ queue.

## 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).
Expand Down
Loading

0 comments on commit a4f29b1

Please sign in to comment.