org.apache.beehive.controls.runtime.generator.apt
Class TwoPhaseAnnotationProcessor

Object
  extended by Diagnostics
      extended by TwoPhaseAnnotationProcessor
All Implemented Interfaces:
AnnotationProcessor
Direct Known Subclasses:
ControlAnnotationProcessor, ControlClientAnnotationProcessor, ControlMemberTypeAnnotationProcessor, ControlSecondaryAnnotationProcessor

public abstract class TwoPhaseAnnotationProcessor
extends Diagnostics
implements AnnotationProcessor

The TwoPhaseAnnotationProcessor class is an abstract class that implements the APT AnnotationProcessor interface. It breaks the work of the process() method of the AnnotationProcessor down into two distinct phases, represented as abstract method of TwoPhaseAnnotationProcessor that are to be implemented by concrete subclasses.

The two phases of processing are:

The benefits of breaking process() down into check() and generate() phases are:

  1. Makes it possible to perform the semantic validation of Declarations without necessarily resulting in code generation.
  2. Provides a clearer association between input Declarations and generator output.
TwoPhaseAnnotationProcessor is intended provide a uniform mechanism for writing AnnotationProcessor implementations that can be used in tooling environments more sophisticated than command-line tools (that may not do all their work on source in a single pass). Such environments will typically also provide implementations of the AnnotationProcessorEnvironment and associated interfaces (Messager, Filer etc).


Constructor Summary
TwoPhaseAnnotationProcessor(Set<AnnotationTypeDeclaration> atds, AnnotationProcessorEnvironment env)
           
 
Method Summary
 void check()
          Performs semantic validation of input Declarations that are annotated with annotations claimed by this AnnotationProcessor.
abstract  void check(Declaration decl)
          The check method is responsible for all semantic validation of the input Declaration.
 void generate()
          Emits additional artifacts for input Declarations that are annotated with annotations claimed by this AnnotationProcessor.
abstract  void generate(Declaration decl)
          The generate method is responsible for the generation of any additional artifacts (source, class, or binary) that are derived from the input Declaration.
protected  String getResourceString(String id, Object... args)
           
 void printError(Declaration d, String id, Object... args)
          Report an error detected during the "check" phase.
 void printWarning(Declaration d, String id, Object... args)
          Report a warning detected during the "check" phase.
 void process()
          Implements AnnotationProcessor.process() as two phases, "check" and "generate".
 
Methods inherited from class Diagnostics
addError, addError, addError, addErrorArrayArgs, addWarning, addWarning, addWarning, getAnnotationProcessorEnvironment, hasErrors, setHasErrors
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TwoPhaseAnnotationProcessor

public TwoPhaseAnnotationProcessor(Set<AnnotationTypeDeclaration> atds,
                                   AnnotationProcessorEnvironment env)
Method Detail

process

public void process()
Implements AnnotationProcessor.process() as two phases, "check" and "generate". "generate" will not be called if "check" emitted any errors (via printError()).

Specified by:
process in interface AnnotationProcessor

check

public void check()
Performs semantic validation of input Declarations that are annotated with annotations claimed by this AnnotationProcessor.


generate

public void generate()
              throws CodeGenerationException
Emits additional artifacts for input Declarations that are annotated with annotations claimed by this AnnotationProcessor.

Throws:
CodeGenerationException

check

public abstract void check(Declaration decl)
The check method is responsible for all semantic validation of the input Declaration.

All semantic errors/warnings associated with the input Declaration should be output during check via the printError(com.sun.mirror.declaration.Declaration, java.lang.String, java.lang.Object...) and printWarning(com.sun.mirror.declaration.Declaration, java.lang.String, java.lang.Object...) methods. If an implementation bypasses printError, it must override Diagnostics.hasErrors() to ensure correct behaviour.

If the presence of the input Declaration implies the need to add new files, and those files need to be visible during the check phase for other Declarations, then the AnnotationProcessorEnvironment's Filer API should be used to add those files in this phase. The adding of such files at this point should typically not result in their emission to persistent storage (i.e. disk), but rather be kept in memory to be referenced by the check phase of other Declarations.


generate

public abstract void generate(Declaration decl)
The generate method is responsible for the generation of any additional artifacts (source, class, or binary) that are derived from the input Declaration.


printError

public void printError(Declaration d,
                       String id,
                       Object... args)
Report an error detected during the "check" phase. The presence of errors will suppress execution of the "generate" phase.


printWarning

public void printWarning(Declaration d,
                         String id,
                         Object... args)
Report a warning detected during the "check" phase. The presence of warnings will not affect execution of the "generate" phase.


getResourceString

protected String getResourceString(String id,
                                   Object... args)
Specified by:
getResourceString in class Diagnostics