Use annotation in Java

Annotation and Annotation Types
The first step in the post is defining an annotation type. This is pretty simple to do and looks familiar as well. An annotation-type declaration looks like an interface declaration except an "@" symbol precedes the interface keyword. The method declaration that goes between the braces of this declaration defines the elements of the annotation type. Of course, since we are annotating the code and not defining behavior, logically speaking, these methods shouldn't throw any exception. That means no throws clause. Another restriction is that the return type for these methods is restricted to primitives: String, Class, enums, annotations and arrays of the preceding types. The complete lists of restrictions are as follows:

• No extends clause is permitted.Annotation types automatically extend a marker interface, java.lang.annotation.Annotation.
• Methods must not have any parameters.
• Methods must not have any type parameters (in other words, generic methods are prohibited).
• Method return types are restricted to primitive types: String, Class, enum types, annotation types and arrays of the preceding types.
• No throws clause is permitted.
• Annotation types must not be parameterized.

The following code snippet defines an annotation type for a servlet. Presumably, we could use this definition to annotate a servlet and then have an annotation tool generate web.xml. Here we define no args methods that define the various XML attributes/elements found in web.xml. For conciseness we have left out elements like init, load on startup, icon etc.

public @interface Servlet {
    String servletName();
    String servletClass();
    String displayName();
    String description();
}

Declaring Annotation
Now that we have the annotation-type defined we can annotate our servlet using the defined annotation type. Annotation is a new kind of modifier that contains an annotation type with zero or more member-value pairs. If a member has a default value defined in the annotation-type member declaration then the value can be omitted, otherwise, annotation must provide a member-value pair for all members defined in the annotation type. Annotation can be used for modifiers in any declaration - class, interface, constructor, method, field, enum, even local variable. It can also be used on a package declaration provided only one annotation is permitted for a given package. In our case we are annotating at the class level and the annotation precedes the access modifier public.

@Servlet(
    	servletName="AnnotatedServet",
	servletClass="com.wonder.servlet.AnnotatedServet",
	displayName="AnnotatedServet",
    	description="This is an example Annotated Servlet"
)
public class AnnotatedServet extends HttpServlet{...}

Annotation Retention
The consumers of annotation fall into three categories.

• Introspectors: Programs that query runtime-visible annotations of their own program elements. These programs will load both annotated classes and annotation interfaces into the virtual machine.
• Specific Tools: Programs that query known annotation types of arbitrary external programs. Stub generators, for example, fall into this category. These programs will read annotated classes without loading them into the virtual machine, but will load annotation interfaces.
• General Tools: Programs that query arbitrary annotations of arbitrary external programs (such as compilers, documentation generators and class browsers). These programs will load neither annotated classes nor annotation interfaces into the virtual machine.

The grouping of annotation consumers mentioned above is determined by the retention policy that is specified by the RetentionPolicy enum present in the java.lang.annotation package. If the retention policy is 'CLASS' then the annotations are recorded in the class files but are not retained by the virtual machine. If the retention policy is 'RUNTIME' then the annotations are recorded in the class file and are retained by the VM at run-time. The value 'SOURCE' causes the compiler and VM to discard the annotation.

Annotation Processing Tool
The annotation processing tool (apt) found in JAVA_HOME/bin directory is a command-line utility that ships with JDK 5.0. This tool looks for annotation processors based on the annotation in the set of specified source files being examined. Essentially the annotation processor uses a set of reflective APIs and supporting infrastructure to process the annotations.

When invoked, the apt goes through the following sequence of operations: First, it determines what annotations are present in the source code being operated on. Next, it looks for annotation processor factories. It then asks the factories what annotations they process and, if the factory processes an annotation present in source files being operated on, the apt asks the factory to provide an annotation processor. Next, the annotation processors are run. If the processors have generated new source files, the apt will repeat this process until no new source files are generated. This high-level sequence is indicated in Figure 1.

To write a factory class, a developer has to rely on packages that aren't part of the standard SDK. The packages used are:

• com.sun.mirror.apt: interfaces to interact with the tool.
• com.sun.mirror.declaration: interfaces to model the source code declarations of fields, methods, classes, etc.
• com.sun.mirror.type: interfaces to model types found in the source code.
• com.sun.mirror.util: various utilities for processing types and declarations, including visitors.

These packages are bundled in tools.jar, and so this jar file needs to be set in the classpath to write and compile the factory class. Assuming that the path and the classpath are set correctly, the annotation processing tool can be invoked from the command prompt by typing 'apt' followed by the tools command-line parameters.