Annotations

• They provide information that you need to fully describe your program, but that cannot be expressed in Java.
• In general the kind of annotations you add and what you do with them are entirely up to you.
• Java SE5 contains three generalpurpose built-in annotations.
• Four additional annotation types support the creation of new annotations.
• Annotations are true language constructs and hence are structured, and are type-checked at compile time.

Basic syntax

• Syntactically, annotations are used in much the same way as modifiers.

Defining annotations

• Annotation definitions look a lot like interface definitions. In fact, they compile to class files like any other Java interface.
• **@Target** defines where you can apply this annotation (a method or a field).
• **@Retention** defines whether the annotations are available in the source code (SOURCE), in the class files (CLASS), or at run time (RUNTIME).
• Elements look like interface methods, except that you can declare default values.

Meta-annotations

• The meta-annotations are for annotating annotations.
• Most of the time, you will be defining your own annotations and writing your own processors to deal with them.

Writing annotation processors

• An important part of the process of using annotations is to create and use annotation processors.
• Java SE5 provides extensions to the reflection API to help you create these tools.

Annotation elements

• Note that you are not allowed to use any of the wrapper classes, but because of autoboxing this isn’t really a limitation.
• You can also have elements that are themselves annotations.

Default value constraints

• No element can have an unspecified value. This means that elements must either have default values or values provided by the class that uses the annotation.
• non-primitive type elements are allowed to take null as a value, either when declared in the source code or when defined as a default value in the annotation interface.

Generating external files

• Annotations are especially useful when working with frameworks that require some sort of additional information to accompany your source code.
• After defining a Java class, the programmer must undergo the tedium of respecifying information like the name, package and so on—information that already exists in the original class.
• If you define an element on an annotation with the name value, then as long as it is the only element type specified you don’t need to use the name-value pair syntax; you can just specify the value in parentheses.

Annotations don’t support inheritance

• You cannot use the extends keyword with **@interfaces**. There doesn’t seem to be any suggestion of annotations supporting inheritance in future releases.

Implementing the processor

• There is no inheritance of annotation interfaces, using getDeclaredAnnotations( ) is the only way you can approximate polymorphic behavior.

Using apt to process annotations

• apt is designed to be run on Java source files rather than compiled classes. By default, apt compiles the source files when it has finished processing them.
• The apt tool can easily group several annotation processors together. It allows you to specify multiple classes to be processed, which is a lot easier than having to iterate through File classes yourself.
• apt works by using an AnnotationProcessorFactory to create the right kind of annotation processor for each annotation it finds.
• When you run apt, you specify either a factory class or a classpath where it can find the factories it needs.
• When you create an annotation processor for use with apt, you can’t use the reflection features in Java because you are working with source code, not compiled classes.

Using the Visitor pattern with apt

• Processing annotations can become complex.
• To prevent the complexity from scaling up badly when you have more annotations and more processors, the mirror API provides classes to support the Visitor design pattern.
• A Visitor traverses a data structure or collection of objects, performing an operation on each one.
• The data structure need not be ordered, and the operation that you perform on each object will be specific to its type.
• This decouples the operations from the objects themselves, meaning that you can add new operations without adding methods to the class definitions.
• When you use the apt tool with the Visitor pattern, you provide a Visitor class which has a method for handling each type of declaration that you visit.

Annotation-based unit testing

• With annotations we can include the unit tests inside the class to be tested, and thus reduce the time and trouble of unit testing to a minimum.
• This approach has the additional benefit of being able to test private methods as easily as public ones.