Applying Normal Annotations
When a normal annotation is applied to a program element, in addition to the name of the annotation type being preceded by the at-sign (@), it can optionally specify a comma-separated list of element-value pairs enclosed in parentheses, (). Each pair has the syntax element = value. For each pair, the element and the value must be compatible with the method name and the return type of a method specified in an annotation type element.
The normal annotation for the annotation type TaskInfo (p. 1558) is applied to a class below, where each element-value pair associates a value with an element of the annotation type TaskInfo.
@TaskInfo( // Normal annotation
taskDesc = “Class for monitoring nuclear reactor activity”, // Required
assignedTo = {“Tom”, “Dick”, “Harriet”}, // Required
priority = TaskInfo.TaskPriority.HIGH // Optional
)
class NuclearPlant {}
A normal annotation must contain element-value pairs for all required annotation elements in the annotation type—that is, for elements that do not specify a default value. Specifying the element-value pairs for optional annotation elements is obviously optional.
The order of the element-value pairs is irrelevant, but usually they are specified in the same order that the elements have in the annotation type declaration. Note also that a null value in an element-value pair will result in a compile-time error.
In the normal annotation below, the optional annotation element priority in the annotation type TaskInfo is omitted.
@TaskInfo( // Normal
annotation
taskDesc = “Class for monitoring nuclear reactor activity”, // Required
assignedTo = {“Tom”, “Dick”, “Harriet”} // Required
)
class NuclearPlant {}
The above normal annotation is then equivalent to the normal annotation below, where the default value TaskInfo.TaskPriority.NORMAL of the optional annotation element priority is implied.
@TaskInfo( // Normal
annotation
taskDesc = “Class for monitoring nuclear reactor activity”, // Required
assignedTo = {“Tom”, “Dick”, “Harriet”}, // Required
priority = TaskInfo.TaskPriority.NORMAL // Implied
)
class NuclearPlant {}
An array element initializer, {v1, …, vn}, can be used to specify the values of array elements for annotation elements whose type is an array type. The curly brackets can be omitted when specifying the value for a single-element array-valued element-value pair—that is, where the type of the annotation type element is an array type, but only a single array element is specified in the annotation.
@TaskInfo(
priority = TaskInfo.TaskPriority.LOW,
taskDesc = “Start nuclear reactor”,
assignedTo = “Harriet” // Single-element array-valued element
)
class NuclearPlant {}