Skip to content

Commit

Permalink
Update the readme file
Browse files Browse the repository at this point in the history
  • Loading branch information
@ayeshLK
ayeshLK committed Feb 22, 2024
1 parent 4177693 commit f6240fe
Showing 1 changed file with 94 additions and 72 deletions.
166 changes: 94 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,105 +5,127 @@
[![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` module provides an API to connect to an IBM MQ server using Ballerina.

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

- QueueManager
- Queue
- Destination (Queue, Topic)
- Message
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.

### IBM MQ queue
### Create a queue

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.
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.

#### Producer
![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` package into your Ballerina project.

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

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();
}
### Step 2: Instantiate a new connector

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

```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.

```ballerina
configurable string topicName = ?;
configurable string topicString = ?;
ibmmq:Topic topic = check queueManager.accessTopic(
topicName, topicString, ibmmq:MQOO_OUTPUT | ibmmq:MQOO_INPUT_AS_Q_DEF
);
```

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.
### Step 3: Invoke the connector operations

#### Publisher
Now, utilize the available connector operations.

#### Produce message 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 message to an IBM MQ queue

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.

## 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

0 comments on commit f6240fe

Please sign in to comment.