Learn to Use the New Annotation Feature of Java 5.0 : Page 2

Annotating Code
Annotations fall into three categories: normal annotations, single member annotations, and marker annotations (see Table 1). Normal and single member annotations can take member values as arguments when you annotate your code.

Category	Example
Normal Annotations—Annotations that take multiple arguments. The syntax for these annotations provides the ability to pass in data for all the members defined in an annotation type.	@MyNormalAnnotation(mem1="val1", mem2="val2") public void someMethod() { ... }
Single Member Annotations—An annotation that only takes a single argument has a more compact syntax. You don't need to provide the member name.	@MySingleMemberAnnotation("a single value") public class SomeClass { ... }
Marker Annotations—These annotations take no parameters. They are used to mark a Java element to be processed in a particular way.	@Deprecated public void doWork() { ... }

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
    }    
}

As you can see in the ClassLevelAnnotation, annotations may also take arrays of values. When creating an annotation that requires an array you must surround the array of parameters with brackets ( { … } ) and you must comma-separate each array parameter.

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;
}

This code shows how to use meta-annotations when declaring your own annotation type. I will cover the specifics on declaring annotation types and meta-annotation types later, but for now, just know that you can use meta-annotations to annotate other annotations.

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).

Previous Page

Next Page