ballerina/mb package

Package overview

The ballerina/mb package provides an API to connect to a Ballerina Message Broker instance.

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

  • SimpleQueueReceiver
  • SimpleTopicSubscriber
  • SimpleDurableTopicSubscriber
  • SimpleQueueSender
  • SimpleTopicPublisher

Samples

Simple Queue Receiver

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

import ballerina/mb;
import ballerina/log;

// Create a simple queue receiver.
mb:SimpleQueueReceiver receiver {
   host: "localhost",
   port: 5672,
   queueName: "MyQueue"
};

// Bind the receiver to the queue to get the messages.
service<mb:Consumer> mbListener bind receiver {

   // Receive the messages that come to the queue.
   onMessage(endpoint consumer, mb:Message message) {
       match (message.getTextMessageContent()) {
           string messageText => log:printInfo("Message : " + messageText);
           error e => log:printError("Error occurred while reading message", err=e);
       }
   }
}

Simple Queue Sender

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

import ballerina/mb;
import ballerina/log;

// Create a queue sender.
endpoint mb:SimpleQueueSender queueSender {
   host: "localhost",
   port: 5672,
   queueName: "MyQueue"
};

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

       mb: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
BrokerURLConfig Configurations related to Ballerina message broker URL
ConsumerEndpointConfiguration
ServiceSecureSocket Configurations related to TLS
SimpleDurableTopicSubscriberEndpointConfiguration Configuration related to simple topic subscriber endpoint
SimpleQueueListenerEndpointConfiguration Configurations related to SimpleQueueReceiver endpoint
SimpleQueueSenderEndpointConfiguration Configurations related to SimpleQueueSender endpoint
SimpleTopicPublisherEndpointConfiguration Configurations related to SimpleQueueSender endpoint
SimpleTopicSubscriberEndpointConfiguration Configuration related to simple topic subscriber endpoint
Store

Objects Summary

Object Description
Consumer
ConsumerActions
DurableTopicSubscriberActions
Message

Represent the MB message used to send and receive content from the a Ballerina Message Broker.

A message 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.

QueueReceiverActions

Caller action handler related to SimpleQueueReceiver endpoint

QueueSenderActions

Caller action handler related to SimpleQueueSender endpoint

TopicPublisherActions

Caller action handler related to SimpleQueuePublisher endpoint

TopicSubscriberActions

Actions that topic subscriber endpoint could perform

Endpoints Summary

Endpoint Description
ConsumerTemplate
SimpleDurableTopicSubscriber

Simple Durable Topic Subscriber endpoint

SimpleQueueReceiver

Simplified queue receiver endpoint. A new connection and a session will be create when this endpoint is initialize.

SimpleQueueSender

Simplified queue sender endpoint. A new connection and a session will be create when this endpoint is initialize.

SimpleTopicPublisher

Simplified topic publisher A new connection and a session will be create when this endpoint is initialize.

SimpleTopicSubscriber

Ballerina message broker simple topic subscriber

public type BrokerURLConfig

Configurations related to Ballerina message broker URL

Field Name Data Type Default Value Description
username string admin

The caller's user name

password string admin

The caller's password

host string localhost

Hostname of the broker node

port int 5672

AMQP port of the broker node

clientID string ballerina

Identifier used to uniquely identify the client connection

virtualHost string default

target virtualhost

secureSocket mb:0.0.0:ServiceSecureSocket?

TLS configurations

public type ConsumerEndpointConfiguration

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

public type ServiceSecureSocket

Configurations related to TLS

Field Name Data Type Default Value Description
trustStore mb:0.0.0:Store?

Trustore configurations

keyStore mb:0.0.0:Store?

Keystore configuration

sslCertAlias string

name of the ssl cert alias

public type SimpleDurableTopicSubscriberEndpointConfiguration

Configuration related to simple topic subscriber endpoint

Field Name Data Type Default Value Description
username string admin

Valid user to connect to the Ballerina message broker

password string admin

Password of the user

host string localhost

Hostname of the Ballerina message broker

port int 5672

Hostname of the Ballerina message broker

clientID string ballerina

Used to identify the JMS client

virtualHost string default

Name of the virtual host where the virtual host is a path that acts as a namespace

secureSocket mb:0.0.0:ServiceSecureSocket?
connectionFactoryName string ConnectionFactory

JNDI name of the connection factory

acknowledgementMode string AUTO_ACKNOWLEDGE

JMS session acknowledgement mode. Legal values are "AUTO_ACKNOWLEDGE", "CLIENT_ACKNOWLEDGE", "SESSION_TRANSACTED" and "DUPS_OK_ACKNOWLEDGE"

identifier string
properties map

JMS message properties

messageSelector string

Message selector condition to filter messages

topicPattern string

Topic name pattern

public type SimpleQueueListenerEndpointConfiguration

Configurations related to SimpleQueueReceiver endpoint

Field Name Data Type Default Value Description
username string admin

The caller's user name

password string admin

The caller's password

host string localhost

Hostname of the broker node

port int 5672

AMQP port of the broker node

clientID string ballerina

Identifier used to uniquely identify the client connection

virtualHost string default

target virtualhost

secureSocket mb:0.0.0:ServiceSecureSocket?
connectionFactoryName string ConnectionFactory
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 SimpleQueueSender endpoint

Field Name Data Type Default Value Description
username string admin

The caller's user name

password string admin

The caller's password

host string localhost

Hostname of the broker node

port int 5672

AMQP port of the broker node

clientID string ballerina

Identifier used to uniquely identify the client connection

virtualHost string default

target virtualhost

secureSocket mb:0.0.0:ServiceSecureSocket?
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

Configurations related to SimpleQueueSender endpoint

Field Name Data Type Default Value Description
username string admin

The caller's user name

password string admin

The caller's password

host string localhost

Hostname of the broker node

port int 5672

AMQP port of the broker node

clientID string ballerina

Identifier used to uniquely identify the client connection

virtualHost string default

target virtualhost

secureSocket mb:0.0.0:ServiceSecureSocket?
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

topicPattern string

name of the target topic

public type SimpleTopicSubscriberEndpointConfiguration

Configuration related to simple topic subscriber endpoint

Field Name Data Type Default Value Description
username string admin

Valid user to connect to the Ballerina message broker

password string admin

Password of the user

host string localhost

Hostname of the Ballerina message broker

port int 5672

Hostname of the Ballerina message broker

clientID string ballerina

Used to identify the JMS client

virtualHost string default

Name of the virtual host where the virtual host is a path that acts as a namespace

secureSocket mb:0.0.0:ServiceSecureSocket?
connectionFactoryName string ConnectionFactory

JNDI name of the connection factory

acknowledgementMode string AUTO_ACKNOWLEDGE

JMS session acknowledgement mode. Legal values are "AUTO_ACKNOWLEDGE", "CLIENT_ACKNOWLEDGE", "SESSION_TRANSACTED" and "DUPS_OK_ACKNOWLEDGE"

messageSelector string

Message selector condition to filter messages

properties map

JMS message properties

topicPattern string

Topic name pattern

public type Store

Field Name Data Type Default Value Description
path string

file path to key store

password string

password used to protect the key store

public type Consumer object

  • <Consumer> getEndpoint() returns (ConsumerTemplate)

    Return Type Description
    ConsumerTemplate

public type ConsumerActions object

  • <ConsumerActions> acknowledge(mb:0.0.0:Message message) returns (error)

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error

public type DurableTopicSubscriberActions object

Field Name Data Type Default Value Description
helper jms:SimpleDurableTopicSubscriberActions
  • <DurableTopicSubscriberActions> new(jms:SimpleDurableTopicSubscriberActions helper)

    Parameter Name Data Type Default Value Description
    helper jms:SimpleDurableTopicSubscriberActions
  • <DurableTopicSubscriberActions> acknowledge(mb:0.0.0:Message message) returns (error)

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error
  • <DurableTopicSubscriberActions> receive(int timeoutInMilliSeconds) returns (Message | error)

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int 0
    Return Type Description
    Message | error
  • <DurableTopicSubscriberActions> unsubscribe() returns (error)

    Unsubscribes the durable subscriber from topic

    Return Type Description
    error

public type Message object

Represent the MB message used to send and receive content from the a Ballerina Message Broker.

A message 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> new(jms:Message message)

    Parameter Name Data Type Default Value Description
    message jms:Message
  • <Message> getTextMessageContent() returns (string | error)

    Gets text content of the MB 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)

    Attach a string property to 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 MB error

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

    Gets the attached 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)

    Attach an integer property to 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 MB error

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

    Gets the attached 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 MB error

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

    Attach an boolean property to 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 MB error

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

    Gets the attached 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 MB error

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

    Attach a float property to 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 MB error

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

    Gets the attached 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 MB error

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

    Gets the MessageID header from the message

    Return Type Description
    string | error

    The header value or MB error

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

    Gets the Timestamp header from the message

    Return Type Description
    int | error

    The timestamp header value or MB error

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

    Sets the DeliveryMode header in the message

    Parameter Name Data Type Default Value Description
    mode int

    The header value

    Return Type Description
    error

    nil or an MB error

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

    Gets the transport header DeliveryMode from the message

    Return Type Description
    int | error

    The delivery mode header value or MB error

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

    Sets Expiration header to the message

    Parameter Name Data Type Default Value Description
    value int

    The header value

    Return Type Description
    error

    nil or an MB error

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

    Gets expiration header from the message

    Return Type Description
    int | error

    The expiration header value or MB error

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

    Sets message type 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 MB error if any JMS provider level internal error occur

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

    Gets message type header from the message

    Return Type Description
    string | error

    The JMS message type header value or JMS error

  • <Message> clearProperties() returns (error)

    Clear properties of the message

    Return Type Description
    error

    nil or an MB error

  • <Message> clearBody() returns (error)

    Clears body of the message

    Return Type Description
    error

    nil or an MB error

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

    Sets priority header to the message

    Parameter Name Data Type Default Value Description
    value int

    The header value

    Return Type Description
    error

    nil or an MB error

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

    Gets priority header from the message

    Return Type Description
    int | error

    The priority header value or an MB error

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

    Gets the redelivered header from the message

    Return Type Description
    boolean | error

    The redelivered header value or an MB error

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

    Sets CorrelationID header to the message

    Parameter Name Data Type Default Value Description
    value string

    The header value

    Return Type Description
    error

    nil or an MB error

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

    Gets CorrelationID header from the message

    Return Type Description
    string | error

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

public type QueueReceiverActions object

Caller action handler related to SimpleQueueReceiver endpoint

Field Name Data Type Default Value Description
helper jms:QueueReceiverActions
  • <QueueReceiverActions> new(jms:QueueReceiverActions helper)

    Parameter Name Data Type Default Value Description
    helper jms:QueueReceiverActions
  • <QueueReceiverActions> acknowledge(mb:0.0.0:Message message) returns (error)

    Acknowledges a received message

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message

    message to be acknowledged

    Return Type Description
    error
  • <QueueReceiverActions> receive(int timeoutInMilliSeconds) returns (Message | error)

    Synchronously receive a message from Ballerina message broker

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int 0

    time to wait until a message is received

    Return Type Description
    Message | error

    Returns a message or nill if the timeout exceededs. Returns an error on broker internal error.

public type QueueSenderActions object

Caller action handler related to SimpleQueueSender endpoint

  • <QueueSenderActions> send(mb:0.0.0:Message message) returns (error)

    Sends a message to Ballerina message broker

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message

    message to be sent to Ballerina message broker

    Return Type Description
    error

public type TopicPublisherActions object

Caller action handler related to SimpleQueuePublisher endpoint

  • <TopicPublisherActions> send(mb:0.0.0:Message message) returns (error)

    Sends a message to Ballerina message broker

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message

    message to be sent to Ballerina message broker

    Return Type Description
    error

public type TopicSubscriberActions object

Actions that topic subscriber endpoint could perform

Field Name Data Type Default Value Description
helper jms:TopicSubscriberActions
  • <TopicSubscriberActions> new(jms:TopicSubscriberActions helper)

    Parameter Name Data Type Default Value Description
    helper jms:TopicSubscriberActions
  • <TopicSubscriberActions> acknowledge(mb:0.0.0:Message message) returns (error)

    Acknowledges a received message

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message

    Message to be acknowledged

    Return Type Description
    error
  • <TopicSubscriberActions> receive(int timeoutInMilliSeconds) returns (Message | error)

    Synchronously receive a message from Ballerina message broker

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int 0

    Time to wait until a message is received

    Return Type Description
    Message | error

    Returns a message or nill if the timeout exceededs. Returns an error on broker internal error.

Endpoint ConsumerTemplate

Field Name Data Type Default Value Description
callerActions mb:0.0.0:ConsumerActions
config mb:0.0.0:ConsumerEndpointConfiguration
  • <ConsumerTemplate> acknowledge(mb:0.0.0:Message message) returns (error?)

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?

Endpoint SimpleDurableTopicSubscriber

Simple Durable Topic Subscriber endpoint

Field Name Data Type Default Value Description
config mb:0.0.0:SimpleDurableTopicSubscriberEndpointConfiguration

configurations related to the endpoint

  • <SimpleDurableTopicSubscriber> acknowledge(mb:0.0.0:Message message) returns (error?)

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?
  • <SimpleDurableTopicSubscriber> receive(int timeoutInMilliSeconds) returns (mb:0.0.0:Message|error?)

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int
    Return Type Description
    mb:0.0.0:Message|error?
  • <SimpleDurableTopicSubscriber> unsubscribe() returns (error?)

    Unsubscribes the durable subscriber from topic

    Return Type Description
    error?

Endpoint SimpleQueueReceiver

Simplified queue receiver endpoint. A new connection and a session will be create when this endpoint is initialize.

Field Name Data Type Default Value Description
config mb:0.0.0:SimpleQueueListenerEndpointConfiguration

configurations related to the SimpleQueueReceiver endpoint

  • <SimpleQueueReceiver> acknowledge(mb:0.0.0:Message message) returns (error?)

    Acknowledges a received message

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?
  • <SimpleQueueReceiver> receive(int timeoutInMilliSeconds) returns (mb:0.0.0:Message|error?)

    Synchronously receive a message from Ballerina message broker

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int
    Return Type Description
    mb:0.0.0:Message|error?

Endpoint SimpleQueueSender

Simplified queue sender endpoint. A new connection and a session will be create when this endpoint is initialize.

Field Name Data Type Default Value Description
config mb:0.0.0:SimpleQueueSenderEndpointConfiguration

configurations related to the SimpleQueueSender endpoint

  • <SimpleQueueSender> send(mb:0.0.0:Message message) returns (error?)

    Sends a message to Ballerina message broker

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?

Endpoint SimpleTopicPublisher

Simplified topic publisher A new connection and a session will be create when this endpoint is initialize.

Field Name Data Type Default Value Description
config mb:0.0.0:SimpleTopicPublisherEndpointConfiguration

configurations related to the SimpleTopicPublisher endpoint

  • <SimpleTopicPublisher> send(mb:0.0.0:Message message) returns (error?)

    Sends a message to Ballerina message broker

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?

Endpoint SimpleTopicSubscriber

Ballerina message broker simple topic subscriber

Field Name Data Type Default Value Description
config mb:0.0.0:SimpleTopicSubscriberEndpointConfiguration

Simple topic subscrirber enpoint configuration

  • <SimpleTopicSubscriber> acknowledge(mb:0.0.0:Message message) returns (error?)

    Acknowledges a received message

    Parameter Name Data Type Default Value Description
    message mb:0.0.0:Message
    Return Type Description
    error?
  • <SimpleTopicSubscriber> receive(int timeoutInMilliSeconds) returns (mb:0.0.0:Message|error?)

    Synchronously receive a message from Ballerina message broker

    Parameter Name Data Type Default Value Description
    timeoutInMilliSeconds int
    Return Type Description
    mb:0.0.0:Message|error?