Ballerina java.jms Library

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

This library 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 library is written to support both JMS 2.0 and JMS 1.0 API.

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

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

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

• Samples

Samples

JMS message Producer

The following Ballerina program sends messages to a queue named MyQueue.

import ballerinax/activemq.driver as _;
import ballerinax/java.jms;

public function main() returns error? {
    jms:Connection connection = check new (
        initialContextFactory = "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
        providerUrl = "tcp://localhost:61616"
    );
    jms:Session session = check connection->createSession();
    jms:MessageProducer producer = check session.createProducer({
        'type: jms:QUEUE,
        name: "MyQueue"
    });
    jms:TextMessage msg = {
        content: "Hello Ballerina!"
    };
    check producer->send(msg);
}

JMS message consumer

The following Ballerina program receives messages from a queue named MyQueue.

import ballerinax/activemq.driver as _;
import ballerinax/java.jms;
import ballerina/log;

public function main() returns error? {
    jms:Connection connection = check new (
        initialContextFactory = "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
        providerUrl = "tcp://localhost:61616"
    );
    jms:Session session = check connection->createSession();
    jms:MessageConsumer consumer = check session.createConsumer(
        destination = {
            'type: jms:QUEUE,
            name: "MyQueue"
    });
    while true {
        jms:Message? response = check consumer->receive(3000);
        if response is jms:TextMessage {
            log:printInfo("Message received: ", content = response.toString());
        }
    }
}

Asynchronous message consumer

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

import ballerinax/activemq.driver as _;
import ballerina/log;
import ballerinax/java.jms;

service "consumer-service" on new jms:Listener(
    connectionConfig = {
        initialContextFactory: "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
        providerUrl: "tcp://localhost:61616"
    },
    consumerOptions = {
        destination: {
            'type: jms:QUEUE,
            name: "MyQueue"
        }
    }
) {
    remote function onMessage(jms:Message message) returns error? {
        if message is jms:TextMessage {
            log:printInfo("Text message received", content = message.content);
        }
    }
}

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.

This repository only contains the source code for the library.

Build from the source

Set up the prerequisites

1. Download and install Java SE Development Kit (JDK) version 17 (from one of the following locations).

   • Oracle

   • OpenJDK

     Note: Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.

2. Generate a Github access token with read package permissions, then set the following env variables:

   export packageUser=<Your GitHub Username>
   export packagePAT=<GitHub Personal Access Token>

3. Download and install Docker. 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.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

• For more information go to the java.jms library.
• For example demonstrations of the usage, go to Ballerina By Examples.
• Chat live with us via our Discord server.
• Post all technical questions on Stack Overflow with the #ballerina tag.