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 abstract Processor implementation that defers processing of Elements 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 the initSteps() 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 ProcessingStep. 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 ProcessingStep can defer elements

Each ProcessingStep can defer elements by including them in the set returned by BasicAnnotationProcessor.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 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	Description
private static final class	BasicAnnotationProcessor.ElementName	A package or type name.
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

Modifier and Type	Field	Description
private final Set<BasicAnnotationProcessor.ElementName>	deferredElementNames
private Elements	elements
private final com.google.common.collect.SetMultimap<BasicAnnotationProcessor.ProcessingStep, BasicAnnotationProcessor.ElementName>	elementsDeferredBySteps
private Messager	messager
private com.google.common.collect.ImmutableList<? extends BasicAnnotationProcessor.ProcessingStep>	steps

Fields inherited from class AbstractProcessor

processingEnv

Constructor Summary

Constructors

Constructor	Description
BasicAnnotationProcessor()

Method Summary

Modifier and Type	Method	Description
private com.google.common.collect.ImmutableMap<String, com.google.common.base.Optional<? extends Element>>	deferredElements()	Returns the previously deferred elements.
private static void	findAnnotatedElements(Element element, com.google.common.collect.ImmutableSet<? extends Class<? extends Annotation>> annotationClasses, com.google.common.collect.ImmutableSetMultimap.Builder<Class<? extends Annotation>, Element> annotatedElements)	Adds element and its enclosed elements to annotatedElements if they are annotated with any annotations in annotationClasses.
private static TypeElement	getEnclosingType(Element element)	Returns the nearest enclosing TypeElement to the current element, throwing an IllegalArgumentException if the provided Element is a PackageElement or is otherwise not enclosed by a type.
private com.google.common.collect.ImmutableSet<? extends Class<? extends Annotation>>	getSupportedAnnotationClasses()
final com.google.common.collect.ImmutableSet<String>	getSupportedAnnotationTypes()	Returns the set of supported annotation types as a collected from registered processing steps.
private com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element>	indexByAnnotation(Set<BasicAnnotationProcessor.ElementName> annotatedElements)
final void	init(ProcessingEnvironment processingEnv)
protected abstract Iterable<? extends BasicAnnotationProcessor.ProcessingStep>	initSteps()	Creates processing steps for this processor.
protected void	postProcess()	Deprecated. use postRound(RoundEnvironment) instead
protected void	postRound(RoundEnvironment roundEnv)	An optional hook for logic to be executed at the end of each round.
private void	process(com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element> validElements)	Processes the valid elements, including those previously deferred by each step.
final boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
private String	processingErrorMessage(String target)
private void	reportMissingElements(Map<String, ? extends com.google.common.base.Optional<? extends Element>> missingElements, Collection<BasicAnnotationProcessor.ElementName> missingElementNames)
private com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element>	validElements(com.google.common.collect.ImmutableMap<String, com.google.common.base.Optional<? extends Element>> deferredElements, RoundEnvironment roundEnv)	Returns the valid annotated elements contained in all of the deferred elements.

Methods inherited from class AbstractProcessor

getCompletions, getSupportedOptions, getSupportedSourceVersion, isInitialized

Methods inherited from class Object

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

Field Details

deferredElementNames

private final Set<BasicAnnotationProcessor.ElementName> deferredElementNames

elementsDeferredBySteps

private final com.google.common.collect.SetMultimap<BasicAnnotationProcessor.ProcessingStep, BasicAnnotationProcessor.ElementName> elementsDeferredBySteps

elements

private Elements elements

messager

private Messager messager

steps

private com.google.common.collect.ImmutableList<? extends BasicAnnotationProcessor.ProcessingStep> steps

Constructor Details

BasicAnnotationProcessor

public BasicAnnotationProcessor()

Method Details

init

public final void init(ProcessingEnvironment processingEnv)

Specified by:

init in interface Processor

Overrides:

init in class AbstractProcessor

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

@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(RoundEnvironment roundEnv)

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

getSupportedAnnotationClasses

private com.google.common.collect.ImmutableSet<? extends Class<? extends Annotation>> getSupportedAnnotationClasses()

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 interface Processor

Overrides:

getSupportedAnnotationTypes in class AbstractProcessor

process

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

Specified by:

process in interface Processor

Specified by:

process in class AbstractProcessor

deferredElements

private com.google.common.collect.ImmutableMap<String, com.google.common.base.Optional<? extends Element>> deferredElements()

Returns the previously deferred elements.

reportMissingElements

private void reportMissingElements(Map<String, ? extends com.google.common.base.Optional<? extends Element>> missingElements,
 Collection<BasicAnnotationProcessor.ElementName> missingElementNames)

processingErrorMessage

private String processingErrorMessage(String target)

validElements

private com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element> validElements(com.google.common.collect.ImmutableMap<String, com.google.common.base.Optional<? extends Element>> deferredElements,
 RoundEnvironment roundEnv)

Returns the valid annotated elements contained in all of the deferred elements. If none are found for a deferred element, defers it again.

process

private void process(com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element> validElements)

Processes the valid elements, including those previously deferred by each step.

indexByAnnotation

private com.google.common.collect.ImmutableSetMultimap<Class<? extends Annotation>, Element> indexByAnnotation(Set<BasicAnnotationProcessor.ElementName> annotatedElements)

findAnnotatedElements

private static void findAnnotatedElements(Element element,
 com.google.common.collect.ImmutableSet<? extends Class<? extends Annotation>> annotationClasses,
 com.google.common.collect.ImmutableSetMultimap.Builder<Class<? extends Annotation>, Element> annotatedElements)

Adds element and its enclosed elements to annotatedElements if they are annotated with any annotations in annotationClasses. Does not traverse to member types of element, so that if Outer is passed in the example below, looking for @X, then Outer, Outer.foo, and Outer.foo() will be added to the multimap, but neither Inner nor its members will.

  @X class Outer {
    @X Object foo;
    @X void foo() {}
    @X static class Inner {
      @X Object bar;
      @X void bar() {}
    }
  }

getEnclosingType

private static TypeElement getEnclosingType(Element element)

Returns the nearest enclosing TypeElement to the current element, throwing an IllegalArgumentException if the provided Element is a PackageElement or is otherwise not enclosed by a type.