Introduce a ballerina connector for IBM MQ

[ayeshLK]

Description:

$subject

IBM MQ: https://www.ibm.com/docs/en/ibm-mq/9.3
IBM MQ client API: https://www.ibm.com/docs/api/v1/content/SSFKSJ_9.3.0/javadoc/WMQJavaClasses/index.html?view=embed

[ayeshLK]

Initial design for the IBM MQ connector

1. QueueManager API

QueueManagerConfiguration

public type QueueManagerConfiguration record {|
    string host;
    int port = 1414;
    string channel;
    string userID?;
    string password?;
|};

ConnectionOpenOptions

public enum ConnectionOpenOptions {
    MQOO_OUTPUT = "MQOO_OUTPUT",
    MQOO_INPUT_AS_Q_DEF = "MQOO_INPUT_AS_Q_DEF",
    MQOO_INPUT_EXCLUSIVE = "MQOO_INPUT_EXCLUSIVE",
    MQOO_INPUT_SHARED = "MQOO_INPUT_SHARED"
}

QueueManager

public type QueueManager distinct object {
    function accessQueue(string queueName, ConnectionOpenOptions options) returns Queue;

    function accessTopic(string topicName, ConnectionOpenOptions options) returns Topic;
};

2. Destination API

Destination

public type Destination distinct client object {
    remote function put(byte[] payload) returns Error?;

    remote function get() returns Message|Error?;
};

Queue

public type Queue distinct client object {
    *Destination;
};

Topic

public type Topic distinct client object {
    *Destination;
};

3. Message API

public type Property record {|
    map<anydata> descriptor;
    boolean|byte|byte[]|decimal|float|int|string property;
|};

public type Message record {|
    map<Property> properties;
    byte[] value;
|};

4. Errors

public type Error distinct error;

[ayeshLK]

As per the IBM MQ java client design, it follows following pattern:

import com.ibm.mq.MQMessage;
import com.ibm.mq.MQQueue;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.constants.CMQC;
import com.ibm.mq.constants.MQConstants;

import java.util.Hashtable;

public class ProducerApp {
    public static void main(String[] args) throws Exception {
        Hashtable<String, Object> properties = new Hashtable<>();
        properties.put(MQConstants.HOST_NAME_PROPERTY, "localhost"); // Hostname of the MQ server
        properties.put(MQConstants.PORT_PROPERTY, 1414); // Port number of the MQ server
        properties.put(MQConstants.CHANNEL_PROPERTY, "DEV.APP.SVRCONN"); // Channel name

        MQQueueManager queueManager = new MQQueueManager("QM1", properties);

        MQMessage message = new MQMessage();
        message.writeUTF("Hello, MQ!"); // Message to be sent

        MQQueue queue = queueManager.accessQueue("DEV.QUEUE.1",
                CMQC.MQOO_OUTPUT | CMQC.MQOO_FAIL_IF_QUIESCING);
        queue.put(message);

        queue.close();
        queueManager.disconnect();
    }
}

[sameerajayasoma]

2. Destination API

Destination

public type Destination distinct client object {
    remote function put(byte[] payload) returns Error?;

    remote function get() returns Message|Error?;
};

Shouldn't we use the Message type in put as well?

[ayeshLK]

Shouldn't we use the Message type in put as well?

+1

[sameerajayasoma]

Let's start with this design. Please share the code when you are done. Thanks.

[ayeshLK]

Let's start with this design. Please share the code when you are done. Thanks.

Ack.

[dilanSachi]

Once the inital implementation is done we need to focus on,

1. Transactions
2. Request/Reply scenarios (using correlation id)
3. SSL support
4. Client ack

Also need to understand how the underline connection happens when QM is created (using wireshark).

[ayeshLK]

Apart from the above tasks we will skip the graalvm compatibility check in the initial release and update the connector with graalvm configurations in the subsequent release.

[theyinyanguy]

Thanks team for your work on this. One of the other things that are important for the PoC are MQ Message headers[1] [2]. I just want to be sure that we support them.
Thanks,
Puneet@wso2.com

[1] https://www.ibm.com/docs/en/ftmswsfz324?topic=messages-message-headers
[2] https://www.ibm.com/docs/en/bpm/8.6.0?topic=bindings-websphere-mq-headers

[ayeshLK]

Since, the above task has been completed closing this issue.