.JAVA File Format – Annotations

Declaring an annotation interface

AnnotationInterfaceDeclaration:
    {InterfaceModifier} @ interface TypeIdentifier AnnotationInterfaceBody

AnnotationInterfaceElementDeclaration:
    {AnnotationInterfaceElementModifier} UnannType Identifier ( ) [Dims] [default ElementValue] ;

import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Review {
    String reviewer();                      // required element
    int priority() default 3;               // optional, with a default
    String[] tags() default {};
    Status status() default Status.OPEN;
    enum Status { OPEN, DONE }              // nested types are allowed
}

• An annotation interface is an interface declared with @interface. Its superinterface is always java.lang.annotation.Annotation; it cannot have an extends clause or type parameters.
• Each method declares an element. Elements have no parameters, no type parameters and no throws clause.
• An element’s type must be a primitive type, String, Class or a parameterisation of it such as Class<? extends Number>, an enum type, another annotation type, or a one-dimensional array of one of these. An annotation interface may not contain an element of its own type, directly or indirectly.
• Defaults and values must be constant expressions, class literals, enum constants, annotations or array initialisers of these. null is never allowed.
• The body may also declare constants and nested types.

Writing annotations

For an array element, a single value may be written without braces: @SuppressWarnings("unchecked") means @SuppressWarnings({"unchecked"}). Annotations are modifiers, so they may be mixed with other modifiers in any order, though by convention they come first.

Predefined annotations

The JLS gives these annotations of java.lang and java.lang.annotation a meaning to the compiler (JLS 9.6.4):

@Documented (Java 5) asks javadoc to show the annotation in the documentation. @Native (Java 8) marks a constant field that native code refers to.

Repeatable annotations

An annotation can be written several times on one element if it is marked @Repeatable with a containing annotation interface, whose value element is an array of it. The compiler wraps the repeats in the container:

@Repeatable(Schedules.class)
@interface Schedule { String day(); }

@interface Schedules { Schedule[] value(); }

@Schedule(day = "Mon")
@Schedule(day = "Thu")                     // stored as @Schedules({@Schedule(day = "Mon"), @Schedule(day = "Thu")})
void backup() {}

The container must have retention at least as long and targets no wider than the repeatable annotation.

Type annotations

Since Java 8 (JSR 308) an annotation whose target includes TYPE_USE can be written on any use of a type, so that checkers can track properties such as nullness:

@NonNull String name;
List<@NonNull String> names;
String @NonNull [] array;                  // the array is non-null
@NonNull String [] elements;               // the elements are non-null
Map.@NonNull Entry<K, V> entry;            // on a nested type: after the dot
new @Interned String("x");
Object o = (@NonNull Object) value;
void read() throws @Critical IOException;
class Box<@Immutable T> extends @Readonly Base implements @Remote Service {}
void m(@ReadOnly Box<T> this) {}           // a receiver parameter

An annotation in front of a declaration is a declaration annotation, a type annotation or both, depending on its targets. For array types, the annotation applies to the type it immediately precedes: before the element type for the elements, before a [] for that level of array. A type annotation cannot be written on a whole qualified name before the simple name: @NonNull java.lang.String is an error, while java.lang.@NonNull String is right.