Java 1.5 Tiger A Developers Notebook [Electronic resources] نسخه متنی

6.11 Reflecting on Annotations

So far, all the discussions

on annotations have been around looking at
them visuallyeither in source code or in Javadoc. However, there are
enough code introspection tools these days that it's worth talking about
using reflection to determine what annotations a class (or field, or
method) has. The java.lang.reflect package has several additions that
make this a piece of cake.

6.11.1 How do I do that?

The easiest way to check for an annotation is by using the
isAnnotationPresent( ) method. This lets you specify the annotation to
check for, and get a true/false result:

     public void testAnnotationPresent(PrintStream out) throws IOException {
Class c = Super.class;
boolean inProgress = c.isAnnotationPresent(InProgress.class);
if (inProgress) {
out.println("Super is In Progress");
} else {
out.println("Super is not In Progress");
}
}

NOTE

This code is in the
ReflectionTester
class.

Running this code gives you the following output:

   run-ch06:
[echo] Running Chapter 6 examples from Java Tiger: A Developer's
Notebook
[echo] Running ReflectionTester...
[java] Super is In Progress

Additionally, this approach lets you take advantage of the Inherited
annotation, described in Setting Up Inheritance in Annotations:

     public void testInheritedAnnotation(PrintStream out) throws IOException {
Class c = Sub.class;
boolean inProgress = c.isAnnotationPresent(InProgress.class);
if (inProgress) {
out.println("Sub is In Progress");
} else {
out.println("Sub is not In Progress");
}
}

NOTE

This assumes you
follow the steps
in "Setting Up
Inheritance in
Annotations" and
mark "Super" as
being in progress.

Remember that although Sub is not marked as in progress, it inherits
from Super, which is in progress. Additionally, the InProgress annotation
was marked as Inherited, so the in-progress indicator should be
passed on to subclasses. Running this new method shows that this,
indeed, works:

    run-ch06:
[echo] Running Chapter 6 examples from Java Tiger: A Developer's
Notebook
[echo] Running VarargsTester...
[java] Super is In Progress
[java] Sub is In Progress

Although this is not picked up in the Javadoc, it certainly appears in your
reflection-based code.

If you're not checking for a marker interface, though, you may have to go
beyond isAnnotationPresent( )especially if you need to get values
from the annotation. Here's a simple example:

NOTE

Reflection on
annotations only
works for annotation
types that
have Runtime
retention.

     public void testGetAnnotation(PrintStream out)
throws IOException, NoSuchMethodException {
Class c = AnnotationTester.class;
MethodElement element = c.getMethod("calculateInterest",
float.class, float.class);
GroupTODO groupTodo = element.getAnnotation(GroupTODO.class);
String assignedTo = groupTodo.assignedTo( );
out.println("TODO Item on Annotation Tester is assigned to: '" +
assignedTo + "'");
}

Once the method in question is located (in this case,
calculateInterest( ) on the AnnotationTester class), that method can
be queried for a specific annotation. In this case, the code locates the
GroupTODO annotation, and grabs the value of assignedTo. The output of
this method is shown here:

     run-ch06:
[echo] Running Chapter 6 examples from Java Tiger: A Developer's
Notebook
[echo] Running ReflectionTester...
[java] Super is In Progress
[java] Sub is In Progress
[java] TODO Item on Annotation Tester is assigned to: 'Brett
McLaughlin'

To use this code, you obviously have to know exactly what you're looking
forand that's one of the few drawbacks of getAnnotation( ).

Finally, you can use getAnnotations( ) if you're trying to locate all annotations
for a program element, or if you need to iterate through all annotations
looking for a specific one. For example, here's a simple utility
method that prints out all annotations for a supplied element:

NOTE

The for/in loop is
detailed in
Chapter 7, and
printf( ) and
other new
formatting
methods are
covered in
Chapter 9.

    public void printAnnotations(AnnotatedElement e, PrintStream out)
throws IOException {
out.printf("Printing annotations for '%s'%n%n", e.toString( ));
Annotation[] annotations = e.getAnnotations( );
for (Annotation a : annotations) {
out.printf("    * Annotation '%s' found%n",
a.annotationType( ).getName( ));
}
}

If you supplied this method the calculateInterest( ) method from
AnnotationTester, you'd get the following output:

   run-ch06:
[echo] Running Chapter 6 examples from Java Tiger: A Developer's
Notebook
[echo] Running ReflectionTester...
[java] Super is In Progress
[java] Sub is In Progress
[java] TODO Item on Annotation Tester is assigned to: 'Brett
McLaughlin'
[java] Printing annotations for 'public void com.oreilly.tiger.ch06.
Annotat
ionTester.calculateInterest(float,float)'
[java]     * Annotation 'com.oreilly.tiger.ch06.InProgress' found
[java]     * Annotation 'com.oreilly.tiger.ch06.GroupTODO' found

This code is really pretty straightforward, so I'll leave it to you to work
through the details. Example 6-15 is the complete code listing for
ReflectionTester, which has all these reflection-based annotation
methods within it.

NOTE

If you don't want
to pick up
inherited
annotations, you
can use get
DeclaredAnnotations(
)
instead of
getAnnotations( ).

Example 6-15. Testing reflection-based annotation methods

package com.oreilly.tiger.ch06;
import java.io.IOException;
import java.io.PrintStream;
import java.lang.reflect.AnnotatedElement;
import java.lang.annotation.Annotation;
public class ReflectionTester {
public ReflectionTester( ) {
}
public void testAnnotationPresent(PrintStream out) throws IOException {
Class c = Super.class;
boolean inProgress = c.isAnnotationPresent(InProgress.class);
if (inProgress) {
out.println("Super is In Progress");
} else {
out.println("Super is not In Progress");
}
}
public void testInheritedAnnotation(PrintStream out) throws IOException {
Class c = Sub.class;
boolean inProgress = c.isAnnotationPresent(InProgress.class);
if (inProgress) {
out.println("Sub is In Progress");
} else {
out.println("Sub is not In Progress");
}
}
public void testGetAnnotation(PrintStream out)
throws IOException, NoSuchMethodException {
Class c = AnnotationTester.class;
AnnotatedElement element = c.getMethod("calculateInterest",
float.class, float.class);
GroupTODO groupTodo = element.getAnnotation(GroupTODO.class);
String assignedTo = groupTodo.assignedTo( );
out.println("TODO Item on Annotation Tester is assigned to: '" +
assignedTo + "'");
}
public void printAnnotations(AnnotatedElement e, PrintStream out)
throws IOException {
out.printf("Printing annotations for '%s'%n%n", e.toString( ));
Annotation[] annotations = e.getAnnotations( );
for (Annotation a : annotations) {
out.printf("      * Annotation '%s' found%n",
a.annotationType( ).getName( ));
}
}
public static void main(String[] args) {
try {
ReflectionTester tester = new ReflectionTester( );
tester.testAnnotationPresent(System.out);
tester.testInheritedAnnotation(System.out);
tester.testGetAnnotation(System.out);
Class c = AnnotationTester.class;
AnnotatedElement element = c.getMethod("calculateInterest",
float.class, float.class);
tester.printAnnotations(element, System.out);
} catch (Exception e) {
e.printStackTrace( );
}
}
}

NOTE

AnnotatedElement
is a new
interface that
the reflection
constructs (like
Method and
Class) implement.
It allows access
to the new
annotation
methods used in
this code.

6.11.2 What just happened?

The key to much of the code you've just seen is a new interface, java.lang.reflect.AnnotatedElement. In Tiger, the core reflection constructs
all implement this interface: Class, Constructor, Field, Method, Package,
and AccessibleObject. This allows for the code you've already seen to
be introspected for annotationsall these element types provide the following
methods as a result of implementing AnnotatedType:

     public Annotation getAnnotation(Class annotationType);
public Annotation[] getAnnotations( );
public Annotation[] getDeclaredAnnotations( );
public boolean isAnnotationPresent(Class annotationType);

Since any Java program element can be treated as an AnnotatedType,
you can always get at an element's annotations using these methods.

NOTE

I've simplified the
generics syntax
for clarity here.
If you're into
generics, check out
the Javadoc on
AnnotatedElement
for more
details on
parameters and
return types for
these methods.

6.11.3 What about...

...annotations that aren't marked as visible at runtime? Recall that you
have to explicitly set an annotation's retention to RetentionPolicy.RUNTIME for any of this to work. Even if the annotation is retained at compilation (the default behavior), if the VM doesn't load this retention at
class-load time, then reflection can't pick up the annotation. In fact, this
is why the Inherited and Documented annotations should always be
paired up with the following annotation:

     @Retention(RetentionPolicy.RUNTIME)

This ensures that your documentation and/or inheritance is actually
readable by code-introspection tools.

Oddly enough, Deprecation does not have runtime retentionit has source retention. So, one of the most valuable annotations, the one indicating deprecation, is undetectable through Java reflection.