Java annotation


In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code. Classes, methods, variables, parameters and Java packages may be annotated. Like Javadoc tags, Java annotations can be read from source files. Unlike Javadoc tags, Java annotations can also be embedded in and read from Java class files generated by the Java compiler. This allows annotations to be retained by the Java virtual machine at run-time and read via reflection. It is possible to create meta-annotations out of the existing ones in Java.

History

The Java platform has various ad-hoc annotation mechanisms—for example, the transient modifier, or the @deprecated javadoc tag. The Java Specification Request JSR-175 introduced the general-purpose annotation facility to the Java Community Process in 2002; it gained approval in September 2004.
Annotations became available in the language itself beginning with version 1.5 of the Java Development Kit. The apt tool provided a provisional interface for compile-time annotation processing in JDK version 1.5; JSR-269 formalized this, and it became integrated into the javac compiler in version 1.6.

Built-in annotations

Java defines a set of annotations that are built into the language. Of the seven standard annotations, three are part of java.lang, and the remaining four are imported from java.lang.annotation.
Annotations applied to Java code:
Annotations applied to other annotations :
Since Java 7, three additional annotations have been added to the language.

Built-in annotations

This example demonstrates the use of the @Override annotation. It instructs the compiler to check parent classes for matching methods. In this case, an error is generated because the gettype method of class Cat doesn't in fact override getType of class Animal like is desired, because of the mismatching case. If the @Override annotation was absent, a new method of name gettype would be created in class Cat.

public class Animal
public class Cat extends Animal

Custom annotations

Annotation type declarations are similar to normal interface declarations. An at-sign precedes the interface keyword. Each method declaration defines an element of the annotation type. Method declarations must not have any parameters or a throws clause. Return types are restricted to primitives, String, Class, enums, annotations, and arrays of the preceding types. Methods can have default values.

// @Twizzle is an annotation to method toggle.
@Twizzle
public void toggle
// Declares the annotation Twizzle.
public @interface Twizzle

Annotations may include an optional list of key-value pairs:

// Same as: @Edible
@Edible
Item item = new Carrot;
public @interface Edible
@Author
Book book = new Book;
public @interface Author

Annotations themselves may be annotated to indicate where and when they can be used:

@Retention // Make this annotation accessible at runtime via reflection.
@Target // This annotation can only be applied to class methods.
public @interface Tweezable

The compiler reserves a set of special annotations for syntactic purposes.
Annotations are often used by frameworks as a way of conveniently applying behaviours to user-defined classes and methods that must otherwise be declared in an external source or programmatically. The following, for example, is an annotated JPA data class:

@Entity // Declares this an entity bean
@Table // Maps the bean to SQL table "people"
public class Person implements Serializable

The annotations are not method calls and will not, by themselves, do anything. Rather, the class object is passed to the JPA implementation at run-time, which then extracts the annotations to generate an object-relational mapping.
A complete example is given below:

package com.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Documented
@Retention
@Target
@Inherited
public @interface Unfinished


package com.annotation;
public @interface UnderConstruction


package com.validators;
import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;
import com.annotation.UnderConstruction;
import com.annotation.Unfinished;
import com.annotation.Unfinished.Priority;
import com.util.Util;
@UnderConstruction
public class DateValidator implements Validator

Processing

When Java source code is compiled, annotations can be processed by compiler plug-ins called annotation processors. Processors can produce informational messages or create additional Java source files or resources, which in turn may be compiled and processed. However, annotation processors cannot modify the annotated code itself. The Java compiler conditionally stores annotation metadata in the class files, if the annotation has a RetentionPolicy of CLASS or RUNTIME. Later, the JVM or other programs can look for the metadata to determine how to interact with the program elements or change their behavior.
In addition to processing an annotation using an annotation processor, a Java programmer can write their own code that uses reflections to process the annotation. Java SE 5 supports a new interface that is defined in the java.lang.reflect package. This package contains the interface called AnnotatedElement that is implemented by the Java reflection classes including Class, Constructor, Field, Method, and Package. The implementations of this interface are used to represent an annotated element of the program currently running in the Java Virtual Machine. This interface allows annotations to be read reflectively.
The AnnotatedElement interface provides access to annotations having RUNTIME retention. This access is provided by the getAnnotation, getAnnotations, and isAnnotationPresent methods. Because annotation types are compiled and stored in byte code files just like classes, the annotations returned by these methods can be queried just like any regular Java object. A complete example of processing an annotation is provided below:

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
// This is the annotation to be processed
// Default for Target is all Java Elements
// Change retention policy to RUNTIME
@Retention
public @interface TypeHeader


// This is the annotation being applied to a class
@TypeHeader
public class SetCustomAnnotation


// This is the example code that processes the annotation
import java.lang.annotation.Annotation;
import java.lang.reflect.AnnotatedElement;
public class UseCustomAnnotation

Usage in the wild

Researchers have studied the usage of Java annotations over 1,094 notable open-source Java projects hosted on GitHub. They found that annotations are actively maintained, with many annotations being added, but also changed or removed because of bugs in the annotation type or values. Overall, this study finds that there exists a small but significant relationship between annotation usage and code error-proneness: Java code with annotations
tends to be less error-prone.