Maninda's Blog: December 2019

Ballerina and it's Connectors

Ballerina is a general purpose programming language designed for system integration. Web Services and REST APIs can be integrated with Ballerina code. WSO2 Ballerina Integrator, supports many out of the box components, called Ballerina Connectors, to programatically integrate external services and APIs. For example, when you want to connect to a Salesforce API, you can import the Salesforce Connector module to the Ballerina code and call its methods to the relevant REST API provided by Salesforce.

Amazon Simple Queue Service (SQS)

Amazon SQS is a simple message queue API provided by Amazon. WSO2 Enterprise Integrator (WSO2 EI) provides Ballerina Amazon SQS Connector to programatically interact with the REST API provided by Amazon SQS. Once you have created an account in Amazon SQS, you can get the credentials for SQS service, which can be given to the Ballerina Connector as a configuration file or as configuration parameters. Then you can perform queue creation, enqueue, dequeue and message-delete operations by calling the respective API methods provided by the Connector.

Using SQS Connector

In this blog I am going to discuss the simplest way to run a Ballerina code with Amazon SQS Connector in Ubuntu/Linux console to create a SQS queue and send a message into it. For more information on usage of Ballerina Integrator with SQS connector with VS Code Plugin please visit the relevant tutorial documentation.

Setting up Ballerina Environment

Go to the WSO2 Ballerina Integrator download page.

Download the WSO2 Ballerina Integrator with Download button and install it.

Check whether Ballerina is correctly installed in your machine by executing the following command.

$ ballerina -v

If the Ballerina integrator is correctly installed in your machine you will get the following output.

Ballerina 1.0.2

Language specification 2019R3

Start developing Ballerina Code

Go to the directory location you want to make the Ballerina code.

$ cd loc

Create a Ballerina file.

touch sqs.bal

Open the file with your preferred editor.

gedit sqs.bal &

Add the following content to start the coding.

import ballerina/log;

import wso2/amazonsqs;

public function main(string... args) {

}

Note how the Ballerina console logging module and Amazon SQS Connector module is imported into the code. The main function is the program entry point as many other languages. Anyway this code snippet will not yet build as these imports are not used in the code.

Defining SQS Configurations and Client

Now let's define the Amazon SQS Configuration object and the SQS Connector client object above the main method.

amazonsqs:Configuration configuration = {
accessKey: "Access Key",
secretKey: "Secret Access Key",
region: "Region",
accountNumber: ""
};

amazonsqs:Client sqsClient = new(configuration);

Replace the Access Key, Secret Access Key and the Region parameters with the credentials obtained from the Amazon SQS account creation stage. Then you can create a SQS queue manually and you can get the parameter from the path of the queue path generated.

Create a Standard Queue in Amazon SQS

There are 2 types of queues defined in Amazon SQS, Standard and FIFO. In this example we are going to create a Amazon Standard Queue. In order to do that we invoke the sqsClient as follows by adding the following code in the main method.

string|error queueURL = sqsClient->createQueue("myNewQueue", {});

if (queueURL is string) {

log:printInfo("Created queue URL: " + queueURL);

} else {

log:printInfo("Error occurred while creating a queue");

}

If the queue creation process had encountered an error, the queueURL would become an error object and a string type otherwise. The string would be the queue URL as specified in the documentation.

If the queue was created the queue URL would be printed something like https://sqs.us-east-2.amazonaws.com/613964236299/myNewQueue. Note the format of the URL.

https://<Region>.amazonaws.com/<Access_Key>/<Queue_Name>

Enqueue a Message to an SQS Queue

Once an SQS queue is created a message can be stored in the queue. Invoking the sendMessage in the connector would send a message into the queue. Note that the received queue context path /<Access_Key>/<Queue_Name> has to be used for accessing the queue.

amazonsqs:OutboundMessage|error response = sqsClient->sendMessage("Sample text message.", "/613964236299/myNewQueue", {});

if (response is amazonsqs:OutboundMessage) {

log:printInfo("Sent message to SQS. MessageID: " + response.messageId);

}

If the above message sending got successful you would get a console output similar to the following.

Sent message to SQS. MessageID: 7e7511a4-68f6-4c94-98e7-2b1e30301a0b

The complete code used would look like following.

import ballerina/log;

import wso2/amazonsqs;

amazonsqs:Configuration configuration = {

accessKey: "AKZAY3QCLPL7DE5YSNC3",

secretKey: "r0RYhP0lputX6hiYvcB5VK7hiY+Id+rUI57b7Qjp",

region: "us-east-2",

accountNumber: "613964236299"

};

amazonsqs:Client sqsClient = new(configuration);