Previous versions of Java provided a limited and ad-hoc mechanism for annotating code through JavaDoc comments and keyword modifiers. Tools such as XDoclet provide a slightly more sophisticated, yet non-standard annotation syntax, which piggybacks on top of JavaDoc. But now, with Java 1.5, annotations are a typed part of the Java language and allow for both runtime and compile-time processing of annotation data.

What Are Annotations?
In short, annotations are metadata or data about data. Annotations are said to annotate a Java element. An annotation indicates that the declared element should be processed in some special way by a compiler, development tool, deployment tool, or during runtime.

Older versions of Java have rough-and-ready annotation functionality. A good example is the @deprecated JavaDoc tag. The @deprecated tag is used for more than sheer documentation purposes. This tag has no effect on the code it describes, but causes the compiler to produce warnings if any other code references the tagged element. JavaDoc does not seem to be the proper place for this type of metadata, but there was no other annotation facility in previous versions of Java. With Java 1.5, finally, annotations are a typed part of the language and the version even comes with some with pre-built annotations, one of which can be used to mark a class as deprecated (I'll cover this later).

The code below shows how you can declare a method that uses an annotation. It is one of Java 1.5's built-in annotation types:

class Child extends Parent {
    @Overrides
    public void doWork() {
        //do something      
    }
}

Annotations types are blueprints for annotations, similar to how a class is the blueprint for an object. You can create your own custom annotations by defining annotation types.

The code below shows the declaration of a normal annotation type:

public @interface MyAnnotationType {
    int someValue();
    String someOtherValue();
}

Annotations will also be used for compile-time checking such as to produce warnings and errors for different failure scenarios. An example of an annotation that is used at compile time is the new @Deprecated annotation, which acts the same as the old @deprecated JavaDoc tag. Of course, a compiler has to know how to interpret annotation data that is meant to produce compile-time warnings, so again, annotations that do things at compile time will likely be used frequently, but rarely written by average developers.

Annotations can be useful at runtime as well. Using annotations you could mark code to behave in a particular way whenever it is called. For example, you could mark some methods with a @prelog annotation. Then at runtime, you could analyze the methods that you're calling and print a particular log message before you begin executing code for that method. One way to achieve this would be through the use of the updated Java 1.5 reflection API. The reflection API now provides access to runtime-accessible annotation data.

< Another way to use annotations at runtime is to use Aspect-Oriented Programming (AOP). AOP uses pointcuts—sets of points configured to executed aspects. You could define a pointcut that will execute an aspect for an annotated method. My guess is that developers would be more likely to write their own runtime annotation types than they would annotation types used for code generation and compile-time checking. Still, writing and understanding the code that accesses the annotations (the annotation consumer) at runtime is fairly advanced.

Any Java declaration can be marked with an annotation. That is, an annotation can be used on a: package, class, interface, field, method, parameter, constructor, enum (newly available in Java 1.5), or local variable. An annotation can even annotate another annotation. Such annotations are called meta-annotations.

This code below shows an annotated class, constructor, field, and method.

@ClassLevelAnnotation(arg1="val1", arg2={"arg2.val1","arg2.val2"})
public class AnnotationExample {

    @FieldLevelAnnotation()
    public String field;    

    @CtorLevelAnnotation()
    public AnnotationsTest() {
        // code
    }

    @MethodLevelAnnotationA("val")
    @MethodLevelAnnotationB(arg1="val1",arg2="val2")
    public void someMethod(String string) {
        // code
    }    
}

Annotation types may define default values for some members. Every member-value pair that does not have a default value must be supplied when you create an annotation.

The annotation-type declaration below uses meta-annotations, which provide information on how the annotation type can be used:

@Retention(RUNTIME) 
@Target(METHOD)
public @interface MyAnnotationType {
    String value;
}

Packages annotations are also allowed, but because packages are not explicitly declared in Java, package annotations must be declared in a source file called package-info.java in the directory containing the source files for the package. This file should contain only a package declaration, preceded by any annotations that should apply to the package. This java file must not contain an actual class definition (which would be illegal anyways, because package-info is not a legal identifier).

java.lang.Override

@Target(value=METHOD)
@Retention(value=SOURCE)
public @interface Override

This annotation is useful in avoiding the situation where you think you are overriding a method, but you misspell the method name in the child class. The code in the method you are trying to override in the parent class will be used because the name is misspelled in the child class. This is usually a difficult bug to track down because no compiler or runtime error is thrown. But marking a method with the Override annotation would help you realize this type of problem at compile time rather than through arduous debugging.

java.lang.Deprecated

@Documented
@Retention(value=RUNTIME)
public @interface Deprecated

java.lang.SuppressWarning

@Target(value={TYPE,FIELD,METHOD,PARAMETER,CONSTRUCTOR,LOCAL_VARIABLE})
@Retention(value=SOURCE)
public @interface SuppressWarnings

java.lang.annotation.Documented

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Documented

java.lang.annotation.Inherited

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Inherited

Note that this meta-annotation type has no effect if the annotated type is used for anything other than a class. Also, this meta-annotation causes annotations to be inherited only from superclasses; annotations on implemented interfaces have no effect.

java.lang.annotation.Retention

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Retention

• SOURCE—Annotations are to be discarded by the compiler.
• CLASS—Annotations are to be recorded in the class file by the compiler but need not be retained by the VM at runtime. This is the default behavior.
• RUNTIME—Annotations are to be recorded in the class file by the compiler and retained by the VM at runtime, so they may be read reflectively.

If no Retention annotation is present on an annotation type declaration, the retention policy defaults to RetentionPolicy.CLASS. By default, the annotation data is not available in the JVM in order to reduce overhead.

java.lang.annotation.Target

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Target

• TYPE (class, interface or enum declaration)
• FIELD (includes enum constants)
• METHOD
• PARAMETER
• CONSTRUCTOR
• LOCAL_VARIABLE
• ANNOTATION_TYPE
• PACKAGE

Here is a sample annotation type:

public @interface MyAnnotationType {
    int someValue();
    String someOtherValue();
    String yesSomeOtherValue() default "[blank]";

}

At first, it seems a little odd to specify the members of an annotation using method syntax, because when you declare a Java element and annotate it (e.g. when you annotate a class), you may pass values into the annotation. But you are not the consumer of the annotation at this point; you are merely constructing an instance of the annotation. Think of it as calling a constructor on an implicit Java class that you didn't have to write.

The annotation consumers are the development tools, the compiler, or a runtime library that accesses the annotation data you created when you annotated your Java code. After you've created the annotation, annotation consumers may call the methods on the annotation interface in order to get the annotation values. The return types of the methods represent the type of data that a consumer of the annotation would get back.

There are a few restrictions when defining annotation types.

• Annotations cannot extend other annotations, except for the java.lang.annotation.Annotation marker interface they inherently extend.
• Method return types must be: primitive types, String, Class, enum types, annotation types, or arrays of the preceding types.
• Annotations can't have a throws clause.
• Self reference is not allowed (e.g. AnnotationA contains a member of type AnnotationA), nor circular reference (e.g. AnnotationA contains a member of type AnnotationB and vice versa).
• Single member annotations must define only a single method called value in the annotation type. So long as you follow this construct, you can use the condensed single-member syntax when creating an annotation of this type.
  
  A single member annotation can be defined as follows:

  
  public @interface Copyright {
      String value();
  }
  

Here is the declaration for the @ Inherited meta-annotation type:

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Inherited

Reading Annotations
Now that you know how to declare your own annotation types and annotate Java elements, you need to know how to access the annotation data you specified. Annotation consumers are software that read annotation data and do something useful with it. Annotation consumers fall into three groups:

General tools are programs that can analyze source code and do something useful with it. For example compilers and documentation generators are both considered general tools. General tools do not load annotated classes or annotation interfaces into the virtual machine.

Specific tools are also programs that can analyze source code without loading annotated classes, but they need to load annotation interfaces into the virtual machine. An example of this is a Stub generator.

Introspectors are programs that can query their own annotations (the ones with a RUNTIME retention policy). Introspectors will load both annotated classes and annotation interfaces into the virtual machine.

Listing 1 is an example of how you can access your code during runtime using the reflection API.

As I mentioned previously, I think that most developers will be users of annotations, but few will have to write code that consumes annotations.

If you are a general or specific tools developer, you may want to look into a few APIs that will help you read annotations from source files in order to use them for some type of static preprocessing. The new Doclet API (com.sun.javadoc) has support for reading annotations. It doesn’t currently support all of the features of annotations, but it may suffice as a library for writing your tool. Another thing to keep an eye on is the newly submitted JSR-269 (Pluggable Annotation Processing API), which will provide a generic API that allows developers to read annotation data using general and specific tools.

If you are developing an introspector, you can use the new reflection API to access your annotations, though I would suggest looking into AOP as a means to interface with annotated methods. I think there is a lot of room for exploration here. The combinations of aspects and annotations can yield a very powerful introspection tool.