Class BasicAnnotationProcessor
- java.lang.Object
-
- javax.annotation.processing.AbstractProcessor
-
- com.google.auto.common.BasicAnnotationProcessor
-
- All Implemented Interfaces:
Processor
public abstract class BasicAnnotationProcessor extends AbstractProcessor
An abstractProcessor
implementation that defers processing ofElement
s to later rounds if they cannot be processed.Subclasses put their processing logic in
BasicAnnotationProcessor.ProcessingStep
implementations. The steps are passed to the processor by returning them in theinitSteps()
method, and can access theProcessingEnvironment
usingAbstractProcessor.processingEnv
. Any logic that needs to happen once per round can be specified by overridingpostProcess()
.Ill-formed elements are deferred
Any annotated element whose nearest enclosing type is not well-formed is deferred, and not passed to anyProcessingStep
. This helps processors to avoid many common pitfalls, such asErrorType
instances,ClassCastException
s and badly coerced types.A non-package element is considered well-formed if its type, type parameters, parameters, default values, supertypes, annotations, and enclosed elements are. Package elements are treated similarly, except that their enclosed elements are not validated. See
SuperficialValidation.validateElement(Element)
for details.The primary disadvantage to this validation is that any element that forms a circular dependency with a type generated by another
BasicAnnotationProcessor
will never compile because the element will never be fully complete. All such compilations will fail with an error message on the offending type that describes the issue.Each
ProcessingStep
can defer elementsEach
ProcessingStep
can defer elements by including them in the set returned byBasicAnnotationProcessor.ProcessingStep.process(SetMultimap)
; elements deferred by a step will be passed back to that step in a later round of processing.This feature is useful when one processor may depend on code generated by another, independent processor, in a way that isn't caught by the well-formedness check described above. For example, if an element
A
cannot be processed because processing it depends on the existence of some classB
, thenA
should be deferred until a later round of processing, whenB
will have been generated by another processor.If
A
directly referencesB
, then the well-formedness check will correctly defer processing ofA
untilB
has been generated.However, if
A
referencesB
only indirectly (for example, from within a method body), then the well-formedness check will not defer processingA
, but a processing step can rejectA
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
BasicAnnotationProcessor.ProcessingStep
The unit of processing logic that runs under the guarantee that all elements are complete and well-formed.
-
Field Summary
-
Fields inherited from class javax.annotation.processing.AbstractProcessor
processingEnv
-
-
Constructor Summary
Constructors Constructor Description BasicAnnotationProcessor()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description com.google.common.collect.ImmutableSet<String>
getSupportedAnnotationTypes()
Returns the set of supported annotation types as a collected from registered processing steps.void
init(ProcessingEnvironment processingEnv)
protected abstract Iterable<? extends BasicAnnotationProcessor.ProcessingStep>
initSteps()
Creates processing steps for this processor.protected void
postProcess()
An optional hook for logic to be executed at the end of each round.boolean
process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
-
Methods inherited from class javax.annotation.processing.AbstractProcessor
getCompletions, getSupportedOptions, getSupportedSourceVersion, isInitialized
-
-
-
-
Method Detail
-
init
public final void init(ProcessingEnvironment processingEnv)
- Specified by:
init
in interfaceProcessor
- Overrides:
init
in classAbstractProcessor
-
initSteps
protected abstract Iterable<? extends BasicAnnotationProcessor.ProcessingStep> initSteps()
Creates processing steps for this processor.AbstractProcessor.processingEnv
is guaranteed to be set when this method is invoked.
-
postProcess
protected void postProcess()
An optional hook for logic to be executed at the end of each round.
-
getSupportedAnnotationTypes
public final com.google.common.collect.ImmutableSet<String> getSupportedAnnotationTypes()
Returns the set of supported annotation types as a collected from registered processing steps.- Specified by:
getSupportedAnnotationTypes
in interfaceProcessor
- Overrides:
getSupportedAnnotationTypes
in classAbstractProcessor
-
process
public final boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
- Specified by:
process
in interfaceProcessor
- Specified by:
process
in classAbstractProcessor
-
-