INTERFACES(4)

INTERFACES(4)

ANNOTATIONS
Annotations provide data about a program that is not part of the program itself. They have no direct effect on the operation of the code they annotate.

Annotations have a number of uses, among which are:
1. they provide information for compilers and can be used to detect or suppress warnings.
2. can be used for compiler-time and deployment-time processing. Software tools can process annotations to generate code, XML files and so forth.
3. for runtime processing. Some annotations are available for examination at runtime.

Note that annotations may be used as modifiers in any declaration, whether package, class, interface, field, method, parameter, constructor or local variable.

package examples;

public @interface Author {
String name();
String date();}

//annotation as modifier for class MyClass
//annotations *must* contain an element-value pair for
//every element of the corresponding annotation type
@Author (
name="nnaemeka david",
date="10/04/2007"
)
public class MyClass {}

annotations may also be used on enum constants.

A compile time error is more than one annotation is specified for a declaration.

There are 3 kinds of annotations:
1. normal annotations – these are fully general annotations
2. marker annotations – these are shorthand annotations
3. single-element annotations - these are shorthand annotations

Normal annotations: normal annotations are used to annotate program elements.

Notation: @TypeName (ElementValuePairsopt)

Where ElementValuePairs are notated as: Identifier = ElementValue

And ElementValue is either:
a. a conditional expression
b. an annotation
c. an element value array initialiser which is notated as {ElementValueopt,opt}

example:
public @interface Author {
String name(); //return type of this method defines the element type
//of the element-value pair
}

//here, TypeName is Author; identifier is name, Element
//value conforms to the return type for method name in
//Author annotation, which is String.
@Author(name="nnaemeka david")
public class MyClass {}

the element type T of the element-value pair is commensurate with an element value V if and only if one of the following conditions is true:
1. T is an array type E[] and either
a. V is an ElementValueArrayInitialiser and each ElementValue initialized in V is commensurate with E, or
b. V is an element value that is commensurate with T

2. The type of V is assignment compatible with T and therefore
a. If T is a primitive type or String, V is a constant expression
b. V is not null
c. If T is Class, or an invocation of Class, and V is a class literal
d. If T is an enum type and V is an enum constant.
Element types must always be commensurate with element values.
Little example:

package examples;

public @interface Author {
int[] number();
}

public @interface Author {
int[] number();
}

An annotation on an annotation type declaration is called a meta-annotation.

import java.lang.annotation.*; //these type on demand import necessary
//to use @Document annotation

//a meta-annotation
@Documented
public @interface Author {
int[] number();
}

Marker annotations: marker annotations notated as: @TypeName
are simply shorthands for the normal annotation, @TypeName().

package examples;

import java.lang.annotation.*;

@Documented
public @interface Author {}

//marker annotation
@Author()
public class MyClass {}

Simple-element annotation: this is a shorthand designed for use with single-element annotation types. Note that by convention, single-element annotation types have a single method, value.

The notation for single-element annotation is: @TypeName(ElementValue) which is the shorthand for the normal annotation: @TypeName(value = ElementValue).

package examples;

import java.lang.annotation.*;

@Documented
public @interface Author {
String value();
}

//single-element annotation
@Author("david")
public class MyClass {}

there are lots of examples in section §9.7 that illustrates this three types of annotations.