INTERFACES(3)

INTERFACES(3)

ANNOTATION TYPES
An annotation type declaration is a special type of interface declaration using the at sign @ along with the keyword interface.

Notation:
InterfaceModifiersopt @interface Identifier AnnotationTypeBody

AnnotationTypeBody: {AnnotationTypeElementDeclarationopt}

Where the annotation type element declarations can be one or many and notated as either one or many of:
AbstractMethodModifiersopt Type Identifier() DefaultValueopt;
ConstantDeclaration
ClassDeclaration
InterfaceDeclaration
EnumDeclaration
AnnotationTypeDeclaration
;

The default values are notated thus: default ElementValue

By virtue of its context free syntax, the following restrictions are imposed on annotation type declarations:
1. annotation type declarations cannot be generic
2. no extends clause is permitted (annotation types (denoted with the sign @) implicitly extend annotation.Annotation.)
3. methods cannot have any parameter
4. methods cannot have any type parameter.
5. method declarations cannot have a throws clause.

Take note: unless explicitly modified, all the rules applying to ordinary interface declarations apply to annotation type declarations.

The identifier in an annotation type declaration specifies the annotation type name and it cannot be the same simple name as any of its enclosing classes or interfaces.

If an annotation a on an annotation type declaration corresponds to an annotation type T, and T has a (meta-)annotation m that corresponds to annotation.Target, then m must have an element whose value is annotation.ElementType.ANNOTATION_TYPE or annotation.ElementType.TYPE or a compile time error occurs.

The direct superinterface of an annotation type is always annotation.Annotation.

The return type of a method declared in an annotation type is either:
1. one of the primitive types
2. String
3. Class and any invocation of Class
4. an enum type
5. an annotation type
6. an array of any of the types above,
otherwise a compile time error occurs.

If any method declaration in an annotation type has a signature that is override-equivalent to that of any public or protected method declared in the class Object or in the interface annotation.Annotation, then a compile time error occurs.

Each method declaration in an annotation type declaration defines an element of the annotation type. Annotation types can have zero or more elements which are only those defined by the methods it explicitly declares.

A compile time error for an annotation of type T to contain an element of type T, either directly or indirectly.

An annotation type element may have a default value specified. This is done by following the empty parameter list with the keyword default and then the default value of the element.

An ElementValue is used to specify a default value and must be correctly typed otherwise a compile time error. An ElementValue is always FP-strict.

(see jls for example. No need to duplicate it here. )

By convention, value is the name of the sole element in a single-element annotation type.

Predefined annotation types:
Target: this predefined annotation type is used in meta-annotations to indicate that the kind of program element an annotation type is applicable to.

Target has one element of, annotation.ElementType[]

The meta-annotation below indicates that the declared type is itself a meta-annotation type. It can only be used on annotation type declarations.

@Target (ElementType.ANNOTATION_TYPE)
public @interface MetaAnnotationtype { ... }

the meta-annotation below indicates that the declared type is intended solely for use as a member type in complex annotation type declarations. It cannot be used to annotate anything directly.

@Target ({})
public @interface MemberType { ... }

note: a single ElementType cannot appear more than once in a Target annotation.

Retention: indicates if annotations may be present only in the source code or in the binary form of a class or interface. The annotation type, annotation.Retention is used to choose between the above two.

If an annotation a corresponds to type T and T has a meta-annotation m that corresponds to annotation.Retention, then
- if m has an element whose value is annotation.RetentionPolicy.SOURCE, then a java compiler must ensure that a is not present in the binary representation of the class and interface in which it appears.
- If m has an element with value annotation.RetentionPolicy.CLASS , or annotation.RetentionPolicy.RUNTIME, then a java compiler must ensure that a is represented in the binary representation of the class or interface in which a appears, unless m annotates a local variable declaration, then it won’t be retained in the binary representation.

Inherited: this indicates that annotations on this class are automatically inherited.

Override: this annotation is useful for early detection of programmers mistaking an overload for an override for a method.

If a method declaration is annoted with the annotation @override, but this method does not in fact override any method declared in a superclass, a compile time error will occur.

SuppressWarnings: used to indicate that the named compiler warnings should be suppressed in the annotated element (and in all program elements contained in the annotated element). It contains a single element that is an array of String.