Java Custom Annotations
Summary: By the end of this tutorial "Java Custom Annotations", you will come to know to create your own annotations and use in the code.
Creating Custom defined Annotations
After learning simple built-in annotations and meta annotations, let us learn how to create our own annotations. Creating our own annotation is simply almost like creating our own general Java interface. Write in a separate file with extension .java and compile as usual.
Let us write a simplest annotation possible to understand.
Writing your first Java Custom Annotation.
@interface StudentAnnotation
{
int age();
String stdName();
boolean feesPaid;
String balanceFees();
String[] busRoutesAllowed();
}
It is exactly like writing a Java interface but with a prefix of @ symbol for interface keyword. The @interface is followed by the name of the annotation (known as annotation type).
Rules of creating an annotation
1. @interface should come before the actual annotation type (name of the annotation).
2. Method declarations should not have parameters
3. Methods should not throw any exceptions (with throws keyword)
4. The return type of methods should any be of the following:
a) Any primitive data type
b) Class
c) String
d) enum
e) An array of any type of the above
The above interface can be given default values also as follows.
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Inheirited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface StudentAnnotation
{
int age();
String stdName();
boolean feesPaid() default=true;
String balanceFees() default="No balance";
String[] busRoutesAllowed();
}
The @Retention and @Target are known as Meta annotations because they annotate the annotation StudentAnnotation. The above meta annotations say that the annotation StudentAnnotation can applied to methods only and not to any other elements (given by @Target) and the annotation should be retained up to runtime (given by @Retention), until the class file is loaded into the Java Virtual Machine and can be inherited by the subclasses (given by @Inherited). To use this annotation, a tool is required. The tool retrieves the student name by calling method stdName.
If the annotation also includes variables, then how to write the @Target annotation? Following is the way.
@Target(ElementType.FIELD, ElementType.METHOD)
@interface StudentAnnotation
@interface tells to the annotation tool that StudentAnnotation is an annotation. @interface is very different from our general interface. The total word @interface defines an annotation.
String balanceFees() default="No balance";
balanceFees is the annotation property name (here, property is a method) and String is known as property type. That is, annotation type is followed by property name. It is similar to writing an abstract method in a general interface. Writing default value is optional. In the above statement, if the client program does not mention the String value, by default "No balance" is given.
Java Custom Annotations you write cannot have extend clause in its declaration. Anyhow, it automatically extends java.lang.annotation.Annotation interface.
How to use the above annotation in our class? See.
@StudentAnnotation
public class College
{
// you are required to implement all the StuddentAnnotation methods
}
We need to write the list of interface methods in the implemented class because the methods are implicitly inherited due to simple @Inherited tag.
If you go by old style, the College class must be written as follows:
public class College implements StudentAnnotation
{
// override each abstract method
}
To rewrite the previous code:
@StudentAnnotation (age=23, stdName="S N Rao", feesPaid=false, balanceFees="balance exists", busRoutesAllowed={"Dilsukh Nagar", "Narayan Guda"});
public class College
{
// you are required to implement all the StuddentAnnotation methods
}
It can also be done as follows to take default values which are not mentioned. Note, default values are set for only methods feesPaid and balanceFees.
@StudentAnnotation (age=23, stdName="S N Rao", busRoutesAllowed={"Dilsukh Nagar", "Narayan Guda"});
public class College
{
// you are required to implement all the StuddentAnnotation methods
}
Note: If not mentioned, the tool takes default values.
Now, let us go for some more theory on Java Custom Annotations.
There are three types in custom-defined annotations.
1. Marker annotation
2. Single Element annotation
3. Multiple Element annotation
The previous @StudentAnnotation is a multiple Element annotation. Let us go for other types.
Marker Annotation
A marker annotation is like a marker interface. Like marker interface, the marker annotation does not have any elements or methods.
public @interface EmployeeAnnotation { }
How to use marker interface?
public class Demo
{
@EmployeeAnnotation public void display() { }
}
The marker annotation @EmployeeAnnotation is used as an access modifier before the method declaration.
Single Element Annotation
As the name indicates there will be a single method in the annotation. In single element annotation, the single method should be value(). The variation comes in the value assignment. As there is a single member, we need not specify the name of the member while giving the value. This works only when member name is value().
public @interface HouseWife
{
String value();
}
How to use?
// write some Java class
@HouseWife ("Sumathi")
Public void getName() { }
// continue the class
You can write
@HouseWife ("Sumathi")
because of single member value or property name is not required.
Annotation processor tool or frameworks uses Java Reflection API to interpret the annotations.
Usage of Annotations or where annotations stand today?
When you use any framework like Hibernate or Spring, you will come to know the strength of annotations; else they look non-sense code. The result is spending time on code is very less and thereby the developer can devote more time to business logic. Now-a-days, annotations are used for Automatic generation of code for testing purpose, writing to log files and transaction managements etc.
Before the introduction of annotations, the metadata is given in separate external files (known as configuration files) which are read and implemented by servers like Tomcat or Weblogic etc. Annotations avoid external files as the annotations are included in the source code itself. Annotations are gaining popularity due to their robustness, simplicity and easiness. When understood properly and included correctly, the annotations are of immense use. Annotations are used in a big way in EJB 3.0. Repetitive code in EJB is implicitly generated by annotations.
As Graham Hamilton, the J2SE 5 Lead Architect at Sun Microsystems, says, annotations are the strength of JDK 1.5 release. Annotations are tags put into the source code and processed by separate processors built into many Java tools, now-a-days. If you write your own annotations, then you are also required to build your own processing tool. If you are using third party annotations, do not forget to load the processing tool developed and given by the third party.
Annotation does not have anything to do in the source code. The annotations are processed by development tools as per the functionality or meaning given to the annotation. Annotations can be used in collaboration with XML documents.
I think I have tried my maximum extent to explain the annotation concept, style of creation and using them in this tutorial "Java Custom Annotations". Pass your comments to improve the quality of this tutorial "Java Custom Annotations".
