In annotation processors one common use case is to read the values contained within an Annotation. In most cases this works fine, however there are some caveats when it comes to accessing values within Annotations that are either Class or a Class array. It’s even worse if you are trying to access an annotation on a method within a super type of the class you are processing. Here I’ll go through how to access those Class values and how to get those values when they are in a super type - specifically when a method has been overridden.
First why?
Well inside retepTools we have an AnnotationProcessor that checks to ensure that certain annotations are used correctly, specifically the @ReadLock and @WriteLock annotations. It’s invalid for those annotations to be used together on the same method. It’s also invalid for a method to be annotated with one and then overridden in another class but annotated with the other, so the processor checks the overridden method and generates an error if the rules have been violated.
Now this caused be a big headache in reading the overridden annotations, because although the annotations were present, the values (and specific the Class ones) were null. Although @ReadLock and @WriteLock do not use values, another related annotation @Contract does, so here’s how I finally solved the problem.
The usual way of reading annotation values
In most cases, when you have an javax.lang.model.element.Element you can use the getAnnotation() method to return your annotation and then you have access to the values contained within it. For example say we have an annotation called Action which holds a single String value:
@Documented @Retention( RetentionPolicy.RUNTIME )
@Target(ElementType.METHOD)
public @interface Action
{
String value();
}
We annotate a class with that annotation against the run method:
public class A {
@Action( “do something” )
public void run() {
}
}
Now within your AnnotationProcessor, you can obviously get the value easily by calling getAnnotation( Action.class ) and if it returns an instance call the value() method:
@SupportedAnnotationTypes( "*" )
@SupportedSourceVersion( SourceVersion.RELEASE_6 )
@ProhibitAnnotationProcessing
public class Processor
extends AbstractProcessor
{
@Override
public boolean process( final Set<? extends TypeElement> annotations,
final RoundEnvironment env )
{
if( !env.processingOver() )
{
for( Element e : env.getRootElements() )
{
TypeElement te = findEnclosingTypeElement( e );
System.out.printf( "\nScanning Type %s\n\n",
te.getQualifiedName() );
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
Action action = ee.getAnnotation( Action.class );
System.out.printf(
"%s Action value = %s\n",
ee.getSimpleName(),
action == null ? null : action.value() );
}
}
}
return false;
}
public static TypeElement findEnclosingTypeElement( Element e )
{
while( e != null && !(e instanceof TypeElement) )
{
e = e.getEnclosingElement();
}
return TypeElement.class.cast( e );
}
}
This generates the following output when run:
------------------------------------------------------------------------
Building scratch
task-segment: [clean, install]
------------------------------------------------------------------------
[clean:clean]
Deleting directory /Users/peter/dev/retep/scratch/target
[compiler:compile {execution: compileAnnotations}]
Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes
[resources:resources]
Using default encoding to copy filtered resources.
[compiler:compile]
Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes
Scanning Type scratch.A
run Action value = do something
Reading annotation values from an overridden method
Now this is fine, but what happens if you are looking at an annotation thats in an overridden class?
Say we have class B which extends A and overrides run():
public class B extends A {
@Override
public void run() {
}
}
Now when we run the processor, for each ExecutableElement we’ll first look for an annotation and then if not found we’ll look for an overridden method and check there.
@Override
public boolean process( final Set<? extends TypeElement> annotations,
final RoundEnvironment env )
{
if( !env.processingOver() )
{
for( Element e : env.getRootElements() )
{
TypeElement te = findEnclosingTypeElement( e );
System.out.printf( "\nScanning Type %s\n\n",
te.getQualifiedName() );
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
Action action = ee.getAnnotation( Action.class );
if( action == null )
{
// Look for the overridden method
ExecutableElement oe = getExecutableElement( te,
ee.getSimpleName() );
if( oe != null )
{
action = oe.getAnnotation( Action.class );
}
}
System.out.printf(
"%s Action value = %s\n",
ee.getSimpleName(),
action == null ? null : action.value() );
}
}
}
return false;
}
public ExecutableElement getExecutableElement( final TypeElement typeElement,
final Name name )
{
TypeElement te = typeElement;
do
{
te = (TypeElement) processingEnv.getTypeUtils().asElement(
te.getSuperclass() );
if( te != null )
{
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
if( name.equals( ee.getSimpleName() ) && ee.getParameters().isEmpty() )
{
return ee;
}
}
}
} while( te != null );
return null;
}
Now when we run we get the annotated value on A.run() when we are processing B.run():
[compiler:compile]
Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes
Scanning Type scratch.A
run Action value = do something
Scanning Type scratch.B
run Action value = do something
The problem with Class
Now this is fine, but what happens if the annotation’s value is Class instead of String? Well the problem here is that Javac does not load classes in the normal manner. In fact it doesn’t at all for classes that are in the source - it’s all contained within a model.
Now say our Action annotation had value defined as Class instead of String. In that case when we call action.value() it would fail:
[compiler:compile]
Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes
Scanning Type scratch.A
javax.lang.model.type.MirroredTypeException: Attempt to access Class object for TypeMirror java.lang.Runnable
So we have to find another way to get the value, and there are two available to us. The first is not to use getAnnotation() but getAnnotationMirrors(), and the second is a neat trick with MirroredTypeException.
Solution 1 use getAnnotationMirrors()
This solution is a little long winded but is the most reliable. When getAnnotationMirrors() is used, it returns a set of AnnotationMirror instances, one for each annotation on that Element, so the first step is to locate the correct AnnotationMirror for the annotation you require. The next step is to extract the AnnotationValue’s from that mirror which represents the values stored in the annotation. This is held in a map keyed by an ExecutableElement.
Why ExecutableElement? Well it’s because the annotation values are actually defined as methods - hence why in our Action value is defined as value().
So in the next example we run through the AnnotationMirrors on a method until we find the one for our annotation then run through until we find the required value.
Once we have the AnnotationValue we simply print it to System.out but normally you would use the getValue() method which returns the value as an Object. If the value is an array it returns a java.util.List containing the values. Oh and if the values are of type Class then it returns a TypeMirror or a List of TypeMirrors.
Element actionElement = processingEnv.getElementUtils().getTypeElement(
Action.class.getName() );
TypeMirror actionType = actionElement.asType();
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
ExecutableElement oe = ee;
AnnotationValue action = null;
while( action == null && oe != null )
{
for( AnnotationMirror am : oe.getAnnotationMirrors() )
{
if( am.getAnnotationType().equals( actionType ) )
{
for( Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : am.getElementValues().entrySet() )
{
if( "value".equals(
entry.getKey().getSimpleName().toString() ) )
{
action = entry.getValue();
break;
}
}
}
}
// Look for the overridden method
oe = getExecutableElement(
findEnclosingTypeElement( oe ),
ee.getSimpleName() );
}
System.out.printf(
"%s Action value = %s\n",
ee.getSimpleName(),
action == null ? null : action );
}
Now at first that appears to work, and in most use cases it does - if we have a method thats overridden then we get the annotation values from the overridden method.
However, although its not obvious, if the super type is not part of the same CompilationUnit - i.e. it’s in a third party jar or from a previous call to javac then it will not find anything outside of that CompilationUnit.
The trouble with TypeMirrors
Now the cause on why the solution above fails isn’t obvious. The problem here is actually down to the TypeMirror’s. In the above example we get a TypeMirror for the annotation called actionType then search the AnnotationMirror set of each element using that TypeMirror.
Now TypeMirror acts in a similar way to how Class works at runtime. At run time Class is equal if it’s in the same ClassLoader, so here TypeMirror is equal if it’s in the same CompilationUnit. So the example above fails because they are different instances.
So the solution here is not to use TypeMirror.equals() but to convert the TypeMirror into a String representing the fully qualified class name and use equals() on that String. Now, no matter what source the super type comes from, it will always match.
Here’s the new version:
final String actionName = Contract.class.getName();
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
ExecutableElement oe = ee;
AnnotationValue action = null;
while( action == null && oe != null )
{
for( AnnotationMirror am : oe.getAnnotationMirrors() )
{
if( actionName.equals(
am.getAnnotationType().toString() ) )
{
for( Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : am.getElementValues().entrySet() )
{
if( "value".equals(
entry.getKey().getSimpleName().toString() ) )
{
action = entry.getValue();
break;
}
}
}
}
// Look for the overridden method
oe = getExecutableElement(
findEnclosingTypeElement( oe ),
ee.getSimpleName() );
}
System.out.printf(
"%s Action value = %s\n",
ee.getSimpleName(),
action == null ? null : action );
}
Now that one works. The lesson here is to use the String version of TypeElement when searching as two TypeElement’s representing the same class are not always equal.
Solution 2 - Single Class values
Now if your value contains just one Class (i.e. not Class[] ) then there’s a much simpler solution. This one isn’t that obvious, but I found that someone had a similar problem in the sun forums[1]. There the trick is to actually use getAnnotation() and catch the MirroredTypeException. Surprisingly the exception then provides the TypeMirror of the required class:
for( ExecutableElement ee : ElementFilter.methodsIn(
te.getEnclosedElements() ) )
{
Action action = ee.getAnnotation( Action.class );
if( action == null )
{
// Look for the overridden method
ExecutableElement oe = getExecutableElement( te,
ee.getSimpleName() );
if( oe != null )
{
action = oe.getAnnotation( Action.class );
}
}
TypeMirror value = null;
if( action != null )
{
try
{
action.value();
}
catch( MirroredTypeException mte )
{
value = mte.getTypeMirror();
}
}
System.out.printf(
"%s Action value = %s\n",
ee.getSimpleName(),
value );
}
Notice getTypeMirror() method call? Here’s the output of the above loop:
[compiler:compile]
Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes
Scanning Type scratch.A
run Action value = java.lang.Runnable
Scanning Type scratch.B
run Action value = java.lang.Runnable
This trick works fine for individual classes, but sadly it does not work for Class[] arrays. According to the javadocs it should work for Class[] as it should then throw the MirroredTypesException instead and that exception contains an alternate method that returns a List of TypeMirrors.
However it doesn’t - it simply throws MirroredTypeException for the first element in the array. I think it’s where it’s running through the array to populate it and the first element is then throwing MirroredTypeException before it gets chance to throw MirroredTypesException.
Conclusion
Well, hopefully this article will save someone hours of trouble when they hit the same problem. I’ve spent about 20 hours of time searching the net and dabbling for these solutions - and at least these solutions use just the documented public APIs.
References
