Reply

Annotations: Evolving an Annotation - Part 2

At 3:53 PM on Feb 18, 2005, R.J. Lorimer wrote:

This week topic has been annotations. If you haven't already - please see my previous tips on these new Java 5 additions:

Annotations: Utilizing the Standard Annotations
Annotations: Evolving an Annotation - Part 1

Last time we took our first steps at designing our new annotation - @Note . We've seen how we can already start using it in our code, and how annotations are integrated in to the language. One thing I have promised is how to interpret annotations as of Java 5 (using reflection at runtime). Before we get there, however, we have to have a full understanding of the feature set of annotations - primarily because these remaining features have a direct impact on that process. Those features I am referring to are the annotations available for annotations. Yes, that is correct, annotations can have annotations applied to them. The built-in annotations that can be applied to annotations are: @Documented , Inherited , @Retention , and @Target . Let's get started!

@Documented

@Documented is the first of the four 'for-annotations-only' annotations that I wan't to discuss. Essentially, the @Documented determines whether or not the annotation will show up in the Javadoc documentation for any class using it. The @Documented tag itself is, in fact, itself a @Documented annotation (as are all of the other annotations I'm discussing today). You can see what this means from a Javadoc perspective (note the annotations on the top) by looking at the @java.lang.annotation.Documented documentation. By the way, something I didn't know at first - for @Documented to work, your annotation's retention policy must be RUNTIME. Don't know what that means? Well, I'll bring it up again shortly - just know you have been warned . Here is our @Note annotation with the @Documented tag:

@Documented
public @interface Note {
 
}

@Inherited

@Inherited controls how the application of annotations applies when integrated with Java's inheritence model with traditional classes. The overall question is that if an annotation exists on a super-class, should it be implied that it is also a part of the sub-class? The reality is, it depends on the annotation itself. What I mean by the application of the annotation is (currently) how it appears to exist at runtime. To understand this, I'll give you a sneak peek at runtime inspection of annotations. For instance, if we were to make our @Note annotation @Inherited :

@Inherited
public @interface Note {
 // ...
}

... then this runtime test would apply:

@Note("Some Note on A")
public class ClassA {
 
}
 
public class ClassB extends ClassA {
 
 public static void main(String[] args) {
   boolean noteExistsOnB = ClassB.class.isAnnotationPresent(com.mypackage.Note.class);
   // if Note is inherited, this will be true, otherwise it will be false.
 }
}

In reality, however, it doesn't make a whole lot of sense for our @Note annotation to be inherited, so we'll leave it off.

@Retention

@java.lang.annotation.Retention is one of the most important annotation features to understand, at least, initially. It's pretty much all bout how long annotations stay around - from the raw source code, all the way to the runtime. To understand this further, we have to take a look at the java.lang.annotation.RetentionPolicy enumeration - which is the type of the sole value on the @Retention annotation. The RetentionPolicy enumeration has three enumeration values: SOURCE , CLASS , and RUNTIME . SOURCE basically means that the annotation is for the compiler's eyes only. Once the code is compiled, the annotations will be gone. CLASS means that the annotations make it in to the bytecode, but they aren't available through the reflection libraries for interpretation at runtime. Finally, RUNTIME means that it runs the full gamut - it is available for the compiler, it is stored in the compiled bytecode, and it is available in the runtime reflection libraries. For the time being, if you plan on writing custom annotations, chances are your choice will probably be pretty easy - it will be RUNTIME . While, as I mentioned previously, Java 6 is currently planned to include a way to process annotations at compile time, Java 5 doesn't have that option. In addition, unless you are spending time sifting through the bytecode of your Java class files using some bytecode engineering or post-processing, I doubt that the CLASS option will be terribly important to you. No, most developers will be using RUNTIME because it is the option that is a.) most readily avaiable and b.) can be executed while the program is running to produce results based on the available annotations.

One quick thing to re-address - because of the way that Javadoc works, if you have marked your annotation as @Documented , it must also be marked as having a runtime retention policy. This is an unfortunate side-effect, but is just the price you pay for clear documentation .

@Target

@java.lang.annotation.Target is the last annotation-annotation to talk about. @Target is used to define what Java elements annotations can be used on. For instance, @Target , @Retention , @Inherited , and @Documented should all only be used on annotations. Likewise, @Override (which I discussed in the prior tip) should only be used on methods. The comprehensive list of available targets can be seen on the ElementType enumeration:

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,
 
    /** Field declaration (inlcudes enum constants) */
    FIELD,
 
    /** Method declaration */
    METHOD,
 
    /** Parameter declaration */
    PARAMETER,
 
    /** Constructor declaration */
    CONSTRUCTOR,
 
    /** Local variable declaration */
    LOCAL_VARIABLE,
 
    /** Annotation type declaration */
    ANNOTATION_TYPE,
 
    /** Package declaration */
    PACKAGE
}

The two values that might be confusing are LOCAL_VARIABLE and PACKAGE . The LOCAL_VARIABLE annotation will be most useful at the compile time/bytecode time because currently, there is no way to ascertain a local variable using reflection. Unfortunately, there is no current local variable behavior at compile time. PACKAGE corresponds to the new allowed feature - a package-info.java file that contains only annotations for the package, followed by the package declaration itself:

@MyPackageAnnotation
@MyOtherPackageAnnotation(value1="Blah", value2="Blah2")
package com.mypackage;

So, what's next? Next is to learn how to read and interpret the annotations for elements at runtime. Stay tuned!