Building and use custom annotations at runtime and compile-time.

1. Annotation Processing -
Demystifying Java's Dark Arts
by Jim Kirkbride

2. Why am I giving this
talk?
@jameskbride

3. @jameskbride

4. //Usage
@ApplyMagicHere
public void doSomething() {
}
@jameskbride

5. Annotations by
themselves are just
metadata.
@jameskbride

6. … so why use them?
@jameskbride

7. Retrofit
JUnit
Dagger
Spring
Hibernate EventBus
Lombok
TestNG
Java
Cross-cutting
Concerns
Reduce
Boilerplate
Introduce Functionality
via Meta-programming
@jameskbride

8. First steps with
Custom Annotations @jameskbride

9. @Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD})
public @interface ApplyMagicHere {
String value() default "";
}
Tells the compiler whether
or not to discard the annotation. What elements can the
annotation be applied to?
Required,
because magic.
Default parameter
name
Default parameter
value
@jameskbride

10. How Do We Process
Annotations?
@jameskbride

11. Reflection at runtime
@jameskbride

12. At compile-time via
AbstractProcessor
@jameskbride

13. @AutoService(Processor.class)
public class ExampleAnnotationProcessor extends AbstractProcessor {
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
}
@Override
public Set<String> getSupportedAnnotationTypes() {
return Sets.newHashSet(
Annotation1.class.getCanonicalName(),
Annotation2.class.getCanonicalName()
);
}
@Override
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.latest();
}
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
return false;
}
}
Access
utility classes
Create required file
META-INF/services/javax.annotation.processing.Processor
Work gets done here
List of Supported
Annotations
Latest supported
source version
Required
base class
@jameskbride

14. Compile
Time
Processor Life-Cycle
Register
Processor
Annotations
processed
in rounds
A processor
processes
annotations and
generates code
Repeat per
processor
Compile the rest of
the code
@jameskbride

15. @AutoService(Processor.class)
public class ExampleAnnotationProcessor extends AbstractProcessor {
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
// for all annotations to be processed:
// 1. Find elements for a given annotation to be processed
// 2. Perform validation (produce compiler errors, warnings, etc)
// 3. Process
// Finally, generate/write code
return true; //Claim all annotations in this round
}
}
Processing Steps
@jameskbride

16. Lets Build Our Own Retrofit
@jameskbride

17. @Base("http://localhost:1080")
public interface ExampleApi {
@GET("/")
Call<SomeObject> getSomeObject();
}
Our
Annotation
Our
Annotation
@jameskbride

18. ExampleApi exampleApi = new ExampleApiProxy();
Call<SomeObject> call = exampleApi.getSomeObject();
call.enqueue(new Callback<SomeObject>() {
@Override
public void onFailure(okhttp3.Call call, IOException e) {
//Do something
}
@Override
public void onResponse(okhttp3.Call call, Response<SomeObject> response)
throws IOException {
//Do something else
}
});
@jameskbride

19. Generating Code with JavaPoet
@jameskbride

20. TypeSpec.classBuilder(/* class/interface name */)
.addSuperinterface(/* interface name */)
.addModifiers(/* array of modifiers */)
.addField(/* FieldSpec */)
.addMethod(/* First MethodSpec */)
.addMethod(/* ...nth MethodSpec */)
.build();
Generate a Class
@jameskbride

21. MethodSpec
.methodBuilder(/* Method name */)
.addModifiers(/* Array of modifiers */)
.returns(/* return TypeName */)
.addCode(/* CodeBlock */)
.build()
Generate a Method
@jameskbride

22. CodeBlock.builder()
.addStatement("$T callFactory = new $T(client, $T.class)",
CallFactory.class,
callType,
ClassName.bestGuess(returnTypeParam.toString()))
.addStatement("return callFactory.make("$L", "$L")",
baseUrl, path)
.build()
Generating a CodeBlock
@jameskbride

23. JavaFile javaFile =
JavaFile
.builder("com.jameskbride", /* TypeSpec */)
.build();
try {
javaFile.writeTo(filer);
} catch (IOException e) {
e.printStackTrace();
}
Write the Java File
@jameskbride

24. Questions?
@jameskbride

25. • The Alchemist by William Fettes Douglas - https://commons.wikimedia.org/wiki/File:William_Fettes_Douglas_-
_The_Alchemist.jpg
• Alchemist’s Laboratory, 1595 - https://commons.wikimedia.org/wiki/File:Amphitheatrum_sapientiae_aeternae_-
_Alchemist%27s_Laboratory.jpg
• Medical miscellany, anatomical illustration showing the veins. Circa 1292 - https://commons.wikimedia.org/wiki/File:
13th_century_anatomical_illustration.jpg
• Anatomy lesson of Dr. Willem van der Meer by Unknown, 1617 - https://commons.wikimedia.org/wiki/
File:Michiel_Jansz_van_Mierevelt_-_Anatomy_lesson_of_Dr._Willem_van_der_Meer.jpg
• An Experiment on a Bird in an Air Pump by Joseph Wright of Derby, 1768 - https://commons.wikimedia.org/wiki/
File:An_Experiment_on_a_Bird_in_an_Air_Pump_by_Joseph_Wright_of_Derby,_1768.jpg
• Louis Pasteur, 1885 - https://commons.wikimedia.org/wiki/File:Albert_Edelfelt_-_Louis_Pasteur_-_1885.jpg
• Anatomy High-tech - http://www.publicdomainpictures.net/view-image.php?image=42723
References
@jameskbride

26. • Demo project: https://github.com/jameskbride/
annotations-demo
• Processor documentation: https://docs.oracle.com/
javase/7/docs/api/javax/annotation/processing/
Processor.html
• Annotation Documentation: https://docs.oracle.com/
javase/tutorial/java/annotations/index.html
• JavaPoet - https://github.com/square/javapoet
Resources
@jameskbride

27. • james.kirkbride@gmail.com
• github.com/jameskbride
• twitter.com/jameskbride
Thanks!
@jameskbride