Java 1.5 comes packaged with seven pre-built annotations. I will describe these built-in annotations in this section, borrowing much of the wording directly from the Java 5 documentation
public @interface Override
This annotation is used to indicate that a method declaration is intended to override a method declaration in a superclass. If a method is annotated with this annotation type but does not override a superclass method, compilers are required to generate an error message.
This annotation is useful in avoiding the situation where you think you are overriding a method, but you misspell the method name in the child class. The code in the method you are trying to override in the parent class will be used because the name is misspelled in the child class. This is usually a difficult bug to track down because no compiler or runtime error is thrown. But marking a method with the Override annotation would help you realize this type of problem at compile time rather than through arduous debugging.
public @interface Deprecated
A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous or because a better alternative exists. Using this annotation, compilers warn when a deprecated program element is used or overridden in non-deprecated code.
public @interface SuppressWarnings
This annotation indicates that the named compiler warnings should be suppressed in the annotated element (and in all program elements contained in the annotated element). Note that the set of warnings suppressed in a given element is a superset of the warnings suppressed in all containing elements. For example, if you annotate a class to suppress one warning and annotate a method to suppress another, both warnings will be suppressed in the method.
public @interface Documented
Annotations with a type declaration are to be documented by javadoc and similar tools by default. It should be used to annotate the declarations of types whose annotations affect the use of annotated elements by their clients. If a type declaration is annotated with @Documented, its annotations become part of the public API of the annotated elements.
public @interface Inherited
This indicates that an annotation type is automatically inherited. If an inherited meta-annotation is present on an annotation type declaration, and the user queries the annotation type on a class declaration, and the class declaration has no annotation for this type, then the class's superclass will automatically be queried for the annotation type. This process will be repeated until an annotation for this type is found or the top of the class hierarchy (Object) is reached. If no superclass has an annotation for this type, then the query will indicate that the class in question has no such annotation.
Note that this meta-annotation type has no effect if the annotated type is used for anything other than a class. Also, this meta-annotation causes annotations to be inherited only from superclasses; annotations on implemented interfaces have no effect.
public @interface Retention
Retention takes a single value of the enumerated type RetentionPolicy, which informs the compiler of its policy for retaining annotations in memory. There are three RetentionPolicy enumerated values:
- SOURCEAnnotations are to be discarded by the compiler.
- CLASSAnnotations are to be recorded in the class file by the compiler but need not be retained by the VM at runtime. This is the default behavior.
- RUNTIMEAnnotations are to be recorded in the class file by the compiler and retained by the VM at runtime, so they may be read reflectively.
If no Retention annotation is present on an annotation type declaration, the retention policy defaults to RetentionPolicy.CLASS. By default, the annotation data is not available in the JVM in order to reduce overhead.
public @interface Target
@Target indicates the kinds of program element to which an annotation type is applicable. It takes a single enumerated parameter of type ElementType
. The enumerated values are as follows:
- TYPE (class, interface or enum declaration)
- FIELD (includes enum constants)
If a @Target meta-annotation is not present on an annotation type declaration, the declared type may be used on any program element. If such a meta-annotation is present, the compiler will enforce the specified usage restriction.