Actions

The ballerinax/java.jms package exposes the following clients:

Client	Purpose
Connection	Establishes a connection to the JMS broker and creates sessions.
Session	Manages transactions and creates message producers and consumers.
Message Producer	Sends messages to JMS queues and topics.
Message Consumer	Receives and acknowledges messages from JMS queues and topics.

For event-driven integration, see the Trigger Reference.

---

Connection

Establishes a connection to the JMS broker and creates sessions.

Configuration

Field	Type	Default	Description
initialContextFactory	string	Required	JNDI initial context factory class (e.g., org.apache.activemq.jndi.ActiveMQInitialContextFactory).
providerUrl	string	Required	JMS provider URL (e.g., tcp://localhost:61616).
connectionFactoryName	string	"ConnectionFactory"	JNDI name of the connection factory.
username	string	()	Username for broker authentication.
password	string	()	Password for broker authentication.
properties	map<string>	{}	Additional JNDI properties.

Initializing the client

import ballerinax/java.jms;

configurable string providerUrl = ?;

jms:Connection connection = check new ({
    initialContextFactory: "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
    providerUrl: providerUrl
});

Operations

Connection lifecycle

createSession

Creates a new JMS session with the specified acknowledgement mode.

Parameters:

Name	Type	Required	Description
ackMode	AcknowledgementMode	No	Session acknowledgement mode. One of AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, SESSION_TRANSACTED, or DUPS_OK_ACKNOWLEDGE.

Returns: jms:Session|jms:Error

Sample code:

jms:Session session = check connection->createSession(jms:AUTO_ACKNOWLEDGE);

Sample response:

jms:Session object

start

Starts the connection, enabling message delivery.

Returns: jms:Error?

Sample code:

check connection->start();

stop

Temporarily stops message delivery on the connection.

Returns: jms:Error?

Sample code:

check connection->stop();

close

Closes the connection and releases all resources.

Returns: jms:Error?

Sample code:

check connection->close();

---

Session

Manages transactions and creates message producers and consumers.

Configuration

Field	Type	Default	Description
connection	jms:Connection	Required	The JMS connection to create the session from.
ackMode	AcknowledgementMode	AUTO_ACKNOWLEDGE	Session acknowledgement mode.

Initializing the client

import ballerinax/java.jms;

// Sessions are typically created from a Connection:
jms:Session session = check connection->createSession(jms:AUTO_ACKNOWLEDGE);

Operations

Producer and consumer creation

createProducer

Creates a message producer, optionally bound to a default destination.

Parameters:

Name	Type	Required	Description
destination	Destination?	No	Default destination for the producer. If omitted, a destination must be specified per message.

Returns: jms:MessageProducer|jms:Error

Sample code:

jms:MessageProducer producer = check session.createProducer();

Sample response:

jms:MessageProducer object

createConsumer

Creates a message consumer for the specified destination.

Parameters:

Name	Type	Required	Description
destination	Destination	Yes	The queue or topic to consume from.
type	ConsumerType	No	Consumer type: DEFAULT, DURABLE, SHARED, or SHARED_DURABLE.
messageSelector	string	No	JMS message selector expression to filter messages.
noLocal	boolean	No	If true, messages published by this connection's producers are not delivered.
subscriberName	string	No	Subscription name, required for durable and shared-durable consumers.

Returns: jms:MessageConsumer|jms:Error

Sample code:

jms:MessageConsumer consumer = check session.createConsumer(
    destination = {'type: jms:QUEUE, name: "orders"}
);

Sample response:

jms:MessageConsumer object

Transaction control

commit

Commits all messages sent or received in the current transaction.

Returns: jms:Error?

Sample code:

check session->commit();

rollback

Rolls back all messages sent or received in the current transaction.

Returns: jms:Error?

Sample code:

check session->rollback();

Subscription management

unsubscribe

Removes a durable subscription by its subscription identifier.

Parameters:

Name	Type	Required	Description
subscriptionId	string	Yes	The name of the durable subscription to remove.

Returns: jms:Error?

Sample code:

check session->unsubscribe("my-durable-sub");

close

Closes the session and releases resources.

Returns: jms:Error?

Sample code:

check session->close();

---

Message producer

Sends messages to JMS queues and topics.

Configuration

Field	Type	Default	Description
session	jms:Session	Required	The JMS session used to create this producer.
destination	Destination?	()	Default destination. If set, send uses this destination.

Initializing the client

import ballerinax/java.jms;

// Producers are typically created from a Session:
jms:MessageProducer producer = check session.createProducer();

Operations

Send operations

send

Sends a message to the producer's default destination.

Parameters:

Name	Type	Required	Description
message	Message	Yes	The JMS message to send. Content can be string, map<Value>, or byte[].

Returns: jms:Error?

Sample code:

check producer->send({
    content: "Hello from Ballerina!"
});

sendTo

Sends a message to a specified destination, overriding the default.

Parameters:

Name	Type	Required	Description
destination	Destination	Yes	The target queue or topic.
message	Message	Yes	The JMS message to send.

Returns: jms:Error?

Sample code:

check producer->sendTo(
    {'type: jms:QUEUE, name: "orders"},
    {content: orderPayload.toJsonString().toBytes()}
);

close

Closes the producer and releases resources.

Returns: jms:Error?

Sample code:

check producer->close();

---

Message consumer

Receives and acknowledges messages from JMS queues and topics.

Configuration

Field	Type	Default	Description
destination	Destination	Required	The queue or topic to consume from.
type	ConsumerType	DEFAULT	Consumer type: DEFAULT, DURABLE, SHARED, or SHARED_DURABLE.
messageSelector	string	""	JMS message selector expression to filter messages.
noLocal	boolean	false	If true, excludes messages published by this connection's own producers.
subscriberName	string	()	Subscription name, required for DURABLE and SHARED_DURABLE types.

Initializing the client

import ballerinax/java.jms;

// Consumers are typically created from a Session:
jms:MessageConsumer consumer = check session.createConsumer(
    destination = {'type: jms:QUEUE, name: "orders"}
);

Operations

Receive operations

receive

Receives the next message from the destination, blocking until a message arrives or the timeout expires.

Parameters:

Name	Type	Required	Description
timeoutMillis	int	No	Maximum time to wait in milliseconds. Defaults to 10000.

Returns: jms:Message|jms:Error?

Sample code:

jms:Message? message = check consumer->receive(5000);

Sample response:

{"messageId": "ID:localhost-12345-1234567890", "timestamp": 1710600000000, "content": "Hello from Ballerina!", "priority": 4, "redelivered": false}

receiveNoWait

Receives the next available message without blocking. Returns () if no message is available.

Returns: jms:Message|jms:Error?

Sample code:

jms:Message? message = check consumer->receiveNoWait();

Sample response:

{"messageId": "ID:localhost-12345-1234567891", "timestamp": 1710600001000, "content": {"orderId": "ORD-001", "item": "Pizza"}, "priority": 4}

Acknowledgement

acknowledge

Acknowledges a received message. Used when the session is in CLIENT_ACKNOWLEDGE mode.

Parameters:

Name	Type	Required	Description
message	Message	Yes	The message to acknowledge.

Returns: jms:Error?

Sample code:

check consumer->acknowledge(message);

close

Closes the consumer and releases resources.

Returns: jms:Error?

Sample code:

check consumer->close();