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
ConsumerTemplate
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.

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:ServiceSecureSocket?

TLS configurations

public type ConsumerEndpointConfiguration

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

public type ServiceSecureSocket

Configurations related to TLS

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

Trustore configurations

keyStore mb: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: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: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: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: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: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:Message message) returns (error)

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

public type ConsumerTemplate object

Field Name Data Type Default Value Description
callerActions mb:ConsumerActions
config mb:ConsumerEndpointConfiguration

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(ballerina.jms:Message message)

    Parameter Name Data Type Default Value Description
    message ballerina.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