Core Java Volume II—Using annotations

Annotations are tags that you insert into your source code so that some tool can process them. The tools can operate on source level or they can process class files into which the compiler has placed annotations.

Uses for annotations:

• Automatic generation of auxiliary files such as deployment descriptors or bean information classes
• Automatic generation of code for testing, logging, transaction semantics, and so on

Junit 4 testing tool calls all methods that are labeled @test when testing a class.

Annotations can be defined to have elements which can be processed by the tools that read the annotations.

An annotation can be put anywhere that you could put a modifier.

You can annotate packages, parameter variables, type parameters, and type uses.

Each annotation must be defined by an annotation interface. The methods of the interface correspond to the elements of the annotation.

The @interface declaration creates an actual Java interface.

Annotation Syntax:

An annotation is defined by a annotation interface:

modifiers @interface AnnotationName{
    elementDeclaration1;
    elementDeclaration2;
    …
}

Each element declaration has the form

type elementName();

or

type elementName() default value;

You cannot extend annotation interfaces.

The type of an annotation element is one of the following:

• A primitive type
• String
• Class
• An enum type
• An annotation type
• An array of the preceding types(an array of arrays is not a legal element type)

Each element has the format

@AnnotationName(elementName1 = value1, elementName2 = value2, …) // the order of elements does not matter.

The default value of the declaration is used if an element value is not specified.

If no elements are specified, you don't need to use parentheses.

@AnnotationName

The single value annotation

If an element has the special name value and no other element is specified, you can omit the element name and the = symbol.

An item can have multiple annotations, if an annotation is repeatable, you can repeat same annotation multiple times.

An annotation element can never be set to null. You can find other defaults such as "" or Void.class.

2 main use of annotation: declarations and type uses.

Declaration annotations can appear at the declaration of:

• Packages
• Classes
• Interfaces
• Methods
• Constructors
• Instances fields (including enum constants)
• Local variables
• Parameter variables
• Type parameters

For classes and interfaces, put the annotations before the class or interface keyword; for variables, put them before the type; for type parameters <@AnnotationName V>; for packages, the package-info.java contains only the package statement preceded by annotations.

Type use annotations can appear in the following places:

• With generic type arguments
• In any position of an array
• With superclasses and implemented interfaces:
• With constructor invocations
• With instanceof checks and casts
• With exception specifications
• With method and constructor references: eg. @Annotation Message::getText

Custom:

• Put type use annotations after other modifiers;
• Put declaration annotations before other modifiers.

An annotation placed on the constructor describes a property of the constructed object.

Annotation	Purpose
@Generated	Code generator tools
@PostConstruct @PreDestroy	In environments that control the life-circle of objects—methods tagged with these annotations should be invoked immediately after an object has been constructed or before is being removed.
@Resource	Resource injection
@Target({ElementType.X, ElementType.Y, …})	Apply to an annotation, retricting the items to which the annotation applies.
@Rentention	Specifies how long an annotation is retained (SOURCE, CLASS, RUNTIME).
@Documented	The documentation of each annotated method/… contains the annotation.
@Inherited	Only applies to classes, all of the subclasses automatically have the same annotation.

Java SE 8 -> Legal to apply the same annotation type multiple times to an item. For backward compatibility, the implementor of a repeatable annotation needs to provide a container annotation that holds the repeated annotations in an array.

Whenever the user supplies 2 or more @TestCase annotations, they are automatically wrapped into a @TestCases annotation.