com.google.auto.common

Class BasicAnnotationProcessor

java.lang.Object

javax.annotation.processing.AbstractProcessor

com.google.auto.common.BasicAnnotationProcessor

All Implemented Interfaces:

javax.annotation.processing.Processor

public abstract class BasicAnnotationProcessor
extends javax.annotation.processing.AbstractProcessor

An abstract Processor implementation that defers processing of Elements to later rounds if they cannot be processed.

Subclasses put their processing logic in BasicAnnotationProcessor.Step implementations. The steps are passed to the processor by returning them in the steps() method, and can access the ProcessingEnvironment using AbstractProcessor.processingEnv.

Any logic that needs to happen once per round can be specified by overriding postRound(RoundEnvironment).

Ill-formed elements are deferred

Any annotated element whose nearest enclosing type is not well-formed is deferred, and not passed to any Step. This helps processors to avoid many common pitfalls, such as ErrorType instances, ClassCastExceptions 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 Step can defer elements

Each Step can defer elements by including them in the set returned by BasicAnnotationProcessor.Step.process(ImmutableSetMultimap); 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 class B, then A should be deferred until a later round of processing, when B will have been generated by another processor.

If A directly references B, then the well-formedness check will correctly defer processing of A until B has been generated.

However, if A references B only indirectly (for example, from within a method body), then the well-formedness check will not defer processing A, but a processing step can reject A.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BasicAnnotationProcessor.ProcessingStep Deprecated. Implement BasicAnnotationProcessor.Step instead. See steps().
static interface	BasicAnnotationProcessor.Step 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 and Description
BasicAnnotationProcessor()

Method Summary

Modifier and Type	Method and Description
protected static BasicAnnotationProcessor.Step	asStep(BasicAnnotationProcessor.ProcessingStep processingStep) Wraps the passed BasicAnnotationProcessor.ProcessingStep in a BasicAnnotationProcessor.Step.
com.google.common.collect.ImmutableSet<java.lang.String>	getSupportedAnnotationTypes() Returns the set of supported annotation types as collected from registered processing steps.
void	init(javax.annotation.processing.ProcessingEnvironment processingEnv)
protected java.lang.Iterable<? extends BasicAnnotationProcessor.ProcessingStep>	initSteps() Deprecated. Implement steps() instead.
protected void	postProcess() Deprecated. use postRound(RoundEnvironment) instead
protected void	postRound(javax.annotation.processing.RoundEnvironment roundEnv) An optional hook for logic to be executed at the end of each round.
boolean	process(java.util.Set<? extends javax.lang.model.element.TypeElement> annotations, javax.annotation.processing.RoundEnvironment roundEnv)
protected java.lang.Iterable<? extends BasicAnnotationProcessor.Step>	steps() Creates processing steps for this processor.

Methods inherited from class javax.annotation.processing.AbstractProcessor

getCompletions, getSupportedOptions, getSupportedSourceVersion, isInitialized

Methods inherited from class java.lang.Object

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

Constructor Detail

BasicAnnotationProcessor

public BasicAnnotationProcessor()

Method Detail

init

public final void init(javax.annotation.processing.ProcessingEnvironment processingEnv)

Specified by:

init in interface javax.annotation.processing.Processor

Overrides:

init in class javax.annotation.processing.AbstractProcessor

initSteps

@Deprecated
protected java.lang.Iterable<? extends BasicAnnotationProcessor.ProcessingStep> initSteps()

Deprecated. Implement steps() instead.

Creates processing steps for this processor. AbstractProcessor.processingEnv is guaranteed to be set when this method is invoked.

steps

protected java.lang.Iterable<? extends BasicAnnotationProcessor.Step> steps()

Creates processing steps for this processor. AbstractProcessor.processingEnv is guaranteed to be set when this method is invoked.

Note: If you are migrating some steps from BasicAnnotationProcessor.ProcessingStep to BasicAnnotationProcessor.Step, then you can call asStep(ProcessingStep) on any unmigrated steps.

postProcess

@Deprecated
protected void postProcess()

Deprecated. use postRound(RoundEnvironment) instead

An optional hook for logic to be executed at the end of each round.

postRound

protected void postRound(javax.annotation.processing.RoundEnvironment roundEnv)

An optional hook for logic to be executed at the end of each round.

getSupportedAnnotationTypes

public final com.google.common.collect.ImmutableSet<java.lang.String> getSupportedAnnotationTypes()

Returns the set of supported annotation types as collected from registered processing steps.

Specified by:

getSupportedAnnotationTypes in interface javax.annotation.processing.Processor

Overrides:

getSupportedAnnotationTypes in class javax.annotation.processing.AbstractProcessor

process

public final boolean process(java.util.Set<? extends javax.lang.model.element.TypeElement> annotations,
                             javax.annotation.processing.RoundEnvironment roundEnv)

Specified by:

process in interface javax.annotation.processing.Processor

Specified by:

process in class javax.annotation.processing.AbstractProcessor

asStep

protected static BasicAnnotationProcessor.Step asStep(BasicAnnotationProcessor.ProcessingStep processingStep)

Wraps the passed BasicAnnotationProcessor.ProcessingStep in a BasicAnnotationProcessor.Step. This is a convenience method to allow incremental migration to a String-based API. This method can be used to return a not yet converted BasicAnnotationProcessor.ProcessingStep from steps().