ANNOTATION PROCESSING

IN ANDROIDEmanuele Zattin - Realm

@emanuelez

19-2-2016 - DroidKaigi

DroidKaigi

WHAT IS A JAVA ANNOTATION?

LET'S START WITH THE OFFICIAL DEFINITION

Annotations, a form of metadata, provide data about a program that is not part of the program itself.

Annotations have no direct effect on the operation of the code they annotate.

— Oracle

WHAT CAN ANNOTATIONS DO?1. Provide information for the compiler

2. Allow runtime processing3. Allow compile-time processing

HOW TO DEFINE AN ANNOTATIONThe simplest annotation can be defined as:

public @interface MyAnnotation {}

and it can be used like this:@MyAnnotationpublic class MyClass {}

ANNOTATIONS CAN ACCEPT ARGUMENTS

public @interface MyAnnotation { String arg1(); int arg2 default 1; String[] arg3;}

Which can be used like this:@MyAnnotation ( arg1 = "value1", // It's a comma, not a semicolon arg3 = { "value2", "value3" } // Arrays use curly brackets)public class MyClass {}

ANNOTATIONS CAN BE ANNOTATEDThe most important is @Retention which value can

be:

▸ RetentionPolicy.SOURCE

▸ RetentionPolicy.CLASS

▸ RetentionPolicy.RUNTIME

ANNOTATIONS CAN BE ANNOTATED PART 2

The other important annotation is @Target which value:

ElementType.ANNOTATION_TYPE ElementType.CONSTRUCTOR

ElementType.FIELD ElementType.LOCAL_VARIABLE

ElementType.METHOD

ANNOTATIONS CAN BE ANNOTATED PART 3

Other useful annotations:

▸ @Documented

▸ @Inherited

▸ @Repeatable

AN EXAMPLE ANNOTATION@Retention(RetentionPolicy.CLASS) // Available at compile-time@Target(ElementType.TYPE) // Can only be applied to classes@interface MyAnnotation { String arg1(); int arg2 default 1; String[] arg3;}

WHAT IS AN ANNOTATION PROCESSOR?

Annotation Processing is a technique that providesa hook into the Java compile process.

It allows to produce compiler errors and warningsand to generate source code and byte code.

JSR 269

HOW DOES IT WORK?

Here's a high-level example:

1. Normal compilation2. First round of annotation processing

3. Second round of annotation processing4. ...

IMPLEMENTING A PROCESSORpublic abstract class AbstractProcessor implements Processor { // more methods here!

void init( ProcessingEnvironment processingEnv );

abstract boolean process( Set<? extends TypeElement> annotations, RoundEnvironment roundEnv );}

THE PROCESSING ENVIRONMENT

It provides the tools to write new files and access utility classes.

Here are the most useful methods:// Use Filer to write new filesFiler getFiler();

// Use Elements to manage fields, methods and classesElements getElementUtils();

// Use Types to deal with classes, converting Type to Element, ...Types getTypeUtils();

THE ROUND ENVIRONMENT

It provides tools to deal with the specific round.The most useful methods are:

// Get the elements annotated with a given annotationSet<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a);Set<? extends Element> getElementsAnnotatedWith(TypeElement a);

THE MOST USELESS ANNOTATIONpublic AnnoyingProcessor extends AbstractProcessor { boolean process( Set<> annotations, RoundEnvironment env) { Messager m = processingEnv.getMessager(); for (TypeElement te : annotations) { for (Element e : env.getElementsAnnotatedWith(te)) { m.printMessage(Diagnostic.Kind.NOTE, "Processing " + e.toString()); } } return true; }}

REGISTERING YOUR PROCESSOR

1. Package your processor in a Jar file2. The Jar file must contain a file called

javax.annotation.processing.Processor

located in META-INF/services3. This file must contain the fully

qualified name of your processor

GENERATING JAVA CODE IN YOUR AP

Enter JavaPoet

MethodSpec main = MethodSpec.methodBuilder("main") .addModifiers(Modifier.PUBLIC, Modifier.STATIC) .returns(void.class) .addParameter(String[].class, "args") .addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!") .build();

TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld") .addModifiers(Modifier.PUBLIC, Modifier.FINAL) .addMethod(main) .build();

JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld) .build();

javaFile.writeTo(processingEnv.getFiler());

TESTING

Testing annotations processors is hard because the execution happens at compile time

SOME MUCH NEEDED HELP!

Google's compile-testing library

EXAMPLE 1assert_() // it uses the Truth testing library .about(javaSource()) .that( JavaFileObjects.forSourceString( "HelloWorld", "final class HelloWorld {}" ) ).compilesWithoutError();

EXAMPLE 2assert_().about(javaSource()) .that(JavaFileObjects.forResource("HelloWorld.java")) .processedWith(new MyAnnotationProcessor()) .compilesWithoutError() .and() .generatesSources( JavaFileObjects.forResource("GeneratedHelloWorld.java"));

HOW ABOUT ANNOTATION

PROCESSING IN ANDROID?

PROBLEM 1

The Android framework does not includejavax.annotation.processing

SOLUTION

Setup your AP to be a Java moduleand to inform your users to use

the Gradle android-apt plugin by Hugo Visser

PROBLEM 2

Both your library and your AP might depend on the annotations

SOLUTION

Setup your annotations to be another Java moduleon which both the library and the AP depend on

PROBLEM 3

Now the Javadoc of your library does not include the annotations

SOLUTIONandroid.libraryVariants.all { variant -> task("javadoc${variant.name.capitalize()}", type: Javadoc) { description "Generates Javadoc for $variant.name." group 'Docs' source = variant.javaCompile.source source "../annotations/src/main/java" // <-- THIS! ext.androidJar = files(project.android.getBootClasspath()) classpath = files(variant.javaCompile.classpath.files) + ext.androidJar exclude '**/BuildConfig.java' exclude '**/R.java' }}

ANDROID LIBRARIES THAT USE AP

▸ ButterKnife▸ Dagger▸ Parceler▸ Realm

Thank you!

Questions?