Question? Leave a message!




Annotation Processing

Annotation Processing 17
Annotation Processing Angelika Langer Trainer/Consultant http://www.AngelikaLanger.comgoal • give an overview of annotation processing – what are annotations • meta information – how are they defined • language features since JDK 5.0 – how are they processed • on the source code level • (on the byte code level) • (at runtime via reflection) © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 2 last update: 4/16/2008 ,12:42speaker's qualifications • independent trainer / consultant / author – teaching C++ and Java for 10+ years – curriculum of a dozen challenging courses – coauthor of "Effective Java" column in JavaSpektrum – author of Java Generics FAQ online – Java champion since 2005 © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 3 last update: 4/16/2008 ,12:42agenda • annotation language features • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 4 last update: 4/16/2008 ,12:42program annotation facility • allows developers – to define custom annotation types –to annotate fields, methods, classes, etc. with annotations corresponding to these types • allow tools to read and process the annotations – no direct effect on semantics of a program – e.g. tool can produce additional Java source files or XML documents related to the annotated program © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 5 last update: 4/16/2008 ,12:42sample usage • annotated class Copyright("2008 Vibro Systems, Ltd.") public class OscillationOverthruster ... • corresponding definition of annotation type public interface Copyright String value(); • reading an annotation via reflection String copyrightHolder = OscillationOverthruster.class. getAnnotation(Copyright.class).value(); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 6 last update: 4/16/2008 ,12:42retention • it makes little sense to retain all annotations at run time – would increase runtime memoryfootprint • annotations can have different lifetime: SOURCE: • discarded after compilation CLASS: • recorded in the class file as signature attributes • not retained until run time RUNTIME: • recorded in the class file and retained by the VM at run time • may be read reflectively © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 7 last update: 4/16/2008 ,12:42agenda • annotation language features – declaring annotation types – annotating program elements – meta annotations • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 8 last update: 4/16/2008 ,12:42annotation type • every annotation has an annotation type – takes the form of a highly restricted interface declaration – new "keyword" interface –a default value may be specified for an annotation type member – permitted return types include primitive types, String, Class public interface RequestForEnhancement int id(); String synopsis(); String engineer() default "unassigned"; String date() default "unimplemented"; s © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 9 last update: 4/16/2008 ,12:42using annotation types RequestForEnhancement( id = 28, synopsis = "Provide timetravel functionality", engineer = "Mr. Peabody", date = "12/24/2008" ) public static void travelThroughTime(Date destination) ... • members with a default may be omitted RequestForEnhancement( id = 45, synopsis = "Add extension as per request 392" ) public static void balanceFederalBudget() throw new UnsupportedOperationException("Not implemented"); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 10 last update: 4/16/2008 ,12:42marker annotations • annotation types can have no members –called marker annotations public interface Immutable • sample usage Immutable public class String ... © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 11 last update: 4/16/2008 ,12:42agenda • annotation language features – declaring annotation types – annotating program elements – meta annotations • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 12 last update: 4/16/2008 ,12:42annotatable program elements • annotations may be used as modifiers in the declaration of: – package, class, interface, field, method, parameter, constructor, local variable, enum type, enum constant, annotation type public interface Copyright String value(); public interface Default Copyright("2004 Angelika Langer") public enum Color RED, BLUE, GREEN, Default NOCOLOR © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 13 last update: 4/16/2008 ,12:42more annotated types • JSR 308 (in Java 7.0) allows annotations as type qualifiers (on any use of a type) •type MapNonNull String, NonEmpty ListReadonly Document files; parameter: • bounds: class FolderF extends Existing File ... Collection super Existing File var; • array: DocumentReadonly docs1 = new DocumentReadonly 212; DocumentReadonly docs2 = new Document2Readonly 12; © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 14 last update: 4/16/2008 ,12:42disambiguation Dimension getSize() Readonly ... • Readonly annotates the type of this Readonly Dimension getSize() ... • Target metaannotation indicates the intent: • Readonly annotates the return type Target(ElementType.TYPE) Override public interface ReadOnly NonNull Dimension getSize() ... • NonNull annotates the return type Target(ElementType.TYPE) public interface NonNull • Override annotates the method declaration Target(ElementType.METHOD) public interface Override © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 15 last update: 4/16/2008 ,12:42agenda • annotation language features – declaring annotation types – annotating program elements – meta annotations • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 16 last update: 4/16/2008 ,12:42meta annotations Target(ElementType) • indicates the program elements to which an annotation type can be applied • values: TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCALVARIABLE, ANNOTATIONTYPE, PACKAGE • default: applicable to all program elements Documented • indicates that annotations are documented in javadoc Retention(RetentionPolicy) • indicates how long annotations are to be retained • values: SOURCE, CLASS, RUNTIME • default: CLASS © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 17 last update: 4/16/2008 ,12:42sample usage • selfreferential metaannotation Documented Retention(value=RUNTIME) Target(value=ANNOTATIONTYPE) public interface Retention RetentionPolicy value(); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 18 last update: 4/16/2008 ,12:42agenda • annotation language features • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 19 last update: 4/16/2008 ,12:42annotation processing • can happen on 3 levels – introspectors • process runtimevisible annotations of their own program elements • use reflection and need annotations with RUNTIME retention – byte code analyzers • process annotations in .class files • e.g. stub generators – source code analyzers • process annotations in Java source code • e.g. compilers, documentation generators, class browsers © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 20 last update: 4/16/2008 ,12:42agenda • annotation language features • processing annotations – reflection – pluggable annotation processing in 6.0 • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 21 last update: 4/16/2008 ,12:42introspection • using reflection – to inspect its own program elements – search for annotated elements – retrieve annotations and their content • reflection API has been extended – to support introspective annotation processing © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 22 last update: 4/16/2008 ,12:42extensions to the reflection API • additional methods inPackage, Class, Field, Constructor, Method A extends Annotation A getAnnotation(ClassA annotationClass) • returns the specified annotation if present on this element Annotations getAnnotations() Annotations getDeclaredAnnotations() • returns all annotations that are (directly) present on this element boolean isAnnotationPresent (Class extends Annotation annotationClass) • returns true if an annotation for the specified type is present on this element © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 23 last update: 4/16/2008 ,12:42reading annotations RequestForEnhancement( id = 28, synopsis = "Provide timetravel functionality", engineer = "Mr. Peabody", date = "24/12/2008" ) public static void travelThroughTime(Date destination) ... • accessed reflectively: Method m = TimeTravel.class.getMethod ("travelThroughTime", new Class Date.class); RequestForEnhancement rfe = m.getAnnotation(RequestForEnhancement.class); int id = rfe.id(); String synopsis = rfe.synopsis(); String engineer = rfe.engineer(); String date = rfe.date(); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 24 last update: 4/16/2008 ,12:42agenda • annotation language features • processing annotations – reflection – pluggable annotation processing in 6.0 • case studies © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 25 last update: 4/16/2008 ,12:42annotation processing in Java 6.0 • annotation processing integrated into javac compiler – since Java 6.0; known as pluggable annotation processing – compiler automatically searches for annotation processors – unless disabled with proc:none option – processors can be specified explicitly with processor option – details at java.sun.com/javase/6/docs/technotes/tools/windows/ javac.htmlprocessing •example: javac processor MyAnnotationProcessor MyAnnotatedClass.java © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 26 last update: 4/16/2008 ,12:42annotation processor • implement a processor class – must implement Processor interface – typically derived from AbstractProcessor – new package javax.annotation.processing • specify supported annotation + options – by means of annotations: SupportedAnnotationTypes SupportedOptions SupportedSourceVersion © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 27 last update: 4/16/2008 ,12:42annotation processor example SupportedAnnotationTypes("Property") SupportedSourceVersion(SourceVersion.RELEASE6) public class PropertyAnnotationProcessor extends AbstractProcessor public boolean process(Set extends TypeElement annotations, RoundEnvironment env) … process the source file elements using the mirror API … © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 28 last update: 4/16/2008 ,12:42rounds • annotation processing happens in a sequence of rounds st •1 round: – compiler parses source files on the command line • to determine what annotations are present – compiler queries the processors • to determine what annotations they process – when a match is found, the processor is invoked © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 29 last update: 4/16/2008 ,12:42claim • a processor may "claim" annotations – no further attempt to find any processors for those annotations – once all annotations have been claimed, compiler stops looking for additional processors • claim is specified as return value of process() method – true: annotations are claimed; no subsequent processors are asked to process them – false: annotations are unclaimed; – subsequent processors are asked to process them © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 30 last update: 4/16/2008 ,12:42subsequent rounds • if processors generate new source files, another round of annotation processing starts – newly generated source files are parsed and annotations are processed as before – processors invoked on previous rounds are also invoked on all subsequent rounds • this continues until no new source files are generated © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 31 last update: 4/16/2008 ,12:42last round • after a round where no new source files are generated: – annotation processors are invoked one last time • to give them a chance to complete work they still need to do – compiler compiles original and all generated source files • compilation and/or processing is controlled by proc option proc:only: only annotation processing, no subsequent compilation proc:none: compilation takes place without annotation processing © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 32 last update: 4/16/2008 ,12:42environment • processor environment provides – Filer for creation of new source, class, or auxiliary files – Messager to report errors, warnings, and other notices • inherited as protected field from AbstractProcessor protected ProcessingEnvironment processingEnv – implicitly initialized on construction of the processor © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 33 last update: 4/16/2008 ,12:42processor arguments • process() method takes 2 arguments: Set extends TypeElement annotations – the annotation types requested to be processed – subset of the supported annotations RoundEnvironment roundenv – environment for information about the current and prior round – supplies elements annotated with a given annotation or all root elements in the source © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 34 last update: 4/16/2008 ,12:42annotation processor example public boolean process(Set extends TypeElement annotations, RoundEnvironment roundEnv) for (Element t : roundEnv.getRootElements()) if (t.getModifiers().contains(Modifier.PUBLIC)) for (ExecutableElement m : ElementFilter.methodsIn(t.getEnclosedElements())) Property p = m.getAnnotation(Property.class); if (p = null) … process property ... … © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 35 last update: 4/16/2008 ,12:42elements and types • elements and types from javax.lang.model. packages – represent declarations and types in the Java source code • element is a static language construct – like the declaration of java.util.Set •a family of types is associated with an element –liketherawtype java.util.Set, and the parameterized types java.util.SetString and java.util.SetT © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 36 last update: 4/16/2008 ,12:42filers private void writeGeneratedFile(String beanClassName) FileObject sourceFile = processingEnv.getFiler().createSourceFile(beanClassName); PrintWriter out = new PrintWriter(sourceFile.openWriter()); out.print("public class "); … out.close(); • Filers are obtained from the processing environment – not from the round environment © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 37 last update: 4/16/2008 ,12:42agenda • annotation language features • processing annotations • case study © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 38 last update: 4/16/2008 ,12:42Comparator annotation • define a Comparator annotation – that can be used to annotate methods that perform a comparison • build an annotation processor that generates a Comparator class – for each annotated method © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 39 last update: 4/16/2008 ,12:42intended use of annotation file: data\Name.java public class Name private final String first; private final String last; public Name(String f, String l) first = f; last = l; Comparator("NameByFirstNameComparator") public int compareToByFirstName(Name other) if (this == other) return 0; int result; if ((result = this.first.compareTo(other.first)) = 0) return result; return this.last.compareTo(other.last); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 40 last update: 4/16/2008 ,12:42class to be generated file: data\NameByFirstNameComparator.java public class NameByFirstNameComparator implements java.util.ComparatorName public int compare(Name o1, Name o2) return o1.compareToByFirstName(o2); public boolean equals(Object other) return this.getClass() == other.getClass(); © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 41 last update: 4/16/2008 ,12:42define the Comparator annotation file: processor/Comparator.java Documented Target(ElementType.METHOD) Retention(RetentionPolicy.SOURCE) public interface Comparator String value(); • applicable to methods only • present in source code only • value is the name of the Comparator class to be generated © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 42 last update: 4/16/2008 ,12:42annotation processor file: processor/ComparatorAnnotationProcessor.java SupportedAnnotationTypes("processor.Comparator") SupportedSourceVersion(SourceVersion.RELEASE6) public class ComparatorAnnotationProcessor extends AbstractProcessor public boolean process( Set extends TypeElement annotations, RoundEnvironment roundEnv) … see next slide … • supports no options • processes only the Comparator annotation © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 43 last update: 4/16/2008 ,12:42processing Comparator public void process() for (Element t : roundEnv.getRootElements()) if (t.getModifiers().contains(Modifier.PUBLIC)) for (ExecutableElement m : ElementFilter.methodsIn(t.getEnclosedElements()) ) Comparator a = m.getAnnotation(Comparator.class); if (a = null) …see next slide … • process all type declarations in the source file • ignore nonpublic ones • process all methods of the type • ignore methods without a Comparator annotation © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 44 last update: 4/16/2008 ,12:42checking the annotated method TypeMirror returnType = m.getReturnType(); if ((returnType instanceof PrimitiveType) ((PrimitiveType)returnType).getKind()=TypeKind.INT ) processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Comparator can only be applied to methods that return int"); continue; … see next slide … • check whether return type is int • print error message © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 45 last update: 4/16/2008 ,12:42preparing code generation String comparatorClassName = a.value(); String comparetoMethodName = m.getSimpleName(); String theProcessedClassesName = t.getQualifiedName(); writeComparatorFile(theProcessedClassesName, comparatorClassName, comparetoMethodName); • retrieve the name of the Comparator class to be generated – from the Comparator annotation • retrieve the compare method's name – from the annotated method • retrieve the enclosing class's name – from the processed type declaration © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 46 last update: 4/16/2008 ,12:42generating the source file private void writeComparatorFile( String fullClassName, String comparatorClassName, String compareToMethodName) throws IOException int i = fullClassName.lastIndexOf("."); String packageName = fullClassName.substring(0, i); FileObject sourceFile = processingEnv.getFiler(). createSourceFile(packageName+"."+comparatorClassName); PrintWriter out = new PrintWriter(sourceFile.openWriter()); if (i 0) out.println("package "+packageName); …see next slide … • get output destination from environment • create a source file and provide the class name – package directory and .java suffix are determined automatically © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 47 last update: 4/16/2008 ,12:42invoke compiler • invoke the javac compiler for annotation processing – it generates a class for each annotated method – in the package of the method's enclosing class javac processor processor.ComparatorAnnotationProcessor data\Name.java © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 48 last update: 4/16/2008 ,12:42wrapup • annotations permit associating information with program elements – consist of membervaluepairs and an annotation type – annotation types are a restricted variant of interfaces • annotations have different lifetime – SOURCE, CLASS, RUNTIME – runtime annotations can be read via reflection – source code annotation processing supported by javac compiler © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 49 last update: 4/16/2008 ,12:42wrapup • 6.0 pluggable annotation processing support – an easy way of processing annotations and generating side files • not an exhaustive exploration of the possibilities • case study intends to provide an idea of what can be done with annotated source files © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 50 last update: 4/16/2008 ,12:42author Angelika Langer Angelika Langer Training Mentoring ObjectOriented Software Development in C++ Java Email: contactAngelikaLanger.com http: www.AngelikaLanger.com © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 51 last update: 4/16/2008 ,12:42annotation processing Q A © Copyright 20032008 by Angelika Langer Klaus Kreft. All Rights Reserved. http://www.AngelikaLanger.com 52 last update: 4/16/2008 ,12:42
Website URL
Comment