OXIGEN - RainFocus

OXIGEN - RainFocus

CODE GENERATION WITH ANNOTATION PROCESSORS: STATE OF THE ART IN JAVA 9 [CON3282] ABOUT THE SPEAKERS Welcome to our session! Jorge Hidalgo Julio Palma Vzquez Coordinator Mlaga JUG Member Mlaga JUG Global Java Lead Accenture Technology Java, Architecture & DevOps Lead

Accenture Delivery Center in Spain Technology Architect Accenture Technology Accenture Global Java Champion Accenture Delivery Center in Spain Father of two children, husband, whistle player, video gamer, sci-fi junkie, Star Wars addict, Lego brick wielder, Raspberry Pi fan, LLAP! Mountain biker, AD&D player, Sid Meiers Civilization gamer, LotR fan, @_deors https://github.com/deors @restalion https://github.com/restalion

Copyright 2017 Accenture. All rights reserved. 2 CODE GENERATION IN THE JAVA COMPILER Objetives for the session Overview of Annotations and Annotation Processors in Java Whats new in Java 9 APT API Learn how to create Annotation Processors

Learn how to use Annotation Processors to generate source code Annotation Processors and Modules in Java 9 With lots of examples and source code Copyright 2017 Accenture. All rights reserved. 3 POLL #1

Please raise your hands if you are familiar with Annotations, know how to use them or are even capable of writing Annotation Types Copyright 2017 Accenture. All rights reserved. 4 ANNOTATIONS IN JAVA LANGUAGE Copyright 2017 Accenture. All rights reserved. 5 ANNOTATIONS IN THE JAVA LANGUAGE History

Annotations were first introduced in Java 5 Add metadata capabilities to the Java language: Build/deployment information Configuration properties Compiler behavior Quality checks

Dependency injection Persistence mapping ... Copyright 2017 Accenture. All rights reserved. 6 ANNOTATIONS IN THE JAVA LANGUAGE Overview

Annotations always appear before the annotated piece of code Annotations can decorate... Packages Types (classes, interfaces, enums, annotation types) Variables (class, instance and local variables)

Constructors, methods and their parameters Generic type parameter (since Java 8) Any type use (since Java 8) Copyright 2017 Accenture. All rights reserved. 7 ANNOTATIONS IN THE JAVA LANGUAGE Overview Can be grouped, nested, repeated... very powerful! Map<@NonNull String, @NonEmpty List<@Readonly Document>> docStore;

Annotations may be used just as a marker @NonNull String email; They may contain name-value pairs, and arrays @Author(name = "Albert", created = "17/09/2010", revision = 3, reviewers = {"George", "Fred"}) public class SomeClass {...} Can be defined with default values, and then omitted when used When it has only one attribute named value, it can be omitted, too @DatabaseTable(MY_TABLE) public class MyTable {...} Copyright 2017 Accenture. All rights reserved. 8 HOW TO CREATE ANNOTATIONS

AND ANNOTATION PROCESSORS Copyright 2017 Accenture. All rights reserved. 9 POLL #2 Please raise your hands if you are familiar with Annotation Processors, their capabilities or know how to write new ones Copyright 2017 Accenture. All rights reserved. 10 ANNOTATIONS Create an Annotation Type

A special type of interface public @interface Author { String name(); String created(); int revision() default 1; String[] reviewers() default {}; } Only primitives, enum types, annotation types, String, Class and arrays of them are allowed as elements May be annotated itself, i.e. to define the retention policy or targets @Retention(RetentionPolicy.SOURCE)

@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE}) public @interface Author {...} Can trigger custom actions at compile time managed by Annotation Processors! Copyright 2017 Accenture. All rights reserved. 11 ANNOTATION PROCESSORS Annotation Processing API Annotation Processor: Implements javax.annotation.processing.Processor Or extends javax.annotation.processing.AbstractProcessor May use three annotations to configure itself: jx.a.p.SupportedAnnotationTypes Used to flag which Annotation Types are managed by

the processor jx.a.p.SupportedSourceVersion Used to flag the latest Java source level supported by the processor jx.a.p.SupportedOptions Used to register custom parameters that may be passed through the command line TL;DR Implement the process() method Copyright 2017 Accenture. All rights reserved. 12 ANNOTATION PROCESSORS Annotation Processing API Annotation processing happens in rounds In each round, a subset of sources are compiled, and then processors matching the annotations found on those sources are called

Processing ends when no more sources/annotations are pending Processors may claim all annotation types with a wildcard process() method has two parameters: Set subset of annotations being processed jx.a.p.RoundEnvironment access to information about the current and previous round Copyright 2017 Accenture. All rights reserved. 13 ANNOTATION PROCESSORS Creating Files jx.a.p.ProcessingEnvironment also provides access to the Filer utility that allows for easy file creation Files are placed in the right folder as required by the compiler settings Folder hierarchy matching the package name

JavaFileObject jfo = processingEnv.getFiler() .createSourceFile(newClassQualifiedName); Writer writer = jfo.openWriter(); ...or... JavaFileObject jfo = processingEnv.getFiler() .createClassFile(newClassQualifiedName); OutputStream os = jfo.openOutputStream(); Copyright 2017 Accenture. All rights reserved. 14 ANNOTATION PROCESSORS How the compiler knows? Annotation Processors leverage the standard services mechanism Package the processors in a Jar file

Include file META-INF/services/javax.annotation.processing.Processor Contents are the fully qualified names of the bundled processors, one per line Copyright 2017 Accenture. All rights reserved. 15 ANNOTATION PROCESSORS Running Annotation Processors Find more information about APT in JavaOne 2014 session: https://www.slideshare.net/deors/javaone-2014-con2013-code-generation-in-thejava-compiler-annotation-processors-do-the-hard-work https://www.youtube.com/watch?v=xswPPwYPAFM Copyright 2017 Accenture. All rights reserved. 16

ANNOTATION PROCESSORS Running Annotation Processors Multiple ways: javac Apache Maven builds Continuous Integration builds IDE Copyright 2017 Accenture. All rights reserved. 17 ADAPT LEGACY APT PROJECTS TO JAVA 9

Copyright 2017 Accenture. All rights reserved. 18 ADAPT LEGACY CODE Upgrading your code to Java 9 Update tag in pom.xml 1.9 Update version of maven-compiler-plugin org.apache.maven.plugins maven-compiler-plugin

3.6.2 Upgrade the supported source version in Processor class @SupportedAnnotationTypes(com.foo.AnnotationSample") @SupportedSourceVersion(SourceVersion.RELEASE_9) public class AnnotationSampleProcessor Copyright 2017 Accenture. All rights reserved. 19 ANNOTATIONS API IN JAVA 9 Upgrading your code to Java 9 mvn clean install finish without errors:

Copyright 2017 Accenture. All rights reserved. 20 ANNOTATIONS API IN JAVA 9 Executing upgraded projects DEMO Copyright 2017 Accenture. All rights reserved. 21 ADAPT LEGACY CODE Upgrading your code to Java 9 Upgraded legacy code sample can be found in github: https://github.com/deors/deors.demos.annotations

Copyright 2017 Accenture. All rights reserved. 22 WHATS NEW IN JAVA 9 APT API Copyright 2017 Accenture. All rights reserved. 23 ANNOTATIONS API IN JAVA 9 Overview New @Generated Annotation To add information about the annotation processor, date, and comments: @Generated(value = "com.foo.processors.SampleProcessor",

date = "2017-09-28T09:43:28.170886", comments = "Sample") Processed as a subsequent step by the annotation processor. Two new methods in RoundEnvironment interface Simplify processing of multiple annotations default Set getElementsAnnotatedWithAny( Set> annotations); default Set getElementsAnnotatedWithAny( TypeElement... annotations); Copyright 2017 Accenture. All rights reserved. 24 ANNOTATIONS API IN JAVA 9 Overview Changes in all methods of Filer interface. To manage files in a module, module name is prefixed to the type name and

separated using a / character, i.e.: JavaFileObject jfo = processingEnv.getFiler().createSourceFile( "com.foo/com.foo.Bar"); JavaFileObject jfo = processingEnv.getFiler().getResource(location, "com.foo/com.foo", "Bar"); Copyright 2017 Accenture. All rights reserved. 25 NEW FEATURES IN JAVA 9 Generated Annotation Its a best practice to include this annotation in the generated code: MUST have the name of the code generator bw.append("@Generated(value = \"" + this.getClass().getName() + "\" , date = \"" +

LocalDateTime.now() + "\", comments = \"Test generator\")"); Date when the source was generated Comments Copyright 2017 Accenture. All rights reserved. 26 NEW FEATURES IN JAVA 9 Generated Annotation During annotation processing,the Generated annotation will be found but nothing is done, its just informational.

Generated code: Name of the code generator Generation date Copyright 2017 Accenture. All rights reserved. Comments 27 ANNOTATIONS API IN JAVA 9 Module Copyright 2017 Accenture. All rights reserved. 28

ANNOTATION PROCESSORS AND MODULES IN JAVA 9 Copyright 2017 Accenture. All rights reserved. 29 ANNOTATION PROCESSORS AND MODULES Creating classes in modules In previous examples we have three different jar files: Annotation type

Annotation processor classes that use annotations annotation.process or annotation client Dependencies are managed using the regular classpath

Copyright 2017 Accenture. All rights reserved. 30 ANNOTATION PROCESSORS AND MODULES Grouping classes in modules One module per jar file. Put a module-info.java file into each module. Each module-info file needs to define exported packages and required modules. annotation.process or

annotation client Copyright 2017 Accenture. All rights reserved. 31 ANNOTATION PROCESSORS AND MODULES Creating classes in modules annotation module: module com.foo.annotation { exports com.foo.annotation; } annotation.process or

annotation.processor module: module com.foo.annotation.processors { annotation requires com.foo.annotation; requires java.compiler; } client client module: module com.foo.client { exports com.foo.client; requires com.foo.annotation; requires java.compiler; }

Copyright 2017 Accenture. All rights reserved. Why? Because we add @Generated annotation 32 ANNOTATION PROCESSORS AND MODULES Creating classes in modules DEMO Copyright 2017 Accenture. All rights reserved. 33 SUMMARY APT API is as powerful as in previous versions. All your legacy code still works as expected. You can add a couple a of new functionalities:

@Generator annotation Simplified processing of multiple annotations You can also manage file generation in other modules Copyright 2017 Accenture. All rights reserved. 34 Q&A Many thanks for attending! @_deors https://github.com/deors

@restalion https://github.com/restalio n Copyright 2017 Accenture. All rights reserved. 35

Recently Viewed Presentations