Module asb
ballerinax/asb Ballerina library
Overview
The Ballerina connector for Azure Service Bus allows you to connect to an Azure Service Bus via the Ballerina language.
The Azure Service Bus is a fully managed enterprise message broker with message queues and publish-subscribe topics.It provides the capability to send and receive messages from Service Bus queues, topics, and subscriptions. The Azure Service Bus handles messages that include data representing any kind of information, including structured data encoded with the common formats such as the following ones: JSON, XML, Plain Text.
This module also supports asynchronous message listening capabilities from the azure service bus. Service Bus provides a Microsoft supported native Java API ( SDK) and this module make use of this public API . As the public API applies SAS authentication, this module supports SAS authentication as well.
This module supports Service Bus SDK 7.13.1 version . The source code on GitHub is located here. The primary wire protocol for Service Bus is Advanced Messaging Queueing Protocol (AMQP) 1.0, an open ISO/IEC standard.
Prerequisites
Before using this connector in your Ballerina application, complete the following:
-
Create an Azure account and a subscription. If you don't have an Azure subscription, sign up for a free Azure account.
-
Create a Service Bus namespace. If you don't have a service bus namespace , learn how to create your Service Bus namespace.
-
Create a messaging entity, such as a queue, topic or subscription. If you don't have these items, learn how to
-
Obtain tokens
Shared Access Signature (SAS) Authentication Credentials are required to communicate with the Azure Service Bus.
- Connection String
Obtain the authorization credentials:
-
For Service Bus Queues
-
Create a queue in the Azure portal & get queue name . It is in the format ‘queueName’.
-
For Service Bus Topics and Subscriptions
-
Create a topic in the Azure portal & get topic name . It's in the format ‘topicName‘.
-
Create a subscription in the Azure portal & get its name . It’s in the format ‘topicName/subscriptions/subscriptionName’.
Quickstart
To use the Azure Service Bus connector in your Ballerina application, update the .bal file as follows:
Enabling Azure SDK Logs
To enable Azure logs in a Ballerina module, you need to set the environment variable ASB_CLOUD_LOGS to ACTIVE. You can do this by adding the following line to your shell script or using the export command in your terminal(to deactivate,remove the variable value):
export ASB_CLOUD_LOGS=ACTIVE
Enabling Internal Connector Logs
To enable internal connector logs in a Ballerina module, you need to set the log level in the Config.toml file using the custom configuration record Where <log_level> is the desired log level (e.g. DEBUG, INFO, WARN, ERROR, FATAL, (Default)OFF)
[ballerinax.asb.customConfiguration] logLevel="OFF"
Step 1: Import connector
Import the ballerinax/asb
module into the Ballerina project.
import ballerinax/asb as asb;
Step 2: Create a new connector instance
Initialize a Message Sender client
This can be done providing connection string with queue or topic name.
asb:MessageSender queueSender = check new (senderConfig); asb:MessageSender topicSender = check new (senderConfig);
Initialize a Message Receiver client
This can be done providing connection string with queue name, topic name or subscription path. Here, Receive mode is optional. (Default : PEEKLOCK)
asb:MessageReceiver queueReceiver = check new (receiverConfig); asb:MessageReceiver subscriptionReceiver = check new (receiverConfig);
Step 3: Invoke connector operation
-
Now you can use the operations available within the connector. Note that they are in the form of remote operations.
Following is an example on how to send messages to the Azure Service Bus using the connector.
Send a message to the Azure Service Bus
public function main() returns error? { asb:MessageSender queueSender = check new (senderConfig); string stringContent = "This is My Message Body"; byte[] byteContent = stringContent.toBytes(); int timeToLive = 60; // In seconds asb:ApplicationProperties applicationProperties = { properties: {a: "propertyValue1", b: "propertyValue2"} }; asb:Message message = { body: byteContent, contentType: asb:TEXT, timeToLive: timeToLive, applicationProperties: applicationProperties }; check queueSender->send(message); check queueSender->close(); }
Following is an example on how to receive messages from the Azure Service Bus using the client connector.Optionally you can provide the receive mode which is PEEKLOCK by default. You can find more information about the receive modes here .
Receive a message from the Azure Service Bus
public function main() returns error? { asb:MessageReceiver queueReceiver = check new (receiverConfig); int serverWaitTime = 60; // In seconds asb:Message|asb:Error? messageReceived = queueReceiver->receive(serverWaitTime); if (messageReceived is asb:Message) { log:printInfo("Reading Received Message : " + messageReceived.toString()); } else if (messageReceived is ()) { log:printError("No message in the queue."); } else { log:printError("Receiving message via Asb receiver connection failed."); } check queueReceiver->close(); }
!!! NOTE: Currently we are using the asb:Message record for both sender & receiver operations. When we use the ASB receiver connector instead of the ASB listener to receive messages we return the exact message converted (re-engineered) to the specific data type based on the content type of the message. But in the ASB listener we receive the message body as byte[] which is the standard according to the AMQP protocol. We haven't re-engineered the listener. Rather we provide the message body as a standard byte[]. So the user must do the conversion based on the content type of the message. We have provided a sample code segment above, where you can do the conversion easily.
-
Use
bal run
command to compile and run the Ballerina program.