Module : jms

Module overview

The ballerina/jms module provides an API to connect to an external JMS provider like Ballerina Message Broker or ActiveMQ.

The module provides consumer and producer endpoint types for queues and topics. Following are the endpoint types supported by this module:

The endpoints prefixed with Simple will automatically create a JMS connection and a JMS session when the endpoint is initialized. For other endpoints, the developer must explicitly provide a properly initialized JMS Session.

Samples

JMS Simple Queue Consumer

Following is a simple listener program that consumes messages from a Ballerina Message Broker queue named MyQueue.

import ballerinax/jms;
import ballerina/log;

// Create a simple queue receiver.
listener jms:QueueListener consumerEP = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616",
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
    }, queueName = "MyQueue");

// Bind the created consumer to the listener service.
service jmsListener on consumerEP {

    // The `OnMessage` resource gets invoked when a message is received.
    resource function onMessage(jms:QueueReceiverCaller consumer, jms:Message message) {
        var msg = message.getTextMessageContent();
        if (msg is string) {
            log:printInfo("Message : " + msg);
        } else {
            log:printError("Error occurred while reading message", err = msg);
        }
    }
}

JMS Simple Topic publisher.

Following is a simple topic publisher program that sends messages to a Ballerina Message Broker topic named MyTopic.

import ballerinax/jms;
import ballerina/log;

// Create a topic publisher.
jms:TopicPublisher topicPublisher = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616",
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
    }, topicPattern = "MyTopic");

public function main(string... args) {
    // Create a text message.
    var msg = topicPublisher.session.createTextMessage("Hello from Ballerina");
    if (msg is jms:Message) {
        var result = topicPublisher->send(msg);
        if (result is error) {
            log:printError("Error occurred while sending message", err = result);
        }
    } else {
        log:printError("Error occurred while creating message", err = msg);       
    }
}

JMS Queue Message Receiver

Following is a listener program that explicitly initializes a JMS session to be used in the consumer.

import ballerinax/jms;
import ballerina/log;

// Initialize a JMS connection with the provider.
jms:Connection conn = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616"
});

// Initialize a JMS session on top of the created connection.
jms:Session jmsSession = new(conn, {
    // An optional property that defaults to `AUTO_ACKNOWLEDGE`.
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
});

// Initialize a queue receiver using the created session.
listener jms:QueueListener consumerEP = new(jmsSession, queueName = "MyQueue");

// Bind the created consumer to the listener service.
service jmsListener on consumerEP {

    // The `OnMessage` resource gets invoked when a message is received.
    resource function onMessage(jms:QueueReceiverCaller consumer, jms:Message message) {
        // Retrieve the text message.
        var msg = message.getTextMessageContent();
        if (msg is string) {
            log:printInfo("Message : " + msg);
        } else {
            log:printError("Error occurred while reading message", err = msg);
        }
    }
}

JMS Queue Message Producer

Following is a queue sender program that explicitly initializes a JMS session to be used in the producer.

import ballerinax/jms;
import ballerina/log;

// Initialize a JMS connection with the provider.
jms:Connection jmsConnection = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616"
});

// Initialize a JMS session on top of the created connection.
jms:Session jmsSession = new(jmsConnection, {
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
});

jms:QueueSender queueSender = new(jmsSession, queueName = "MyQueue");

public function main(string... args) {
    // Create a text message.
    var msg = jmsSession.createTextMessage("Hello from Ballerina");
    if (msg is error) {
        log:printError("Error occurred while creating message", err = msg);
    } else {
        var result = queueSender->send(msg);
        if (result is error) {
            log:printError("Error occurred while sending message", err = result);
        }
    }
}

JMS Topic Subscriber

Following is a topic subscriber program that subscribes to a particular JMS topic.

import ballerinax/jms;
import ballerina/log;

jms:Connection conn = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616"
});

jms:Session jmsSession = new(conn, {
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
});

listener jms:TopicListener subscriberEndpoint = new(jmsSession, topicPattern = "MyTopic");

service jmsListener on subscriberEndpoint {
    resource function onMessage(jms:TopicSubscriberCaller subscriber, jms:Message message) {
        var msg = message.getTextMessageContent();
        if (msg is string) {
            log:printInfo("Message : " + msg);
        } else {
            log:printError("Error occurred while reading message", err = msg);
        }
    }
}

JMS Topic Producer

Following is a topic producer program that publishes to a particular JMS topic.

import ballerinax/jms;
import ballerina/log;

jms:Connection jmsConnection = new({
    initialContextFactory: "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory",
    providerUrl: "tcp://localhost:61616"
});

jms:Session jmsSession = new(jmsConnection, {
    acknowledgementMode: "AUTO_ACKNOWLEDGE"
});

jms:TopicPublisher topicPublisher = new(jmsSession, topicPattern = "MyTopic");

public function main(string... args) {
    var msg = jmsSession.createTextMessage("Hello from Ballerina");
    if (msg is error) {
        log:printError("Error occurred while creating message", err = msg);
    } else {
        var result = topicPublisher->send(msg);
        if (result is error) {
            log:printError("Error occurred while sending message", err = result);
        }
    }
}

Records

ConnectionConfiguration Configurations related to a JMS connection
ConsumerEndpointConfiguration Configurations related to a JMS consumer object
ReceiverEndpointConfiguration Configuration related to simple topic subscriber endpoint
SenderEndpointConfiguration Configurations related to the sender
SessionConfiguration The Configurations that are related to a JMS session.

Objects

Connection

Represents JMS Connection

Consumer

JMS consumer service object. This has the capability to bind multiple types of JMS consumer endpoints.

ConsumerActions

JMS consumer action handling object

ConsumerTemplate

Represent a JMS consumer endpoint

Destination

Destination object

Message

Represent the JMS message used to send and receive content from the a JMS provider.

Most message-oriented middleware (MOM) products treat messages as lightweight entities that consist of a header and a body. The header contains fields used for message routing and identification; the body contains the application data being sent.

Session

Represents the JMS session.

Clients

DurableTopicSubscriberCaller

Caller actions related to the DurableTopicSubscriber.

QueueReceiverCaller

The Caller actions related to queue receiver endpoint.

QueueSender

JMS QueueSender Endpoint

TopicPublisher

JMS TopicPublisher endpoint

TopicSubscriberCaller

Remote functions that the topic subscriber endpoint could perform.

Listeners

DurableTopicListener

The JMS DurableTopicListener endpoint.

QueueListener

The Queue Receiver endpoint.

TopicListener

The JMS TopicListener.

Constants

QUEUE

Constant for JMS destination type queue

TOPIC

Constant for JMS destination type topic

JMS_ERROR_CODE