Tutorials : Program Annotation Facility :

Annotations:

An annotation is a modifier that can be used on any declaration like a class, interface, method, variable, parameter etc. An annotation contains zero or more member value pairs depending on which annotation type is used. Annotation should define member- value pairs for all members defined in the annotation type. The only exception to this rule is members who have default values already assigned in the annotation type definition. Annotations can be used on Enum constants.

Annotations can also be used on packages. When they are declared in packages they need to be in a file called package-info.java. Most people who have worked with generating javadocs from classes would be familiar with package.html file. The package.html file contains all the package level information that is required for generating documentation. The package- info.java file replaces this package.html file. Document generators should ignore package.html file if they find the package-info.java file. The package-info.java file will contain package level annotations and documentations, which can be used by the generator to generate documentation.

There are three kinds of annotations: normal annotation, marker annotation, and single member annotation. A normal annotation is used to annotate a program element using a regular annotation, an example of an annotation using the annotation type (Normal Annotation) defined above would be:

	@NormalAnnotation(	value1 = “”, value2=0)
      public void someMethod(){
      …
      }

A marker annotation uses a marker annotation type. A single member annotation is a short hand for a regular annotation and uses a single member annotation type.

Meta-Annotation Types

The program annotation specification provides meta-annotation types, which are used to annotate annotation types. The java.lang.Annotation class provides the facility for doing this.

The first meta-annotation type is the target, which is used to specify the program element to which an annotation type can be applied. The possible values are defined in the ElementType enumeration: TYPE , FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, PACKAGE etc. The TYPE ElementType defines a class, interface or an enum declaration; the FIELD can include any field declarations and enum constants. When an annotation type is marked with the target Meta tag say TYPE, then the annotation can only be used in the scope of a class, interface or a enum declaration.

Usage: @Target(FIELD) 

The second type is the Documented meta-annotation tag. This specifies whether the method needs to be documented by javadoc. Specifying the @Documented tag within a method tells the javadoc compiler to generate Javadoc documentation for this method.

Usage : @Documented

The third type of meta-annotation tag is Retention. Retention decides how long an annotation has to be retained. It is used in conjunction with the RetentionPolicy enumerated type. The possible values for the enumeration are

Usage : @Retention(SOURCE)

@Retention(SOURCE) 
@Target(METHOD) 
@Documented 
public @metaExampleMethod{
 …
}