The RoundEnvironment and Processing Rounds
You'll learn how annotation processing works in multiple rounds and how RoundEnvironment gives you access to annotated elements during each round.
How Annotation Processing Happens in Rounds
Annotation processing doesn't happen all at once—it occurs in rounds. Think of it like multiple passes through your code: in each round, the processor examines elements, potentially generates new files, and those new files might trigger another round if they contain annotations.
Here's how it works:
- Round 1: The compiler invokes your processor with all initial source files. Your processor examines annotated elements and may generate new source files.
- Round 2+: If new files were generated, the compiler processes them and calls your processor again with the newly created elements.
- Final Round: When no new files are generated, a final round occurs with
processingOver()returningtrue.
The RoundEnvironment Object
RoundEnvironment is passed to your processor's process() method each round. It provides:
- Access to annotated elements:
getElementsAnnotatedWith(MyAnnotation.class)returns all elements carrying that annotation in this round - Root elements:
getRootElements()gives you all top-level types being compiled this round - Round status:
processingOver()tells you if this is the final round - Error checking:
errorRaised()indicates if errors occurred in previous rounds
Each round is isolated—you only see the elements relevant to that specific pass. This allows processors to generate code incrementally, with each generation potentially creating new annotated elements for subsequent rounds.
Key Takeaway:
Annotation processing happens in rounds managed by the compiler, and RoundEnvironment is your window into each round, providing access to annotated elements and round status information.