org.yarnandtail.andhow.compile

Class AndHowCompileProcessor

java.lang.Object

javax.annotation.processing.AbstractProcessor

org.yarnandtail.andhow.compile.AndHowCompileProcessor

All Implemented Interfaces:

Processor

@SupportedAnnotationTypes(value="*")
public class AndHowCompileProcessor
extends AbstractProcessor

This is the central AndHow compilation class, an Annotation Processor. An annotation processor nominally reads annotations as classes are compiled. This class is annotated SupportedAnnotationTypes("*"), allowing it to 'see' all classes as they are compiled. This class then delegates to a 'scanner' class that does deep inspection on compiled code, looking for AndHow Properties.

When an AndHow Property is found in a class, a new PropertyRegistrar class is created, which contains the list of Properties in that class. There is a one-to-one correspondence between user classes that contain AndHow Properties and auto-created PropertyRegistrar classes.

At runtime, AndHow will use the ServiceLoader to discover all instances of PropertyRegistrar on the classpath, thus finding all AndHow Property containing classes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	AndHowCompileProcessor.CauseEffect Match up a causal Element (Basically the compiler representation of a class to be compiled) w/ the Class name that will be registered in a service registry.

Field Summary

Fields inherited from class javax.annotation.processing.AbstractProcessor

processingEnv

Constructor Summary

Constructors

Constructor and Description
AndHowCompileProcessor() A no-arg constructor is required.

Method Summary

Modifier and Type	Method and Description
int	getJdkVersion() The major version number of the JDK used to compile.
int	getSrcVersion() The java language level the output file needs to be compatible with.
SourceVersion	getSupportedSourceVersion()
void	init(ProcessingEnvironment processingEnv)
boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
protected void	processFinalRound(Filer filer, Messager log, int srcVersion, int jdkVersion, List<CompileProblem> compileProblems, List<AndHowCompileProcessor.CauseEffect> initCEs, List<AndHowCompileProcessor.CauseEffect> testInitCEs, List<AndHowCompileProcessor.CauseEffect> registrarCEs) The final round of annotation processing.
protected void	processNonFinalRound(ProcessingEnvironment localProcessingEnv, RoundEnvironment roundEnv, Calendar runDate, Filer filer, Messager log, int srcVersion, int jdkVersion, List<CompileProblem> compileProblems, List<AndHowCompileProcessor.CauseEffect> initCEs, List<AndHowCompileProcessor.CauseEffect> testInitCEs, List<AndHowCompileProcessor.CauseEffect> registrarCEs) Process a round of annotation processing.
protected CompileUnit	scanTypeElement(ProcessingEnvironment localProcessingEnv, TypeElement typeElement) Scan the TypeElement for init, testInit and AndHow properties.
void	writeClassFile(Filer filer, PropertyRegistrarClassGenerator generator, Element causingElement) Writes a new class implementing the PropertyRegistrar interface.
protected void	writeServiceFile(Filer filer, String fullyQualifiedServiceInterfaceName, List<AndHowCompileProcessor.CauseEffect> implementingClasses) Writes a new META-INF service file with a list of classes implementing the specified interface.

Methods inherited from class javax.annotation.processing.AbstractProcessor

getCompletions, getSupportedAnnotationTypes, getSupportedOptions, isInitialized

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AndHowCompileProcessor

public AndHowCompileProcessor()

A no-arg constructor is required.

Method Detail

init

public void init(ProcessingEnvironment processingEnv)

Specified by:

init in interface Processor

Overrides:

init in class AbstractProcessor

getSrcVersion

public int getSrcVersion()

The java language level the output file needs to be compatible with.

This is provided by the ProcessingEnvironment.getSourceVersion() as an enum, but is converted here to the major version number. Version 1.8 return 8, ver. 9 returns 9 and so on.

Returns:

The source level to generate code to.

getJdkVersion

public int getJdkVersion()

The major version number of the JDK used to compile.

This taken from System.getProperty("java.version"), See CompileUtil.getMajorJavaVersion(). JDK 1.8 return 8, JDK 9 returns 9 and so on.

Returns:

The major version of the JDK used to compile.

getSupportedSourceVersion

public SourceVersion getSupportedSourceVersion()

Specified by:

getSupportedSourceVersion in interface Processor

Overrides:

getSupportedSourceVersion in class AbstractProcessor

process

public boolean process(Set<? extends TypeElement> annotations,
                       RoundEnvironment roundEnv)

Specified by:

process in interface Processor

Specified by:

process in class AbstractProcessor

processNonFinalRound

protected void processNonFinalRound(ProcessingEnvironment localProcessingEnv,
                                    RoundEnvironment roundEnv,
                                    Calendar runDate,
                                    Filer filer,
                                    Messager log,
                                    int srcVersion,
                                    int jdkVersion,
                                    List<CompileProblem> compileProblems,
                                    List<AndHowCompileProcessor.CauseEffect> initCEs,
                                    List<AndHowCompileProcessor.CauseEffect> testInitCEs,
                                    List<AndHowCompileProcessor.CauseEffect> registrarCEs)

Process a round of annotation processing.

There will always be a 'final' round of processing after all annotation processors have completed and stop generating new files.

Parameters:

localProcessingEnv - The compile-time environment, for writing and analyzing classes

roundEnv - State of a single round of annotation processing

runDate - Single consistent timestamp for the entire compilation

filer - ProcessingEnv provided file system for writing source files

log - ProcessingEnv provided message/log system

srcVersion - Major version number of the source code the compiler is using

jdkVersion - Major version number of the JDK

compileProblems - Accumulation of problems - reported in final processing round

initCEs - Accumulation of AndHowInit implementing classes, as they are discovered

testInitCEs - Accumulation of AndHowTestInit implementing classes, as they are discovered

registrarCEs - Accumulation of AndHow Property containing top-level classes, as they are discovered

processFinalRound

protected void processFinalRound(Filer filer,
                                 Messager log,
                                 int srcVersion,
                                 int jdkVersion,
                                 List<CompileProblem> compileProblems,
                                 List<AndHowCompileProcessor.CauseEffect> initCEs,
                                 List<AndHowCompileProcessor.CauseEffect> testInitCEs,
                                 List<AndHowCompileProcessor.CauseEffect> registrarCEs)

The final round of annotation processing.

No new root elements (i.e. application classes) are processed in this round. Instead, this round is the opportunity to write final generated output:

• Service loader file in META-INF for AndHowInit instances (max of one)
• Service loader file in META-INF for AndHowTestInit instances (max of one)
• Service loader file in META-INF for PropertyRegistrar instances (could be many entries) for each generated proxy class containing AndHow Properties

Parameters:

filer - ProcessingEnv provided file system for writing source files

log - ProcessingEnv provided message/log system

srcVersion - Major version number of the source code the compiler is using

jdkVersion - Major version number of the JDK

compileProblems - Accumulation of problems - reported in final processing round

initCEs - Accumulation of AndHowInit implementing classes, as they are discovered

testInitCEs - Accumulation of AndHowTestInit implementing classes, as they are discovered

registrarCEs - Accumulation of AndHow Property containing top-level classes, as they are discovered

scanTypeElement

protected CompileUnit scanTypeElement(ProcessingEnvironment localProcessingEnv,
                                      TypeElement typeElement)

Scan the TypeElement for init, testInit and AndHow properties.

Parameters:

localProcessingEnv - The environment used to analyze the typeElement

typeElement - Represents a class being compiled

Returns:

A CompileUnit, which is a summary of init, testInit and AndHow properties in the Type.

writeClassFile

public void writeClassFile(Filer filer,
                           PropertyRegistrarClassGenerator generator,
                           Element causingElement)
                    throws Exception

Writes a new class implementing the PropertyRegistrar interface.

The new class directly corresponds to a user classes containing AndHow Properties and will contain meta data about the properties.

Parameters:

filer - The javac file system representation for writing files.

generator - AndHow class capable of generating source code for this PropertyRegistrar class.

causingElement - A javac Element, which generically refers to any piece of source code such as a keyword, class name, etc.. When a file is written to the filer, a causingElement is recorded as metadata so there is an association between the file and the reason it was written. Likely this is normally used to associate source code line numbers with generated code.

Throws:

Exception - If unable to write (out of disc space?) or other issues

writeServiceFile

protected void writeServiceFile(Filer filer,
                                String fullyQualifiedServiceInterfaceName,
                                List<AndHowCompileProcessor.CauseEffect> implementingClasses)
                         throws IOException

Writes a new META-INF service file with a list of classes implementing the specified interface.

The new class directly corresponds to a user classes containing AndHow Properties and will contain meta data about the properties.

Parameters:

filer - The ProcessingEnvironment provided Filer

fullyQualifiedServiceInterfaceName - The name of the interface the classes implement

implementingClasses - List of CauseEffect's with each class implementing the interface

Throws:

IOException - If unable to write the file