ballerina/jms package

Package overview

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

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

  • QueueReceiver
  • TopicSubscriber
  • DurableTopicSubscriber
  • SimpleQueueReceiver
  • SimpleTopicSubscriber
  • SimpleDurableTopicSubscriber
  • QueueReceiver
  • TopicSubscriber
  • DurableTopicSubscriber
  • SimpleQueueReceiver
  • SimpleTopicSubscriber
  • SimpleDurableTopicSubscriber

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 ballerina/jms;
import ballerina/log;

// Create a simple queue receiver.
endpoint jms:SimpleQueueReceiver consumer {
    initialContextFactory: "bmbInitialContextFactory",
    providerUrl: "amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'",
    acknowledgementMode: "AUTO_ACKNOWLEDGE",
    queueName: "MyQueue"
};

// Bind the created consumer to the listener service.
service<jms:Consumer> jmsListener bind consumer {

    // The `OnMessage` resource gets invoked when a message is received.
    onMessage(endpoint consumer, jms:Message message) {
        match (message.getTextMessageContent()) {
            string messageText => log:printInfo("Message : " + messageText);
            error e => log:printError("Error occurred while reading message", err = e);
        }
    }
}

JMS Simple Queue Producer.

Following is a simple queue sender program that sends messages to a Ballerina Message Broker queue named MyQueue.

import ballerina/jms;
import ballerina/log;

// Create a topic publisher.
endpoint jms:SimpleTopicPublisher topicPublisher {
    initialContextFactory: "bmbInitialContextFactory",
    providerUrl: "amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'",
    acknowledgementMode: "AUTO_ACKNOWLEDGE",
    topicPattern: "BallerinaTopic"
};

function main(string... args) {
    // Create a text message.
    match (topicPublisher.createTextMessage("Hello from Ballerina")) {
        error e => {
            log:printError("Error occurred while creating message", err = e);
        }

        jms:Message msg => {
            // Send the Ballerina message to the JMS provider.
            topicPublisher->send(msg) but {
                error e => log:printError("Error occurred while sending message", err = e)
            };
        }
    }
}

JMS queue message receiver

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

import ballerina/jms;
import ballerina/log;

// Initialize a JMS connection with the provider.
jms:Connection conn = new({
        initialContextFactory: "bmbInitialContextFactory",
        providerUrl: "amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'"
    });

// 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.
endpoint jms:QueueReceiver consumer {
    session: jmsSession,
    queueName: "MyQueue"
};

// Bind the created consumer to the listener service.
service<jms:Consumer> jmsListener bind consumer {

    // The `OnMessage` resource gets invoked when a message is received.
    onMessage(endpoint consumer, jms:Message message) {
        // Retrieve the text message.
        match (message.getTextMessageContent()) {
            string messageText => log:printInfo("Message : " + messageText);
            error e => log:printError("Error occurred while reading message", err = e);
        }
    }
}

JMS queue message producer

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

import ballerina/jms;
import ballerina/log;

// Initialize a JMS connection with the provider.
jms:Connection jmsConnection = new({
        initialContextFactory: "bmbInitialContextFactory",
        providerUrl: "amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'"
    });

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

endpoint jms:QueueSender queueSender {
    session: jmsSession,
    queueName: "MyQueue"
};

function main(string... args) {
    // Create a text message.
    match (jmsSession.createTextMessage("Hello from Ballerina")) {
        error e => {
            log:printError("Error occurred while creating message", err = e);
        }

        jms:Message msg => {
            // Send the Ballerina message to the JMS provider.
            queueSender->send(msg) but { error e => log:printError("Error occurred while sending message", err = e) };
        }
    }
}

Records Summary

Record Description
ConnectionConfiguration

Configurations related to a JMS connection

ConsumerEndpointConfiguration

Configurations related to a JMS consumer object

DurableTopicSubscriberEndpointConfiguration

Configurations related to the durable topic subscriber endpoint

QueueReceiverEndpointConfiguration

Configurations related to the QueueReceiver endpoint

QueueSenderEndpointConfiguration

Configurations related to a QueueSender object

SessionConfiguration

Configurations related to a JMS session

SimpleDurableTopicSubscriberEndpointConfiguration

Configurations of the simple durable topic subscriber endpoint

SimpleQueueReceiverEndpointConfiguration

Configurations related to the SimpleQueueReceiver endpoint

SimpleQueueSenderEndpointConfiguration

Configurations related to the SimpleQueueSender endpoint

SimpleTopicPublisherEndpointConfiguration

Configuration related to simple topic publisher endpoint

SimpleTopicSubscriberEndpointConfiguration

Configuration related to simple topic subscriber endpoint

TopicPublisherEndpointConfiguration

Configuration related to the topic publisher endpoint

TopicSubscriberEndpointConfiguration

Configuration related to topic subscriber endpoint

Objects Summary

Object Description
Connection

Represents JMS Connection

Consumer

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

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 JMS session

public type ConnectionConfiguration

Configurations related to a JMS connection

Field Name Data Type Default Value Description
initialContextFactory string wso2mbInitialContextFactory

JMS provider specific inital context factory

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

JMS provider specific provider URL used to configure a connection

connectionFactoryName string ConnectionFactory

JMS connection factory to be used in creating JMS connections

properties map

Additional properties use in initializing the initial context

public type ConsumerEndpointConfiguration

Configurations related to a JMS consumer object

Field Name Data Type Default Value Description
session jms:Session?

JMS session used to create the consumer

identifier string

Unique identifier of the consumer

public type DurableTopicSubscriberEndpointConfiguration

Configurations related to the durable topic subscriber endpoint

Field Name Data Type Default Value Description
session jms:Session?

JMS session object

topicPattern string

Name or the pattern of the topic subscription

messageSelector string

JMS selector statement

identifier string

unique identifier for the subscription

public type QueueReceiverEndpointConfiguration

Configurations related to the QueueReceiver endpoint

Field Name Data Type Default Value Description
session jms:Session?

JMS session object

queueName string

Name of the queue

messageSelector string

JMS selector statement

identifier string

unique identifier for the subscription

public type QueueSenderEndpointConfiguration

Configurations related to a QueueSender object

Field Name Data Type Default Value Description
session jms:Session?

JMS session object used to create the consumer

queueName string

name of the target queue

public type SessionConfiguration

Configurations related to a JMS session

Field Name Data Type Default Value Description
acknowledgementMode string AUTO_ACKNOWLEDGE

specifies the session mode that will be used. Legal values are "AUTO_ACKNOWLEDGE", "CLIENT_ACKNOWLEDGE", "SESSION_TRANSACTED" and "DUPS_OK_ACKNOWLEDGE"

public type SimpleDurableTopicSubscriberEndpointConfiguration

Configurations of the simple durable topic subscriber endpoint

Field Name Data Type Default Value Description
initialContextFactory string bmbInitialContextFactory

JMS initial context factory name

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

Connection url of the JMS provider

connectionFactoryName string ConnectionFactory

Name of the JMS connection factory created

acknowledgementMode string AUTO_ACKNOWLEDGE

Sets the acknowledgment mode for the underlying session. String representation of the JMS acknowledgment mode needs to be provided.

identifier string

Unique identifier for the subscriber

properties map

Custom properties related to JMS provider

messageSelector string

JMS selector statement

topicPattern string

Name or the pattern of the topic subscription

public type SimpleQueueReceiverEndpointConfiguration

Configurations related to the SimpleQueueReceiver endpoint

Field Name Data Type Default Value Description
initialContextFactory string bmbInitialContextFactory

JMS provider specific inital context factory

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

JMS provider specific provider URL used to configure a connection

connectionFactoryName string ConnectionFactory

JMS connection factory to be used in creating JMS connections

acknowledgementMode string AUTO_ACKNOWLEDGE

specifies the session mode that will be used. Legal values are "AUTO_ACKNOWLEDGE", "CLIENT_ACKNOWLEDGE", "SESSION_TRANSACTED" and "DUPS_OK_ACKNOWLEDGE"

messageSelector string

JMS selector statement

properties map

Additional properties use in initializing the initial context

queueName string

Name of the target queue

public type SimpleQueueSenderEndpointConfiguration

Configurations related to the SimpleQueueSender endpoint

Field Name Data Type Default Value Description
initialContextFactory string bmbInitialContextFactory

JMS provider specific inital context factory

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

JMS provider specific provider URL used to configure a connection

connectionFactoryName string ConnectionFactory

JMS connection factory to be used in creating JMS connections

acknowledgementMode string AUTO_ACKNOWLEDGE

specifies the session mode that will be used. Legal values are "AUTO_ACKNOWLEDGE", "CLIENT_ACKNOWLEDGE", "SESSION_TRANSACTED" and "DUPS_OK_ACKNOWLEDGE"

properties map

Additional properties use in initializing the initial context

queueName string

Name of the target queue

public type SimpleTopicPublisherEndpointConfiguration

Configuration related to simple topic publisher endpoint

Field Name Data Type Default Value Description
initialContextFactory string bmbInitialContextFactory

JNDI initial context factory class

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

JNDI provider URL

connectionFactoryName string ConnectionFactory

JNDI name of the connection factory

acknowledgementMode string AUTO_ACKNOWLEDGE

JMS session acknwoledge mode

properties map

JMS message properties

topicPattern string

name of the target topic

public type SimpleTopicSubscriberEndpointConfiguration

Configuration related to simple topic subscriber endpoint

Field Name Data Type Default Value Description
initialContextFactory string bmbInitialContextFactory

JNDI initial context factory class

providerUrl string amqp://admin:admin@ballerina/default?brokerlist='tcp://localhost:5672'

JNDI provider URL

connectionFactoryName string ConnectionFactory

JNDI name of the connection factory

acknowledgementMode string AUTO_ACKNOWLEDGE

JMS session acknwoledge mode

messageSelector string

Message selector condition to filter messages

properties map

JMS message properties

topicPattern string

Topic name pattern

public type TopicPublisherEndpointConfiguration

Configuration related to the topic publisher endpoint

Field Name Data Type Default Value Description
session jms:Session?

Session object used to create topic publisher

topicPattern string

Topic name pattern

public type TopicSubscriberEndpointConfiguration

Configuration related to topic subscriber endpoint

Field Name Data Type Default Value Description
session jms:Session?

Session object used to create topic subscriber

topicPattern string

Topic name pattern

messageSelector string

Message selector condition to filter messages

identifier string

Identifier of topic subscriber endpoint

public type Connection object

Represents JMS Connection

Field Name Data Type Default Value Description
config jms:ConnectionConfiguration

Used to store configurations related to a JMS connection

  • <Connection> new(jms:ConnectionConfiguration config)

    JMS connection constructor

    Parameter Name Data Type Default Value Description
    config jms:ConnectionConfiguration

public type Consumer object

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

  • <Consumer> getEndpoint() returns (ConsumerTemplate)

    Returns the endpoint bound to service

    Return Type Description
    ConsumerTemplate

    JMS consumer endpoint bound to the service

public type Message object

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.

  • <Message> getTextMessageContent() returns (string | error)

    Gets text content of the JMS message

    Return Type Description
    string | error

    the string containing this message's data or an JMS error

  • <Message> setStringProperty(string key, string value) returns (error)

    Sets a JMS transport string property from the message

    Parameter Name Data Type Default Value Description
    key string

    The string property name

    value string

    The string property value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getStringProperty(string key) returns (string | error)

    Gets a JMS transport string property from the message

    Parameter Name Data Type Default Value Description
    key string

    The string property name

    Return Type Description
    string | error

    The string property value, JMS error or nil if there is no property by this name

  • <Message> setIntProperty(string key, int value) returns (error)

    Sets a JMS transport integer property from the message

    Parameter Name Data Type Default Value Description
    key string

    The integer property name

    value int

    The integer property value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getIntProperty(string key) returns (int | error)

    Gets a JMS transport integer property from the message

    Parameter Name Data Type Default Value Description
    key string

    The integer property name

    Return Type Description
    int | error

    The integer property value or JMS error

  • <Message> setBooleanProperty(string key, boolean value) returns (error)

    Sets a JMS transport boolean property from the message

    Parameter Name Data Type Default Value Description
    key string

    The boolean property name

    value boolean

    The boolean property value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getBooleanProperty(string key) returns (boolean | error)

    Gets a JMS transport boolean property from the message

    Parameter Name Data Type Default Value Description
    key string

    The boolean property name

    Return Type Description
    boolean | error

    The boolean property value or JMS error

  • <Message> setFloatProperty(string key, float value) returns (error)

    Sets a JMS transport float property from the message

    Parameter Name Data Type Default Value Description
    key string

    The float property name

    value float

    The float property value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getFloatProperty(string key) returns (float | error)

    Gets a JMS transport float property from the message

    Parameter Name Data Type Default Value Description
    key string

    The float property name

    Return Type Description
    float | error

    The float property value or JMS error

  • <Message> getMessageID() returns (string | error)

    Gets JMS transport header MessageID from the message

    Return Type Description
    string | error

    The header value or JMS error

  • <Message> getTimestamp() returns (int | error)

    Gets JMS transport header Timestamp from the message

    Return Type Description
    int | error

    The timestamp header value or JMS error

  • <Message> setDeliveryMode(int mode) returns (error)

    Sets DeliveryMode JMS transport header to the message

    Parameter Name Data Type Default Value Description
    mode int

    The header value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getDeliveryMode() returns (int | error)

    Get JMS transport header DeliveryMode from the message

    Return Type Description
    int | error

    The delivery mode header value or JMS error

  • <Message> setExpiration(int value) returns (error)

    Sets Expiration JMS transport header to the message

    Parameter Name Data Type Default Value Description
    value int

    The header value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getExpiration() returns (int | error)

    Gets JMS transport header Expiration from the message

    Return Type Description
    int | error

    The expiration header value or JMS error

  • <Message> setType(string messageType) returns (error)

    Sets Type JMS transport header to the message

    Parameter Name Data Type Default Value Description
    messageType string

    The message type header value

    Return Type Description
    error

    nil or an JMS error if any JMS provider level internal error occur

  • <Message> getType() returns (string | error)

    Gets JMS transport header Type from the message

    Return Type Description
    string | error

    The JMS message type header value or JMS error

  • <Message> clearProperties() returns (error)

    Clears JMS properties of the message

    Return Type Description
    error

    nil or error if any JMS provider level internal error occur

  • <Message> clearBody() returns (error)

    Clears body of the JMS message

    Return Type Description
    error

    nil or an JMS error

  • <Message> setPriority(int value) returns (error)

    Sets priority JMS transport header to the message

    Parameter Name Data Type Default Value Description
    value int

    The header value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getPriority() returns (int | error)

    Gets JMS transport header Priority from the message

    Return Type Description
    int | error

    The JMS priority header value or error

  • <Message> getRedelivered() returns (boolean | error)

    Gets JMS transport header Redelivered from the message

    Return Type Description
    boolean | error

    The JMS redelivered header value or JMS error

  • <Message> setCorrelationID(string value) returns (error)

    Sets CorrelationID JMS transport header to the message

    Parameter Name Data Type Default Value Description
    value string

    The header value

    Return Type Description
    error

    nil or an JMS error

  • <Message> getCorrelationID() returns (string | error)

    Gets JMS transport header CorrelationID from the message

    Return Type Description
    string | error

    The JMS correlation ID header value or JMS error or nil if header is not set

public type Session object

Represents JMS session

Field Name Data Type Default Value Description
config jms:SessionConfiguration

Used to store configurations related to a JMS session

  • <Session> new(jms:Connection connection, jms:SessionConfiguration config)

    Default constructor of the JMS session

    Parameter Name Data Type Default Value Description
    connection jms:Connection
    config jms:SessionConfiguration
  • <Session> createTextMessage(string content) returns (Message | error)

    Creates a JMS message which holds text content

    Parameter Name Data Type Default Value Description
    content string

    the text content used to initialize this message

    Return Type Description
    Message | error
  • <Session> unsubscribe(string subscriptionId) returns (error)

    Unsubscribes a durable subscription that has been created by a client. It is erroneous for a client to delete a durable subscription while there is an active (not closed) consumer for the subscription, or while a consumed message is part of a pending transaction or has not been acknowledged in the session.

    Parameter Name Data Type Default Value Description
    subscriptionId string

    the name used to identify this subscription

    Return Type Description
    error