原文地址:http://hannesdorfmann.com/annotation-processing/annotationprocessing101
In this blog entry I would like to explain how to write an annotation processor. So here is my tutorial. First, I am going to explain to you what annotation processing is, what you can do with that powerful tool and finally what you cannot do with it. In a second step we will implement a simple annotation processor step by step.
The Basics
To clarify a very important thing from the very beginning: we are not talking about evaluating annotations by using reflections at runtime (run time = the time when the application runs). Annotation processing takes place at compile time (compile time = the time when the java compiler compiles your java source code).
Annotation processing is a tool build in javac for scanning and processing annotations at compile time. You can register your own annotation processor for certain annotations. At this point I assume that you already know what an annotation is and how to declare an annotation type. If you are not familar with annotations you can find more information in theofficial java documentation. Annotation processing is already available since Java 5 but a useable API is available since Java 6 (released in December 2006). It took some time until the java world realized the power of annotation processing. So it has become popular in the last few years.
An annotation processor for a certain annotation takes java code (or compiled byte code) as input and generate files (usually .java files) as output. What does that exactly means? You can generate java code! The generated java code is in a generated .java
file. So you can notmanipulate an existing java class for instance adding a method. The generated java file will be compiled by javac as any other hand written java source file.
AbstractProcessor
Let’s have a look at the Processor API. Every Processor extends from AbstractProcessor
as follows:
package com.example;
public class MyProcessor extends AbstractProcessor {
@Override
public synchronized void init(ProcessingEnvironment env){ }
@Override
public boolean process(Set<? extends TypeElement> annoations, RoundEnvironment env) { }
@Override
public Set<String> getSupportedAnnotationTypes() { }
@Override
public SourceVersion getSupportedSourceVersion() { }
}
init(ProcessingEnvironment env)
: Every annotation processor class must have an empty constructor. However, there is a special init() method which is invoked by the annotation processing tool with theProcessingEnviroment
as parameter. The ProcessingEnviroment provides some useful util classesElements
,Types
andFiler
. We will use them later.process(Set<? extends TypeElement> annotations, RoundEnvironment env)
: This is kind ofmain()
method of each processor. Here you write your code for scanning, evaluating and processing annotations and generating java files. WithRoundEnviroment
passed as parameter you can query for elements annotated with a certain annotation as we will see later.getSupportedAnnotationTypes()
: Here you have to specify for which annotations this annotation processor should be registered for. Note that the return type is a set of strings containing full qualified names for your annotation types you want to process with this annotation processor. In other words, you define here for which annotations you register your annotation processor.getSupportedSourceVersion()
: Used to specify which java version you use. Usually you will returnSourceVersion.latestSupported()
. However, you could also returnSourceVersion.RELEASE_6
if you have good reasons for stick with Java 6. I recommend to useSourceVersion.latestSupported();
With Java 7 you could also use annotations instead of overriding getSupportedAnnotationTypes()
and getSupportedSourceVersion()
like that:
@SupportedSourceVersion(SourceVersion.latestSupported())
@SupportedAnnotationTypes({
// Set of full qullified annotation type names
})
public class MyProcessor extends AbstractProcessor {
@Override
public synchronized void init(ProcessingEnvironment env){ }
@Override
public boolean process(Set<? extends TypeElement> annoations, RoundEnvironment env) { }
}
For compatibility reasons, especially for android, I recommend to overridegetSupportedAnnotationTypes()
and getSupportedSourceVersion()
instead of using@SupportedAnnotationTypes
and @SupportedSourceVersion
The next thing you have to know is that the annotation processor runs in it’s own jvm. Yes you read correctly. javac starts a complete java virtual machine for running annotation processors. So what that means for you? You can use anything you would use in any other java application. Use guava! If you want to you can use dependency injection tools like dagger or any other library you want to. But don’t forget. Even if it’s just a small processor you should take care about efficient algorithms and design patterns like you would do for any other java application.
Register Your Processor
You may ask yourself “How do I register MyProcessor to javac?”. You have to provide a .jar
file. Like any other .jar file you pack your (compiled) annotation processor in that file. Furthermore you also have to pack a special file called javax.annotation.processing.Processor
located in META-INF/services
in your .jar file. So the content of your .jar file looks like this:
MyProcessor.jar
- com
- example
- MyProcessor.class
- META-INF
- services
- javax.annotation.processing.Processor
The content of the file javax.annotation.processing.Processor
(packed in MyProcessor.jar) is a list with full qualified class names to the processors with new line as delimiter:
com.example.MyProcessor
com.foo.OtherProcessor
net.blabla.SpecialProcessor
With MyProcessor.jar
in your buildpath javac automatically detects and reads thejavax.annotation.processing.Processor
file and registers MyProcessor
as annotation processor.
Example: Factory Pattern
It’s time to for a concrete example. We will use maven as our build system and dependency management tool. If you are not familiar with maven, don’t worry maven is not necessary. The whole code can be found on github.
First of all I have to say, that it’s not so easy to find a simple problem for a tutorial that we can solve with an annotation processor. Here we gonna implement a very simple factory pattern (not abstract factory pattern). It should give you just a brief introduction on the annotation processing API. So the problem statement may be a little bit dump and not a real world one. Once again, you will learn about annotation processing and not about design patterns.
So here is the problem: We want to implement a pizza store. The pizza store offers to it’s customers 2 Pizzas (“Margherita” and “Calzone”) and Tiramisu for dessert.
Have a look at this code snippets, which should not need any further explanation:
public interface Meal {
public float getPrice();
}
public class MargheritaPizza implements Meal {
@Override public float getPrice() {
return 6.0f;
}
}
public class CalzonePizza implements Meal {
@Override public float getPrice() {
return 8.5f;
}
}
public class Tiramisu implements Meal {
@Override public float getPrice() {
return 4.5f;
}
}
To order in our PizzaStore
the customer has to enter the name of the meal:
public class PizzaStore {
public Meal order(String mealName) {
if (mealName == null) {
throw new IllegalArgumentException("Name of the meal is null!");
}
if ("Margherita".equals(mealName)) {
return new MargheritaPizza();
}
if ("Calzone".equals(mealName)) {
return new CalzonePizza();
}
if ("Tiramisu".equals(mealName)) {
return new Tiramisu();
}
throw new IllegalArgumentException("Unknown meal '" + mealName + "'");
}
public static void main(String[] args) throws IOException {
PizzaStore pizzaStore = new PizzaStore();
Meal meal = pizzaStore.order(readConsole());
System.out.println("Bill: $" + meal.getPrice());
}
}
As you see, we have a lot of if statements in the order()
method and whenever we add a new type of pizza we have to add a new if statement. But wait, with annotation processing and the factory pattern we can let an annotation processor generate this if statements. So what we want to have is something like that:
public class PizzaStore {
private MealFactory factory = new MealFactory();
public Meal order(String mealName) {
return factory.create(mealName);
}
public static void main(String[] args) throws IOException {
PizzaStore pizzaStore = new PizzaStore();
Meal meal = pizzaStore.order(readConsole());
System.out.println("Bill: $" + meal.getPrice());
}
}
The MealFactory
should look as follows:
public class MealFactory {
public Meal create(String id) {
if (id == null) {
throw new IllegalArgumentException("id is null!");
}
if ("Calzone".equals(id)) {
return new CalzonePizza();
}
if ("Tiramisu".equals(id)) {
return new Tiramisu();
}
if ("Margherita".equals(id)) {
return new MargheritaPizza();
}
throw new IllegalArgumentException("Unknown id = " + id);
}
}
@Factory Annotation
Guess what: We want to generate the MealFactory
by using annotation processing. To be more general, we want to provide an annotation and a processor for generating factory classes.
Let’s have a look at the @Factory
annotation:
@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS)
public @interface Factory {
/**
* The name of the factory
*/
Class type();
/**
* The identifier for determining which item should be instantiated
*/
String id();
}
The idea is that we annotate classes which should belong to the same factory with the sametype()
and with id()
we do the mapping from "Calzone"
to CalzonePizza
class. Let’s apply@Factory
to our classes:
@Factory(
id = "Margherita",
type = Meal.class
)
public class MargheritaPizza implements Meal {
@Override public float getPrice() {
return 6f;
}
}
@Factory(
id = "Calzone",
type = Meal.class
)
public class CalzonePizza implements Meal {
@Override public float getPrice() {
return 8.5f;
}
}
@Factory(
id = "Tiramisu",
type = Meal.class
)
public class Tiramisu implements Meal {
@Override public float getPrice() {
return 4.5f;
}
}
You may ask yourself if we could just apply @Factory
on the Meal
interface. Annotations are not inherited. Annotating class X
with an annotation does not mean that class Y extends X
is automatically annotated. Before we start writing the processor code we have to specify some rules:
- Only classes can be annotated with
@Factory
since interfaces or abstract classes can not be instantiated with thenew
operator. - Classes annotated with
@Factory
must provide at least one public empty default constructor (parameterless). Otherwise we could not instantiate a new instance. - Classes annotated with
@Factory
must inherit directly or indirectly from the specifiedtype
(or implement it if it’s an interface). @Factory
annotations with the sametype
are grouped together and one Factory class will be generated. The name of the generated class has “Factory” as suffix, for exampletype = Meal.class
will generateMealFactory
id
are limited to Strings and must be unique in it’s type group.
The Processor
I will guide you step by step by adding line of code followed by an explanation paragraph. Three dots (...
) means that code is omitted either was discussed in the paragraph before or will be added later as next step. Goal is to make the snipped more readable. As already mentioned above the complete code can be found on github. Ok lets start with the skeleton of our FactoryProcessor
:
@AutoService(Processor.class)
public class FactoryProcessor extends AbstractProcessor {
private Types typeUtils;
private Elements elementUtils;
private Filer filer;
private Messager messager;
private Map<String, FactoryGroupedClasses> factoryClasses = new LinkedHashMap<String, FactoryGroupedClasses>();
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
typeUtils = processingEnv.getTypeUtils();
elementUtils = processingEnv.getElementUtils();
filer = processingEnv.getFiler();
messager = processingEnv.getMessager();
}
@Override
public Set<String> getSupportedAnnotationTypes() {
Set<String> annotataions = new LinkedHashSet<String>();
annotataions.add(Factory.class.getCanonicalName());
return annotataions;
}
@Override
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.latestSupported();
}
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
...
}
}
In the first line you see @AutoService(Processor.class)
. What’s that? It’s an annotation from another annotation processor. This AutoService
annotation processor has been developed by Google and generates the META-INF/services/javax.annotation.processing.Processor
file. Yes, you read correctly. We can use annotation processors in our annotation processor. Handy, isn’t it? In getSupportedAnnotationTypes()
we specify that @Factory
is processed by this processor.
Elements and TypeMirrors
In init()
we retrieve a reference to
- Elements: A utils class to work with
Element
classes (more information later). - Types: A utils class to work with
TypeMirror
(more information later) - Filer: Like the name suggests with Filer you can create files.
In annotation processing we are scanning java source code files. Every part of the source code is a certain type of Element
. In other words: Element
represents a program element such as a package, class, or method. Each element represents a static, language-level construct. In the following example I have added comments to clarify that:
package com.example; // PackageElement
public class Foo { // TypeElement
private int a; // VariableElement
private Foo other; // VariableElement
public Foo () {} // ExecuteableElement
public void setA ( // ExecuteableElement
int newA // TypeElement
) {}
}
You have to change the way you see source code. It’s just structured text. It’s not executable. You can think of it like a XML file you try to parse (or an abstract syntax tree in compiler construction). Like in XML parsers there is some kind of DOM with elements. You can navigate from Element to it’s parent or child Element.
For instance if you have a TypeElement
representing public class Foo
you could iterate over its children like that:
TypeElement fooClass = ... ;
for (Element e : fooClass.getEnclosedElements()){ // iterate over children
Element parent = e.getEnclosingElement(); // parent == fooClass
}
As you see Elements are representing source code. TypeElement represent type elements in the source code like classes. However, TypeElement does not contain information about the class itself. From TypeElement you will get the name of the class, but you will not get information about the class like the superclass. This is kind of information are accessible through a TypeMirror
. You can access the TypeMirror of an Element by calling element.asType()
.
Searching For @Factory
So lets implement the process()
method step by step. First we start with searching for classes annotated with @Factory
:
@AutoService(Processor.class)
public class FactoryProcessor extends AbstractProcessor {
private Types typeUtils;
private Elements elementUtils;
private Filer filer;
private Messager messager;
private Map<String, FactoryGroupedClasses> factoryClasses = new LinkedHashMap<String, FactoryGroupedClasses>();
...
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
// Itearate over all @Factory annotated elements
for (Element annotatedElement : roundEnv.getElementsAnnotatedWith(Factory.class)) {
...
}
}
...
}
No rocket science here. roundEnv.getElementsAnnotatedWith(Factory.class))
returnes a list of Elements annotated with @Factory
. You may have noted that I have avoited saying “returns list of classes annotated with @Factory”, because it really returns list of Element
. Remember:Element
can be a class, method, variable etc. So what we have to do next is to check if the Element is a class:
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
for (Element annotatedElement : roundEnv.getElementsAnnotatedWith(Factory.class)) {
// Check if a class has been annotated with @Factory
if (annotatedElement.getKind() != ElementKind.CLASS) {
...
}
}
...
}
What’s going on here? We want to ensure that only elements of type class are processed by our processor. Previously we have learned that classes are TypeElements
. So why don’t we check if (! (annotatedElement instanceof TypeElement) )
. That’s a wrong assumption because interfaces are TypeElement as well. So in annoation processing you should avoid instanceofbut rather us ElementKind or TypeKind with TypeMirror.
Error Handling
In init()
we also retrieve a reference to Messager
. A Messager provides the way for an annotation processor to report error messages, warnings and other notices. It’s not a logger for you, the developer of the annotation processor (even thought it can be used for that during development of the processor). Messager is used to write messages to the third party developer who uses your annotation processor in their projects. There are different levels of messages described in the official docs. Very important is Kind.ERROR because this kind of message is used to indicate that our annotation processor has failed processing. Probably the third party developer is misusing our @Factory
annotation (i.e. annotated an interface with @Factory). The concept is a little bit different from traditional java application where you would throw an Exception
. If you throw an exception in process()
then the jvm which runs annotation processing crashs (like any other java application) and the third party developer who is using our FactoryProcessor will get an error from javac with a hardly understandable Exception, because it contains the stacktrace of FactoryProcessor. Therefore Annotation Processor has this Messager
class. It prints a pretty error message. Additionaly, you can link to the element who has raised this error. In modern IDEs like IntelliJ the third party developer can click on this error message and the IDE will jump to the source file and line of the third party developers project where the error source is.
Back to implementing the process()
method. We raise a error message if the user has annotated a non class with @Factory:
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
for (Element annotatedElement : roundEnv.getElementsAnnotatedWith(Factory.class)) {
// Check if a class has been annotated with @Factory
if (annotatedElement.getKind() != ElementKind.CLASS) {
error(annotatedElement, "Only classes can be annotated with @%s",
Factory.class.getSimpleName());
return true; // Exit processing
}
...
}
private void error(Element e, String msg, Object... args) {
messager.printMessage(
Diagnostic.Kind.ERROR,
String.format(msg, args),
e);
}
}
To get the message of the Messager displayed it’s important that the annotation processor has to complete without crashing. That’s why we return
after having callederror()
. If we don’t return here process()
will continue running since messager.printMessage( Diagnostic.Kind.ERROR)
does not stop the process. So it’s very likely that if we don’t return after printing the error we will run in an internal NullPointerException etc. if we continue inprocess()
. As said before, the problem is that if an unhandled exception is thrown in process()
javac will print the stacktrace of the internal NullPointerException and NOT your error message of Messager
.
Datamodel
Before we continue with checking if classes annotated with @Factory observe our five rules (see above) we are going to introduce data structures which makes it easier for us to continue. Sometimes the problem or processor seems to be so simple that programmers tend to write the whole processor in a procedural manner. But you know what? An Annotation Processor is still a java application. So use object oriented programming, interfaces, design patterns and anything else you would use in any other java application!
Our FactoryProcessor is quite simple but there are some information we want to store as objects. With FactoryAnnotatedClass
we store the annotated class data like qualified class name along with the data of the @Factory annotation itself. So we store the TypeElement and evaluate the @Factory annotation:
public class FactoryAnnotatedClass {
private TypeElement annotatedClassElement;
private String qualifiedSuperClassName;
private String simpleTypeName;
private String id;
public FactoryAnnotatedClass(TypeElement classElement) throws IllegalArgumentException {
this.annotatedClassElement = classElement;
Factory annotation = classElement.getAnnotation(Factory.class);
id = annotation.id();
if (StringUtils.isEmpty(id)) {
throw new IllegalArgumentException(
String.format("id() in @%s for class %s is null or empty! that's not allowed",
Factory.class.getSimpleName(), classElement.getQualifiedName().toString()));
}
// Get the full QualifiedTypeName
try {
Class<?> clazz = annotation.type();
qualifiedSuperClassName = clazz.getCanonicalName();
simpleTypeName = clazz.getSimpleName();
} catch (MirroredTypeException mte) {
DeclaredType classTypeMirror = (DeclaredType) mte.getTypeMirror();
TypeElement classTypeElement = (TypeElement) classTypeMirror.asElement();
qualifiedSuperClassName = classTypeElement.getQualifiedName().toString();
simpleTypeName = classTypeElement.getSimpleName().toString();
}
}
/**
* Get the id as specified in {@link Factory#id()}.
* return the id
*/
public String getId() {
return id;
}
/**
* Get the full qualified name of the type specified in {@link Factory#type()}.
*
* @return qualified name
*/
public String getQualifiedFactoryGroupName() {
return qualifiedSuperClassName;
}
/**
* Get the simple name of the type specified in {@link Factory#type()}.
*
* @return qualified name
*/
public String getSimpleFactoryGroupName() {
return simpleTypeName;
}
/**
* The original element that was annotated with @Factory
*/
public TypeElement getTypeElement() {
return annotatedClassElement;
}
}
Lot of code, but the most important thing happens ins the constructor where you find the following lines of code:
Factory annotation = classElement.getAnnotation(Factory.class);
id = annotation.id(); // Read the id value (like "Calzone" or "Tiramisu")
if (StringUtils.isEmpty(id)) {
throw new IllegalArgumentException(
String.format("id() in @%s for class %s is null or empty! that's not allowed",
Factory.class.getSimpleName(), classElement.getQualifiedName().toString()));
}
Here we access the @Factory annotation and check if the id is not empty. We will throw an IllegalArgumentException if id is empty. You may be confused now because previously we said that we are not throwing exceptions but rather use Messager
. That’s still correct. We throw an exception here internally and we will catch that one in process()
as you will see later. We do that for two reasons:
- I want to demonstrate that you should still code like in any other java application. Throwing and catching exceptions is considered as good practice in java.
- If we want to print a message right from
FactoryAnnotatedClass
we also have to pass theMessager
and as already mentioned in “Error Handling” (scroll up) the processor has to terminate successfully to makeMessager
print the error message. So if we would write an error message by usingMessager
how do we “notify”process()
that an error has occurred? The easiest and from my point of view most intuitive way is to throw an Exception and letprocess()
chatch this one.
Next we want to get the type
field of the @Factory
annotation. We are interessted in the full qualified name.
try {
Class<?> clazz = annotation.type();
qualifiedGroupClassName = clazz.getCanonicalName();
simpleFactoryGroupName = clazz.getSimpleName();
} catch (MirroredTypeException mte) {
DeclaredType classTypeMirror = (DeclaredType) mte.getTypeMirror();
TypeElement classTypeElement = (TypeElement) classTypeMirror.asElement();
qualifiedGroupClassName = classTypeElement.getQualifiedName().toString();
simpleFactoryGroupName = classTypeElement.getSimpleName().toString();
}
That’s a little bit tricky, because the type is java.lang.Class
. That means, that this is a real Class object. Since annotation processing runs before compiling java source code we have to consider two cases:
- The class is already compiled: This is the case if a third party .jar contains compiled .class files with
@Factory
annotations. In that case we can directly access the Class like we do in thetry-block
. - The class is not compiled yet: This will be the case if we try to compile our source code which has @Factory annotations. Trying to access the Class directly throws a
MirroredTypeException
. Fortunately MirroredTypeException contains aTypeMirror
representation of our not yet compiled class. Since we know that it must be type of class (we have already checked that before) we can cast it toDeclaredType
and accessTypeElement
to read the qualified name.
Alright, now we need one more datastructure named FactoryGroupedClasses
which basically groups all FactoryAnnotatedClasses
together.
public class FactoryGroupedClasses {
private String qualifiedClassName;
private Map<String, FactoryAnnotatedClass> itemsMap =
new LinkedHashMap<String, FactoryAnnotatedClass>();
public FactoryGroupedClasses(String qualifiedClassName) {
this.qualifiedClassName = qualifiedClassName;
}
public void add(FactoryAnnotatedClass toInsert) throws IdAlreadyUsedException {
FactoryAnnotatedClass existing = itemsMap.get(toInsert.getId());
if (existing != null) {
throw new IdAlreadyUsedException(existing);
}
itemsMap.put(toInsert.getId(), toInsert);
}
public void generateCode(Elements elementUtils, Filer filer) throws IOException {
...
}
}
As you see it’s basically just a Map<String, FactoryAnnotatedClass>
. This map is used to map an @Factory.id() to FactoryAnnotatedClass. We have chosen Map
because we want to ensure that each id is unique. That can be easily done with a map lookup. generateCode()
will be called to generate the Factory code (discussed later).
Matching Criteria
Let’s proceed with the implementation of process()
. Next we want to check if the annotated class has at least one public constructor, is not an abstract class, inherits the specified type and is a public class (visibility):
public class FactoryProcessor extends AbstractProcessor {
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
for (Element annotatedElement : roundEnv.getElementsAnnotatedWith(Factory.class)) {
...
// We can cast it, because we know that it of ElementKind.CLASS
TypeElement typeElement = (TypeElement) annotatedElement;
try {
FactoryAnnotatedClass annotatedClass =
new FactoryAnnotatedClass(typeElement); // throws IllegalArgumentException
if (!isValidClass(annotatedClass)) {
return true; // Error message printed, exit processing
}
} catch (IllegalArgumentException e) {
// @Factory.id() is empty
error(typeElement, e.getMessage());
return true;
}
...
}
private boolean isValidClass(FactoryAnnotatedClass item) {
// Cast to TypeElement, has more type specific methods
TypeElement classElement = item.getTypeElement();
if (!classElement.getModifiers().contains(Modifier.PUBLIC)) {
error(classElement, "The class %s is not public.",
classElement.getQualifiedName().toString());
return false;
}
// Check if it's an abstract class
if (classElement.getModifiers().contains(Modifier.ABSTRACT)) {
error(classElement, "The class %s is abstract. You can't annotate abstract classes with @%",
classElement.getQualifiedName().toString(), Factory.class.getSimpleName());
return false;
}
// Check inheritance: Class must be childclass as specified in @Factory.type();
TypeElement superClassElement =
elementUtils.getTypeElement(item.getQualifiedFactoryGroupName());
if (superClassElement.getKind() == ElementKind.INTERFACE) {
// Check interface implemented
if (!classElement.getInterfaces().contains(superClassElement.asType())) {
error(classElement, "The class %s annotated with @%s must implement the interface %s",
classElement.getQualifiedName().toString(), Factory.class.getSimpleName(),
item.getQualifiedFactoryGroupName());
return false;
}
} else {
// Check subclassing
TypeElement currentClass = classElement