Annotations in Ballerina

What are Annotations?


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

However, this differs for different types of annotations. For example, http:BasePath{} can only be attached to a Service, here as http:POST{} can only be attached to a resource. This is specified in the definition of each annotation.


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?

Absolutely! 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;
}

Will the above work? Absolutely!



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

Share:

0 comments