In this tutorial, I’m trying to give a simple introduction to Java Annotations with less words and simple examples. In 10 minutes, you’ll learn what is Annotations, how to use Annotations, and how to create custom Annotations.
Annotations, a form of metadata, like tags, alternative to configuration files, provide extra information to our code.
Built-in Annotations
It tells the program that method `getName` of class `Guinness` overrides the `getName` method declared in its superclass.
Annotation follows the at sign character (@). This is the most simplest annotation. The other two similar build-in annotations are @Deprecated (tells the method is obsolete) and @SuppressWarnings (tells the compiler to suppress warnings).
Before we dive deep, we need to understand two concepts: RetentionPolicy and ElementType.
RetentionPolicy tells when Annotations can be used. For example, @Override is used in code only.
Retention Policies
- RetentionPolicy.SOURCE — The marked annotation is retained only in the source level and is ignored by the compiler. Can be used by the compiler to detect errors or suppress warnings.
- RetentionPolicy.CLASS — The marked annotation is retained by the compiler at compile time, but is ignored by the Java Virtual Machine (JVM). Software tools can process annotation information to generate code, XML files, and so forth.
- RetentionPolicy.RUNTIME — The marked annotation is retained by the JVM so it can be used by the runtime environment. Some annotations are available to be examined at runtime.
ElementType tells where Annotations can be used. For example, @Override is used at method only.
Element Types
- ElementType.ANNOTATION_TYPE can be applied to an annotation type.
- ElementType.CONSTRUCTOR can be applied to a constructor.
- ElementType.FIELD can be applied to a field or property.
- ElementType.LOCAL_VARIABLE can be applied to a local variable.
- ElementType.METHOD can be applied to a method-level annotation.
- ElementType.PACKAGE can be applied to a package declaration.
- ElementType.PARAMETER can be applied to the parameters of a method.
- ElementType.TYPE can be applied to any element of a class
We can see the definition of @Override annotation from Java source code
Custom Annotation
From the definition of @Override annotation, we can see annotation is `interface` with a preceding at sign character: `public @interface Override`. 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.
Example 1 RetentionPolicy.SOURCE
Example 2 RetentionPolicy.RUNTIME
Annotation Definition
We can use the annotation via Reflection
More complicated example
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). Like Spring Framework Annotations: Link.
You now know the basic of annotations. Here are some bonus information if you want to learn more.
Bonus Information
Meta annotations
Annotations that apply to annotations are called meta annotations. Besides Retention and Target. Other meta annotations are:
- @Documented: indicates that whenever the specified annotation is used those elements should be documented using the Javadoc tool. (By default, annotations are not included in Javadoc.)
- @Inherited: indicates that the annotation type can be inherited from the super class. (This is not true by default.) When the user queries the annotation type and the class has no annotation for this type, the class’ superclass is queried for the annotation type. This annotation applies only to class declarations.
- @Repeatable: introduced in Java SE 8, indicates that the marked annotation can be applied more than once to the same declaration or type use.
Multiple annotations
Type Annotations
As of the Java SE 8 release, annotations can also be applied to the use of types. Here are some examples:
