Author: kentam
Date: Tue Jul 20 18:28:04 2004
New Revision: 23106
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlAnnotationProcessor.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlClientAnnotationProcessor.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/TwoPhaseAnnotationProcessor.java
Log:
Refine TwoPhaseAnnotationProcessor API and add additional Javadocs.
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlAnnotationProcessor.java
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlAnnotationProcessor.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlAnnotationProcessor.java
Tue Jul 20 18:28:04 2004
@@ -32,49 +32,8 @@
super(atds, env);
}
- /**
- * Returns the CodeGenerator instance supporting this processor,
instantiaiting a new
- * generator instance if necessary.
- */
- public CodeGenerator getGenerator()
- {
- if (_generator == null)
- {
- //
- // Locate the class that wraps the Velocity code generation process
- //
- AnnotationProcessorEnvironment env =
getAnnotationProcessorEnvironment();
- String generatorName = null;
-
- // BUGBUG: getting the name should be as easy as the code below...
but for some
- // reason the APT option processing is busted, and doesn't parse
-A keys correctly.
- // The entire value of the -Aoption will be the key, and the value
will be 'null'
- // generatorName = env.getOptions().get("-AcontrolGenerator");
- for (String keyName : env.getOptions().keySet())
- {
- if (keyName.startsWith("-AcontrolGenerator="))
- {
- generatorName = keyName.substring(19);
- break;
- }
- }
-
- if (generatorName == null)
- generatorName =
"org.apache.beehive.controls.runtime.generator.VelocityGenerator";
- try
- {
- Class generatorClass = Class.forName(generatorName);
- _generator = (CodeGenerator)generatorClass.newInstance();
- }
- catch (Exception e)
- {
- throw new CodeGenerationException("Unable to create code
generator", e);
- }
- }
- return _generator;
- }
-
- public String [] check(Declaration decl)
+ @Override
+ public void check(Declaration decl)
{
AnnotationProcessorEnvironment env =
getAnnotationProcessorEnvironment();
GenClass genClass = null;
@@ -93,12 +52,11 @@
if (genClass != null)
{
_typeMap.put(decl, genClass);
- return genClass.getGeneratedTypes();
}
- return null;
}
- public void generate(Declaration decl) throws CodeGenerationException
+ @Override
+ public void generate(Declaration decl)
{
GenClass genClass = _typeMap.get(decl);
if (genClass == null)
@@ -120,6 +78,48 @@
{
throw new CodeGenerationException("Code generation failure: ",
ioe);
}
+ }
+
+ /**
+ * Returns the CodeGenerator instance supporting this processor,
instantiating a new
+ * generator instance if necessary.
+ */
+ protected CodeGenerator getGenerator()
+ {
+ if (_generator == null)
+ {
+ //
+ // Locate the class that wraps the Velocity code generation process
+ //
+ AnnotationProcessorEnvironment env =
getAnnotationProcessorEnvironment();
+ String generatorName = null;
+
+ // BUGBUG: getting the name should be as easy as the code below...
but for some
+ // reason the APT option processing is busted, and doesn't parse
-A keys correctly.
+ // The entire value of the -Aoption will be the key, and the value
will be 'null'
+ // generatorName = env.getOptions().get("-AcontrolGenerator");
+ for (String keyName : env.getOptions().keySet())
+ {
+ if (keyName.startsWith("-AcontrolGenerator="))
+ {
+ generatorName = keyName.substring(19);
+ break;
+ }
+ }
+
+ if (generatorName == null)
+ generatorName =
"org.apache.beehive.controls.runtime.generator.VelocityGenerator";
+ try
+ {
+ Class generatorClass = Class.forName(generatorName);
+ _generator = (CodeGenerator)generatorClass.newInstance();
+ }
+ catch (Exception e)
+ {
+ throw new CodeGenerationException("Unable to create code
generator", e);
+ }
+ }
+ return _generator;
}
HashMap<Declaration, GenClass> _typeMap = new
HashMap<Declaration,GenClass>();
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlClientAnnotationProcessor.java
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlClientAnnotationProcessor.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/ControlClientAnnotationProcessor.java
Tue Jul 20 18:28:04 2004
@@ -28,20 +28,19 @@
super( atds,env );
}
- public void generate(Declaration decl) throws CodeGenerationException
- {
- }
-
-
- public String[] check( Declaration d )
+ @Override
+ public void check( Declaration d )
{
if ( d instanceof FieldDeclaration )
checkControlField( (FieldDeclaration)d );
// if @Control is used on something other than a field, the Java lang
// checker should produce an error due to the @Target violation.
+ }
- return null;
+ @Override
+ public void generate(Declaration decl)
+ {
}
private void checkControlField( FieldDeclaration f )
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/TwoPhaseAnnotationProcessor.java
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/TwoPhaseAnnotationProcessor.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/generator/apt/TwoPhaseAnnotationProcessor.java
Tue Jul 20 18:28:04 2004
@@ -24,20 +24,34 @@
* <p>
* The two phases of processing are:
* <ul>
- * <li>The <b>check</b> phase is used to validate an input Declaration that
has been
- * annotated with annotation claimed by the processor to ensure that it
- * is semantically valid.
- * <li>The <b>generate</b> phase will actually generate any source, binary, or
class files
- * that are derived from the input Declaration.
+ * <li>The <b>check</b> phase is used to validate input Declarations that have
been
+ * annotated with annotations claimed by the processor to ensure that it
+ * is semantically valid. 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.
+ * <li>The <b>generate</b> phase will actually emit any source, binary, or
class files
+ * that are derived from the input Declaration, including files added via the
Filer
+ * API during the check phase. The Filer API may also be used in this phase
to add
+ * new files, however, such additions will not be visible during the check
phase of
+ * any Declarations.
* </ul>
+ * <p>
* The benefits of breaking process() down into check() and generate() phases
are:
* <ol>
* <li>Makes it possible to perform the semantic validation of Declarations
without
- * necessary resulting in code generation.
- * <li>Provides a clearer association between input Declarations and generator
output,
- * because the check() phase will return the list of new canonical types that
will be
- * produced by calling generate().
+ * necessarily resulting in code generation.
+ * <li>Provides a clearer association between input Declarations and generator
output.
* </ol>
+ * 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).
*/
abstract public class TwoPhaseAnnotationProcessor implements
AnnotationProcessor
{
@@ -49,44 +63,68 @@
}
/**
- * Implements the AnnotationProcessor.process interface. This is done by
interating
- * over the lilst of AnnotationTypeDeclarations for the processor, and
calling the
- * check() and generate() methods on them.
+ * Implements AnnotationProcessor.process() as two phases, "check" and
"generate".
*/
public void process()
{
+ check();
+ generate();
+ }
+
+ /**
+ * Performs semantic validation of input Declarations that are annotated
with
+ * annotations claimed by this AnnotationProcessor.
+ */
+ public void check()
+ {
for (AnnotationTypeDeclaration atd : _atds)
{
Collection<Declaration> decls =
_env.getDeclarationsAnnotatedWith(atd);
for (Declaration decl : decls)
{
check(decl);
- generate(decl);
}
}
}
/**
+ * Emits additional artifacts for input Declarations that are annotated
with
+ * annotations claimed by this AnnotationProcessor.
+ */
+ public void generate() throws CodeGenerationException
+ {
+ for (AnnotationTypeDeclaration atd : _atds)
+ {
+ Collection<Declaration> decls =
_env.getDeclarationsAnnotatedWith(atd);
+ for (Declaration decl : decls)
+ {
+ generate(decl);
+ }
+ }
+ }
+
+ /**
* The check method is responsible for all semantic validation of the
input Declaration.
- * The return value of the check method is a String array containing the
canonical (fully
- * qualified) names of new types that will be result from calling the
generate method), or
- * null if processing does not result in the generation of new types.
This (a null return
- * value) should not be used as an indicator of whether it is necessary to
call generate;
- * it is still possible that other non-type artifacts (text or binary
files) may result
- * from generation.
* <p>
- * <b>All semantic warnings/errors associated with the input Declaration
- * AnnotationProcessEnvironment during the check phase.</b>
+ * All semantic warnings/errors associated with the input Declaration
should
+ * be output during check via a Messager obtained from the
+ * AnnotationProcessorEnvironment.
+ * <p>
+ * 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.
*/
- abstract public String [] check(Declaration decl);
+ abstract public void check(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.
- * <p>
- * <b>The generate method must use the return value of
*/
- abstract public void generate(Declaration decl) throws
CodeGenerationException;
+ abstract public void generate(Declaration decl);
protected AnnotationProcessorEnvironment
getAnnotationProcessorEnvironment()
{
