Making the Most of Java's Metadata, Part 2: Custom Annotations
by Jason Hunter

Learn how to write your own annotation types and make use of built-in annotations to control their behavior.

Downloads for this article: Oracle Application Server 10g (10.1.3) Developer Preview 4 Oracle JDeveloper 10g

An @Unfinished Annotation Type

For our example let's imagine and then create an @Unfinished annotation type. The idea for this example comes from the common situation where you sketch out a block of code and leave some classes or methods temporarily unfinished—basic scaffolding on which proper code can and will be added later. Perhaps like me, you've traditionally marked these areas with a special "XXX" or "TODO" comment (something easy to search for). Using Java Metadata and a custom annotation type you can instead use an annotation to mark these code construct as @Unfinished.

This approach opens up a few interesting possibilities. You can, for example, at runtime have any unit tests that call into unfinished code produce a special "unfinished" result, something not to be confused with a regular failure. Or you could at compile time output warnings whenever fully completed code has a dependency on unfinished code, marking it as "effectively unfinished" as well. Plus, while comments tend to be free-form, an annotation type can be written to accept a description string, optional owner list, and a priority (with an assumed default).

You write annotations using a special @interface syntax:

public @interface Unfinished { }  // Unfinished.java

Our annotation is missing a lot of features, so for the moment let's self-referentially mark it unfinished:

@Unfinished
public @interface Unfinished { }

To provide your @Unfinished annotation type with its description, owner, and priority you'll need to add parameters to the annotation declaration. Annotation parameters follow certain strict rules:

• Parameters may only be typed as a primitive, String, Class, enum, annotation, or an array of any of these.
• Parameter values may never be null!
• Each parameter may declare a default value.
• A single parameter named "value" can be set in a shorthand style.
• Parameters are written as simple methods (no arguments, no throws clauses, etc).

@Unfinished("Just articleware")
public @interface Unfinished {
  public enum Priority { LOW, MEDIUM, HIGH }

  String value();
  String[] owners() default "";
  Priority priority() default Priority.MEDIUM;
}

The "value" parameter, because of its special name, is assumed when the attribute is passed just one parameter. You can see this in the "Just articleware" annotation. We had to add that description there because our "value" parameter declares no default value, so any use of the annotation without a description generates a compile error:

Unfinished.java:4: annotation Unfinished is missing value
@Unfinished
 ^
1 error

You might find the use of "default" in the declaration to be slightly odd, but the "default" keyword isn't new; Java used it previously in switch statements. You can tell a language is mature when each keyword has multiple uses.

Below is an example that demonstrates the @Unfinished parameter feature:

@Unfinished(
  value="Class scope",
  priority=Unfinished.Priority.LOW
)
public class UnfinishedDemo {

  @Unfinished("Constructor scope")
  public UnfinishedDemo() { }

  @Unfinished(owner="Jason", value="Method scope")
  public void foo() { }
}

What about a package level annotation? Because there's no natural place on which to put these, you place them within a specially named package-info.java file. It looks like this:

// package-info.java
@Unfinished("Package scope")
package com.servlets;

For the above package-info.java example to compile, the @Unfinished annotation can't reside in the default package anymore. Prior to J2SE 1.4 you could import classes from the default package using a syntax like this:

import Unfinished;

package com.servlets;

@Unfinished("Just articleware")
public @interface Unfinished { ...

Annotations on Annotations

J2SE 5.0 provides four annotations in the java.lang.annotation package that are used only when writing annotations:

• @Documented—Whether to put the annotation in Javadocs
• @Retention—When the annotation is needed
• @Target—Places the annotation can go
• @Inherited—Whether subclasses get the annotatio

@Documented

Annotations on a class or method don't by default appear in the Javadocs for that class or method. The @Documented annotation changes this. It's a simple marker annotation and accepts no parameters. With @Unfinished we want people to know which classes and methods have work remaining, so we will mark @Unfinished with this meta-annotation:

package com.servlets;
import java.lang.annotation.*;

@Unfinished("Just articleware")
@Documented
public @interface Unfinished { ...

How long do you want to keep your annotation? There are three options as listed in the RetentionPolicy enumeration:

package com.servlets;
import java.lang.annotation.*;

@Unfinished("Just articleware")
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Unfinished { ...

Now where do you want your annotation to be placed? You have eight options listed in the ElementType enumeration:

• ElementType.TYPE (class, interface, enum)
• ElementType.FIELD (instance variable)
• ElementType.METHOD
• ElementType.PARAMETER
• ElementType.CONSTRUCTOR
• ElementType.LOCAL_VARIABLE
• ElementType.ANNOTATION_TYPE (on another annotation)
• ElementType.PACKAGE (remember package-info.java)

package com.servlets;
import java.lang.annotation.*;

@Unfinished("Just articleware")
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE,ElementType.METHOD,
 ElementType.CONSTRUCTOR,ElementType.ANNOTATION_TYPE,
 ElementType.PACKAGE})
public @interface Unfinished { ...

Finally, @Inherited controls if an annotation should affect subclasses. Forexample, does an @Unfinished superclass imply an unfinished subclass? Probably so, so here's the final form of @Unfinished:

package com.servlets;
import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE,ElementType.METHOD,
 ElementType.CONSTRUCTOR,ElementType.ANNOTATION_TYPE,
 ElementType.PACKAGE})
@Inherited
public @interface Unfinished {
  public enum Priority { LOW, MEDIUM, HIGH }

  String value();
  String[] owners() default "";
  Priority priority() default Priority.MEDIUM;
}

In the next article in this series, I'll show how Java's reflection capabilities have been enhanced to help you discover annotations at runtime and how the Annotation Processing Tool "apt" lets you use annotations at build-time.

Send us your comments