org.wso2.ei.b7a:b7a-jms-connector on Maven

Module overview

The ballerina/java.jms module provides an API to connect to an external JMS provider like ActiveMQ from Ballerina.

This module is created with minimal deviation from the JMS API to make it easy for the developers who are used to working with the JMS API. This module is written to support both JMS 2.0 and JMS 1.0 API.

Currently, the following JMS API Classes are supported through this module.

Connection
Session
Destination (Queue, Topic, TemporaryQueue, TemporaryTopic)
Message (TextMessage, MapMessage, BytesMessage, StreamMessage)
MessageConsumer
MessageProducer

The following sections provide details on how to use the JMS connector.

Compatibility
Samples

Compatibility

Ballerina Language Version	JMS Module Version
1.0.x	0.6.x
1.1.x	0.7.x
1.2.x	0.8.x
Swan Lake Preview1	0.99.x

Samples

JMS Message Producer and Consumer example

Following is a simple Ballerina program that sends and receives a message from a queue named MyQueue.

import ballerina/log;
import ballerina/java.jms;

public function main() returns error? {

    jms:Connection connection = check jms:createConnection({
                      initialContextFactory: "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
                      providerUrl: "tcp://localhost:61616"
                    });
    jms:Session session = check connection->createSession({acknowledgementMode: "AUTO_ACKNOWLEDGE"});
    jms:Destination queue = check session->createQueue("MyQueue");
    jms:MessageProducer producer = check session.createProducer(queue);
    jms:MessageConsumer consumer = check session->createConsumer(queue);

    jms:TextMessage msg = check session.createTextMessage("Hello Ballerina!");

    check producer->send(msg);

    jms:Message? response = check consumer->receive(3000);
    if (response is jms:TextMessage) {
        var val = response.getText();
        if (val is string) {
            log:printInfo("Message received: " + val);
        } else {
            log:printInfo("Message received without text");
        }
    } else {
        log:printInfo("Message received.");
    }
}

Asynchronous message consumer

One of the key deviations from the JMS API was the asynchronous message consumption using message listeners. In Ballerina transport listener, the concept is covered with the service type, hence we have used the Ballerina service to implement the message listener. Following is a message listener example listening on a topic named MyTopic.

import ballerina/log;
import ballerina/java.jms;

jms:Connection connection = check jms:createConnection({
                   initialContextFactory: "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
                   providerUrl: "tcp://localhost:61616"
              });

listener jms:MessageConsumer jmsConsumer = createListener(connection);

service messageListener on jmsConsumer {

   resource function onMessage(jms:Message message) {
       if (message is jms:TextMessage) {
           var val = message.getText();
           if (val is string) {
               log:printInfo("Message received: " + val );
           } else {
               log:printInfo("Message received without text");
           }
       } else {
           log:printInfo("Message received.");
       }
   }
}

function createListener(jms:Connection connection) returns  jms:MessageConsumer {
    jms:Session session = checkpanic connection->createSession({acknowledgementMode: "AUTO_ACKNOWLEDGE"});
    jms:Destination queue = checkpanic session->createQueue("MyQueue");
    jms:MessageConsumer consumer = checkpanic session->createConsumer(queue);
    return consumer;
}

Adding the required dependencies

Add the required dependencies to the Ballerina.toml file based on the broker that you're trying to connect to. Add the configurations below to run the given examples using Apache ActiveMQ.

  [[platform.libraries]]
  module = "jms"
  path = "<path>/activemq-client-5.15.12.jar"
  artifactId = "activemq-client"
  version = "5.15.12"
  groupId = "org.apache.activemq"

  [[platform.libraries]]
  module = "jms"
  path = "<path>/geronimo-j2ee-management_1.1_spec-1.0.1.jar"
  artifactId = "geronimo-j2ee-management_1.1_spec"
  version = "1.0.1"
  groupId = "org.apache.geronimo.specs"

  [[platform.libraries]]
  module = "jms"
  path = "<path>/libs/hawtbuf-1.11.jar"
  artifactId = "hawtbuf"
  version = "1.11"
  groupId = "org.fusesource.hawtbuf"