In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code, like an attribute. 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.
The Java platform has various ad-hoc annotation mechanismsâÂÂfor example, the <code>transient</code> modifier, or the <code>@Deprecated</code> javadoc tag. The Java Specification Request JSR-175 introduced the general-purpose annotation (also known as metadata) 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 (JDK). The <code>apt</code> 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.
In C++26, C++ added annotations for reflection that are similar to Java annotations.
Java defines a set of annotations that are built into the language. Of the seven standard annotations, three are part of , and the remaining four are imported from <code>java.lang.annotation</code>.
In Jakarta EE (formerly Java Platform, Enterprise Edition), the following annotations also exist in <code>jakarta.annotation</code> (formerly <code>javax.annotation</code>):
There was previously an annotation, <code>@ManagedBean</code>, located in <code>jakarta.annotation</code>, which was historically used to declare a Managed Bean which are container managed objects that support a small set of basic services such as resource injection, lifecycle callbacks and interceptors. However, it has been removed.
This example demonstrates the use of the <code>@Override</code> annotation. It instructs the compiler to check parent classes for matching methods. In this case, an error is generated because the <code>gettype()</code> method of class Cat doesn't in fact override <code>getType()</code> of class Animal like is desired, because of the mismatching case. If the <code>@Override</code> annotation were absent, a new method of name <code>gettype()</code> would be created in class Cat.
Annotation type declarations are similar to normal interface declarations. An at-sign (@) precedes the keyword "interface".
Annotations may include a set of key-value pairs, which are modeled as methods of the annotation type. 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.
Annotations themselves may be annotated to indicate where and when they can be used:
The compiler reserves a set of special annotations (including <code>@Deprecated</code>, <code>@Override</code> and <code>@SuppressWarnings</code>) 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 (such as an XML configuration file) or programmatically (with API calls). The following, for example, is an annotated JPA data class:
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:
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. (Code modifications may be implemented using methods beyond the Java Language Specification.) The Java compiler conditionally stores annotation metadata in the class files, if the annotation has a <code>RetentionPolicy</code> of <code>CLASS</code> or <code>RUNTIME</code>. 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 reflection to process the annotation. Java SE 5 supports a new interface that is defined in the <code>java.lang.reflect</code> package. This package contains the interface called <code>AnnotatedElement</code> that is implemented by the Java reflection classes including <code>Class</code>, <code>Constructor</code>, <code>Field</code>, <code>Method</code>, and <code>Package</code>. 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 <code>AnnotatedElement</code> interface provides access to annotations having <code>RUNTIME</code> retention. This access is provided by the <code>getAnnotation</code>, <code>getAnnotations</code>, and <code>isAnnotationPresent</code> 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:
Libraries such as JUnit use annotation processing to generate unit tests.