25.2 Declaring Annotation Types
An annotation type declaration specifies a new annotation type, and has a lot in common with an interface type. General syntax of an annotation type declaration is shown below.
meta-annotations access_modifier
@interface
annotation_name
// Annot type header
{ // Annotation type body with zero or more member declarations:
annotation_type_element_declarations
constant_variable_declarations
enum_declarations
class_declarations
interface_declarations
}
We will use the annotation type declaration TaskInfo below to explain the syntax of an annotation type declaration. The TaskInfo annotation type allows meta-information to be specified about tasks on program elements: a description of the task, people the task is assigned to, and the priority given to the task. The TaskInfo annotation type is meant to illustrate declaring annotation types, and is in no way meant to replace task management tools.
import java.lang.annotation.Target; // (1)
import java.lang.annotation.ElementType; // (2)
import java.lang.annotation.Retention; // (3)
import java.lang.annotation.RetentionPolicy; // (4)
@Target({ElementType.TYPE, ElementType.METHOD}) // (5) Meta-annotation
@Retention(RetentionPolicy.RUNTIME) // (6) Meta-annotation
public @interface TaskInfo { // (7)
String taskDesc(); // (8) Annotation type element
String[] assignedTo(); // (9) Annotation type element
TaskPriority priority() default TaskPriority.NORMAL; // (10) Annot type element
public enum TaskPriority { LOW, NORMAL, HIGH }; // (11) Nested enum type
public static final String LOG_FILE = “./logs/Tasks.log”; // (12) const decl.
}
The meta-annotations specified in the annotation type header are annotations that are applied to the annotation type declaration to specify certain aspects of the declaration—that is, they allow metadata to be associated with the annotation type declaration (p. 1567). In the code above, these meta-annotations are defined by classes in the java.lang.annotation package, which are imported at (1) and (3), together with auxiliary enum types at (2) and (4). The meta-annotation @Target at (5) specifies which program elements the annotation type can be applied to. The targets specified for the TaskInfo annotation type are any type declaration (Element-Type.TYPE) and methods (ElementType.METHOD). The @Retention meta-annotation specifies the retention policy: whether invocations of the annotation should be retained with the program element in the source file or in the class file, or made available at runtime. Applications of the TaskInfo annotation type on program elements will be available at runtime (RetentionPolicy.RUNTIME).
The access modifier that can be specified in the annotation type header is public, or there is no access modifier to indicate package accessibility—the same as with a normal interface. The TaskInfo annotation type is declared public.
Like any normal interface, an annotation type declaration is implicitly abstract, but seldom explicitly specified as such. Note also that an annotation type declaration cannot be generic and the extends clause is not permitted—in contrast to a normal interface.
The simple name of an annotation type shares the same namespace as simple names of normal classes and interfaces in a package—that is, a simple name of an annotation type should not conflict with any type declaration having the same simple name in the package.
The annotation type body can contain zero or more member declarations. These member declarations are analogous to the member declarations in a normal interface when it comes to constant variable declarations (which are implicitly public, static, and final) and nested type member declarations—but default, static, and private methods are not permitted. For example, the TaskInfo type annotation declaration declares a nested enum type named TaskPriority at (11) and a constant variable named LOG_FILE at (12).
In the rest of this section, we take a closer look at declaration of annotation type elements in the body of an annotation type, declared at (8), (9), and (10), as values provided for these annotation type elements when an annotation is applied to a program element determine the metadata that is associated with the program element.