Ballerina 101

In this tutorial you will learn the basic concepts of Ballerina and why we call it Flexible, Powerful and Beautiful. You will also learn to run your ballerina programs in two modes: server and standalone modes with simple examples.

Introduction

Ballerina is a programming language designed from the ground up specifically for integration which allows you to draw code to life. It allows you to connect apps and services to handle all kinds of integration scenarios. Why do we call it Flexible, Powerful and Beautiful?

You can build your integrations by drawing sequence diagrams, or write your code in swagger or in ballerina. You can add plugins and write ballerina code in IntelliJ IDEA[2], Vim[3], Atom[4], Sublime Text 3[5] and more. Therefore it is FLEXIBLE.

Ballerina can handle everything from a simple Hello World program to complex service chaining and content-based routing scenarios. It comes with native support for REST, Swagger, JSON, and XML, and it includes connectors for popular services like Twitter and Facebook. It has an incredibly fast lightweight runtime which can be deployed in a production environment without any development tools. Therefore it is POWERFUL.

The integration code is written for you as you create the diagram in Ballerina Composer.

Cool! isn't it? All you have to do is drag and drop elements needed for your use case onto a canvas who will easily create your integration scenario for you. You can switch between Source view and Design view anytime. Therefore it is BEAUTIFUL.

Key Concepts

Each Ballerina program represents a discrete unit of functionality that performs an integration task. The complexity of the ballerina program is upon your discretion.

You can create your ballerina program in two ways.
1. Server mode: as a service that runs in the Ballerina server and awaits requests over HTTP.
2. Standalone mode: as an executable program that executes a main() function and then exits.

Following are the available constructs you can use [1].

1. Service: When defining a Ballerina program as a service instead of an executable program, the service construct acts as the top-level container that holds all the integration logic and can interact with the rest of the world. Its base path is the context part of the URL that you use when sending requests to the service.

2. Resource: A resource is a single request handler within a service. When you create a service in Ballerina using the visual editor, a default resource is automatically created as well. The resource contains the integration logic.

3. Function: A function is a single operation. Ballerina includes a set of native functions you can call and you can define additional functions within your Ballerina programs.
 The main() function contains the core integration logic when creating an executable program instead of a service. When you run the program, the main() function executes, and then the program terminates. You can define additional functions, connectors, etc. inside the program and call them from main(). See here for a complex example.

4. Worker: A worker is a thread that executes a function.

5. Connector: A connector represents a participant in the integration and is used to interact with an external system or a service you've defined in Ballerina. Ballerina includes a set of standard connectors that allow you to connect to Twitter, Facebook, and more, and you can define additional connectors within your Ballerina programs.

6. Action: An action is an operation you can execute against a connector. It represents a single interaction with a participant of the integration.

See language reference for more information.

Quick Start

1. Download complete ballerina tools package from http://ballerinalang.org/downloads/
2. Unzip it on your computer and lets call it <ballerina_home>. 
e.g.: /WSO2/ballerina/ballerina-tools-<version>
3. Add <ballerina_home>/bin directory to your $PATH environment variable so that you can run ballerina commands from anywhere.
e.g.: on Mac OS X

export BALLERINA_HOME=/WSO2/ballerina/ballerina-tools-0.8.1 export PATH=$BALLERINA_HOME/bin:$PATH

Run HelloWorld - Standalone Mode

Now we are going to run HelloWorld classical example using a main() function, i.e. in standalone mode as follows.

1. Create /WSO2/ballerina/tutorial/helloWorld directory.
2. In this directory, create the file helloWorld.bal with following contents.

import ballerina.lang.system; function main (string[] args) {   system:println("Hello, World!"); }

This is how the famous hello world sample looks like in ballerina programming language!

3. Issue the following command to run the main() function in helloWorld.bal file.
$ ballerina run main helloworld.bal

You can observe the following output in command line.

> Hello, World!

After the HelloWorld program is executed, Ballerina will be stopped. This is useful when you want to execute a program once and then stop as soon as it has finished its job. It runs the main() function of the program you specify and then exits. 

Run HelloWorld - Server Mode

Here Ballerina will deploy one or more services in the ballerina program that wait for requests.

1. Create the file helloWorldService.bal with following contents.

import ballerina.lang.messages; @http:BasePath ("/hello") service helloWorld {     @http:GET     resource sayHello (message m) {         message response = {};         messages:setStringPayload(response, "Hello, World!");         reply response;     } }

3. Issue the following command to deploy the helloWorld service in helloWorldService.bal file.

$ ballerina run service helloWorldService.bal

You can observe the following output in command line that the service is waiting for requests.

> ballerina: deploying service(s) in 'helloWorldService.bal'

> ballerina: started server connector http-9090

The Ballerina server is available at localhost:9090, and helloWorld service is available at context hello. 

4. Open another command line window and use the curl client to call helloWorld service as follows.

$ curl -v http://localhost:9090/hello

The service receives the request and executes its logic, printing "Hello, World!" on the command line as follows. 

*   Trying 127.0.0.1...

* Connected to localhost (127.0.0.1) port 9090 (#0)

> GET /hello HTTP/1.1

> Host: localhost:9090

> User-Agent: curl/7.49.1

> Accept: */*

> 

< HTTP/1.1 200 OK

< Content-Type: text/plain

< Content-Length: 13

< 

* Connection #0 to host localhost left intact

Hello, World!

Notice that the Ballerina server is still running in the background, waiting for more requests to serve. 

5. Stop the Ballerina server by pressing Ctrl-C (Command-C). 

Reference:
[1] http://ballerinalang.org/
[2] https://github.com/ballerinalang/plugin-intellij/releases
[3] https://github.com/ballerinalang/plugin-vim/releases
[4] https://github.com/ballerinalang/plugin-atom/releases
[5] https://github.com/ballerinalang/plugin-sublimetext3/releases