Tutorials : Program Annotation Facility :

Program Annotation Facility

Introduction:

Most Java programmers who have used the Java API reference are familiar with the @deprecated within the comments of a Java method. We know that the tag appears in the comments so that it can help the Javadoc generator to mark this method as deprecated and display the information on the new method set to replace it. There are many comments similar to these (@author, @param etc), which are used to indicate informational parameters. Specific programs with the ability to understand these tags use them to do some specific task. The compiler and the Java runtime usually ignore these comments, as they are included into the comment blocks. However some vendors and programmers have cleverly made use of these comments to include information that could be used by specific custom interpreters to do some routine tasks.

An example is EJBGen by Cedric Beust,(See resources below). EJBGen provides a set of javadoc tags, which can be included into the comments for the method and class etc. These tags are interpreted by the EJBGen compiler which in turn generates appropriate value objects, remote methods, and primary key classes, XML descriptors and so on. So instead of creating all these supporting classes separately EJBGen allows the user to create a single EJB bean class with javadoc attributes specified within it. The tool generates all the supporting classes, relationships and descriptor files required for the EJB. Another example is Xdoclet which has taken this javadoc facility to another level by providing javadoc tags for many common Java tasks like generating bean classes, creating portlets and defining ant tasks. It also has support for many application servers like websphere, weblogic, Sun one Application server and can do tasks ranging from compiling EJBs to deploying applications.

There are many similar efforts like the ones above which use annotations to do routine jobs. The JSR 175 proposes to introduce a Program Annotation facility within the Java programming language, which can help in streamlining these annotation efforts, and also provide a standard way of annotating elements within a Java program.

The annotation facility allows the annotator the facility to define annotation types and then use these annotation types as annotations within a Java program. It also provides control over whether the annotation can be used during compile time or during runtime. Most of the time, third party tools use annotations at compile time to generate supporting classes and artifacts. But in some cases annotations can be used by the Java runtime to do some operations at runtime. The facility allows the annotator to reduce the overhead of carrying the compile time annotations with the class file to the JVM by specifying them to be ‘compile time’ annotations.

How to use Annotations:

To create an annotation we need to define an annotation type first. Annotation types are defined like interfaces with an "@" sign before the interface definition. Annotation types and Annotation are described below in detail.

A sample of how to define "Annotation Types" is given below.

	public @interface SampleAnnotation{
      	String someValue;
} 
public @interface NormalAnnotation{
	String value1;
	int value2;
}

How an annotation can be used is shown below.

@SampleAnnotation (someValue ="Actual Value used in the program”)
public void annotationUsingMethod(){
	…
} 

Annotation Type

The annotation type declaration looks similar to an interface declaration and they have similar characteristics like interfaces. They have the same scope and accessibility as Java interfaces and can be used wherever interfaces can be used.

Some of the characteristics of annotation types are listed below.