An annotation is a ballerina code snippet that can be attached to some ballerina code, and will hold some metadeta related to that attached code. Annotations are not executable, but can be used to alter the behavior of some executable code.

Sample:

@http:POST{}
@http:BasePath("/pizzaService")
service MyService {
   ...
   ...
}

Where Can I attach an Annotation?

Annotations can be attached to any one of the following:

• Services
• Resources
• Functions
• Connectors
• Actions (of Connectors)
• TypeMappers
• Structs
• Constants
• Annotations

What are the inbuilt ones?

Currently (in ballerina v0.85), there are inbuilt annotations in four packages, each are for HTTP, JMS, WebSockets, and Documentations. You can find the definitions of each annotations in [1], [2], [3], and [4] respectively.

Can I define my own Annotation?

You can define your own annotation and apply it anywhere you want. A definition of an annotation takes the following form:

package foo.bar;
annotation MyAnnotation attach service, resource, function {
    string status;
    int code;
}

Here the starting 'annotation' is a keyword that describes this is an annotation definition, followed by the name of your annotation. Then you can specify to where this annotation can be applied, after the keyword 'attach'. In the above sample, my 'MyAnnotation' is allowed to be attached to any service, resource, or a function (or all of them).

You can apply the above annotation in a function like below:

@bar:MyAnnotation{status:"working", code:1}
function myFunction(string str) {
    ...
}

Note that, if the function is in the same package as the annotation, then you need to ignore the preceding package name in the annotation attachment.
e.g.:

@MyAnnotation{status:"working", code:1}
function myFunction(string str) {
    ...
}

What can be the types of attributes?

Type of an attribute of an annotation can be on of the following:

• A value type (string, int, float, boolean).
• An Annotation.
• Array of any of above.

Default Values for Annotation Attributes?

Indeed. Attributes of an annotation can have default values, But only for attributes of value types (string, int, float, boolean).
e.g:

annotation MyAnnotation attach service, resource, function {
    string status = "failed";
    int code = 0;
}

This means, if you have an attribute of an array type (eg: int[] a), or an attribute of another annotation (eg MyAnnotation a;), then those attributes cannot have default values.

Annotate an Annotation by itself?

You can also annotate an annotation using the same annotation itself. For example, say we write an annotations called 'Desciption' to add an dexscription to any of the ballerina construct we write. And suppose we need to add a description to that 'Description' annotation. We can do it as follows:

@Description{value:"This is an annotation that can be used to describe a construct"}
annotation Description attach service, annotation, function {
    string value;
}

References

[1] https://github.com/ballerinalang/ballerina/blob/master/modules/ballerina-native/src/main/ballerina/ballerina/net/http/annotation.bal
[2] https://github.com/ballerinalang/ballerina/blob/master/modules/ballerina-native/src/main/ballerina/ballerina/net/jms/annotations.bal
[3] https://github.com/ballerinalang/ballerina/blob/master/modules/ballerina-native/src/main/ballerina/ballerina/net/ws/annotation.bal
[4] https://github.com/ballerinalang/ballerina/blob/master/modules/ballerina-native/src/main/ballerina/ballerina/doc/annotation.bal

Suppose you are writing an integration scenario (in Ballerina or any technology), and you need to test the end-to-end scenario you just wrote. Way to achieve this is to mock a back-end service, and test your integration flow, without having to hassle with the actual back-end servers. With Ballerina, mocking a service has made easier than ever. All it takes is one minute to mock your service and make it up and running, with the flexibility of Ballerina. Lets look at how we can achieve this.

Mock the Service:

Lets consider a scenario where we need to test sending a payload to a back-end server, and receiving a different payload form it. Lets also assume following are the two pyaloads, we are sending to the back-end, and receiving from it, respectively.

Sending Payload:

<Order>
    <orderId>order100</orderId>
    <items>
        <item>
            <itemId>101</itemId>
            <price>2</price>
            <quantity>1</quantity>
        </item>
        <item>
            <itemId>106</itemId>
            <price>7</price>
            <quantity>2</quantity>
        </item>
    </items>
</Order>

Receiving Payload:

{
      "orderId":"order100",
      "status":"accpeted"
}

Lets create the mocked service to accept the above "sending payload" and send back the "receiving payload" as the response.

import ballerina.lang.xmls;
import ballerina.lang.messages;
import ballerina.lang.system;
import ballerina.net.http;

@http:BasePath{value:"/pizzaService"}
service PizzaService {

    @http:POST{}
    @http:BasePath{value:"/placeOrder"}
    resource placeOrder(message m) {

        // Get the order Id
        xml request = messages:getXmlPayload(m);
        string orderId = xmls:getString(request, "/Order/orderId/text()");

        // generate the json payload
        json responseJson = `{"orderId":${orderId}, "status":"accpeted"}`;

        // generate the response   
        message response = {};
        messages:setJsonPayload(response, responseJson);
        reply response;
    }
}

Don't we need to set the content type?

No, we don't need to. Ballerina will automatically set the content type to application/json, when we set a json as the payload!
Lets save this service in pizzeService.bal file.

Run the Mocked Service

To run our service, execute the following:

<ballerina_home>/bin/ballerina run service <path/to/bal/file>pizzeService.bal

Now the mocked service is up, and you can test your integration scenario using this service as the back-end.

You can download ballerina runtime and tooling from http://ballerinalang.org/downloads/. Ballerina runtime contains the runtime environment (bre) needed to run ballerina main programs and ballerina services. Ballerina tooling distribution contains the runtime environement (bre), The Composer (visual editor), Docerina (for API document generation) and Testerina (Test framework for ballerina).

To get the things started, lets write a very simple ballerina main program which will print some text to the console. It will look like follow:

import ballerina.lang.system;

function main(string[] args) {
    system:println("My first ballerina main program!");
}

<ballerina_home>/bin/ballerina run main <path/to/bal/file>myFirstMainProg.bal

My first ballerina main program!

import ballerina.lang.system;

import ballerina.net.http;

@http:BasePath{value:"/myService"}
service echoService {

    @http:GET{}
    @http:BasePath{value:"/echo"}

    resource echoResource (message m) {
        system:println("My first ballerina service!");
        reply m;
    }
}

<ballerina_home>/bin/ballerina run service <path/to/bal/file>myFirstService.bal

ballerina: deploying service(s) in 'passthrough.bal'
ballerina: started server connector http-9090

And unlike in the main program, server will not exit, and will be keep listening to the port 9090. Now to invoke our service, lets run the following curl command, which will send a get request to the service. Note that, in our service, "myService" will be the base path followed by the resource path "echo".

curl http://localhost:9090/myService/echo

My first ballerina service!