KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > beehive > wsm > processor > apt > TwoPhaseAnnotationProcessor


1 package org.apache.beehive.wsm.processor.apt;
2
3 /*
4  * Copyright 2004 The Apache Software Foundation
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  *
18  * $Header:$
19  */
20
21 import java.util.Collection JavaDoc;
22 import java.util.Set JavaDoc;
23
24 import com.sun.mirror.apt.AnnotationProcessor;
25 import com.sun.mirror.apt.AnnotationProcessorEnvironment;
26 import com.sun.mirror.declaration.AnnotationTypeDeclaration;
27 import com.sun.mirror.declaration.Declaration;
28 import org.apache.beehive.wsm.processor.ProcessorException;
29
30 /**
31  * The TwoPhaseAnnotationProcessor class is an abstract class that implements the APT
32  * AnnotationProcessor interface. It breaks the work of the process() method of the
33  * AnnotationProcessor down into two distinct phases, represented as abstract method
34  * of TwoPhaseAnnotationProcessor that are to be implemented by concrete subclasses.
35  * The two phases of processing are:
36  * <ul>
37  * <li>The <b>check</b> phase is used to validate input Declarations that have been
38  * annotated with annotations claimed by the processor to ensure that it
39  * is semantically valid. If the presence of the input Declaration implies the need
40  * to add new files, and those files need to be visible during the check phase for
41  * other Declarations, then the AnnotationProcessorEnvironment's Filer API should be
42  * used to add those files in this phase. The adding of such files at this point
43  * should typically not result in their emission to persistent storage (i.e. disk),
44  * but rather be kept in memory to be referenced by the check phase of other
45  * Declarations.
46  * <li>The <b>generate</b> phase will actually emit any source, binary, or class files
47  * that are derived from the input Declaration, including files added via the Filer
48  * API during the check phase. The Filer API may also be used in this phase to add
49  * new files, however, such additions will not be visible during the check phase of
50  * any Declarations.
51  * </ul>
52  * The benefits of breaking process() down into check() and generate() phases are:
53  * <ol>
54  * <li>Makes it possible to perform the semantic validation of Declarations without
55  * necessarily resulting in code generation.
56  * <li>Provides a clearer association between input Declarations and generator output.
57  * </ol>
58  * TwoPhaseAnnotationProcessor is intended provide a uniform mechanism for writing
59  * AnnotationProcessor implementations that can be used in tooling environments more
60  * sophisticated than command-line tools (that may not do all their work on source
61  * in a single pass). Such environments will typically also provide implementations
62  * of the AnnotationProcessorEnvironment and associated interfaces (Messager,
63  * Filer etc).
64  */
65 abstract public class TwoPhaseAnnotationProcessor implements AnnotationProcessor {
66     public TwoPhaseAnnotationProcessor(Set JavaDoc<AnnotationTypeDeclaration> atds,
67                                        AnnotationProcessorEnvironment env) {
68         _atds = atds;
69         _env = env;
70     }
71
72     /**
73      * Implements AnnotationProcessor.process() as two phases, "check" and "generate".
74      */
75     public void process() {
76         check();
77         generate();
78     }
79
80     /**
81      * Performs semantic validation of input Declarations that are annotated with
82      * annotations claimed by this AnnotationProcessor.
83      */
84     public void check() {
85         for (AnnotationTypeDeclaration atd : _atds) {
86             Collection JavaDoc<Declaration> decls = _env.getDeclarationsAnnotatedWith(atd);
87             for (Declaration decl : decls) {
88                 check(decl);
89             }
90         }
91     }
92
93     /**
94      * Emits additional artifacts for input Declarations that are annotated with
95      * annotations claimed by this AnnotationProcessor.
96      */
97     public void generate() throws ProcessorException {
98         for (AnnotationTypeDeclaration atd : _atds) {
99             Collection JavaDoc<Declaration> decls = _env.getDeclarationsAnnotatedWith(atd);
100             for (Declaration decl : decls) {
101                 generate(decl);
102             }
103         }
104     }
105
106     /**
107      * The check method is responsible for all semantic validation of the input Declaration.
108      * All semantic warnings/errors associated with the input Declaration should
109      * be output during check via a Messager obtained from the
110      * AnnotationProcessorEnvironment.
111      * If the presence of the input Declaration implies the need to add new files,
112      * and those files need to be visible during the check phase for
113      * other Declarations, then the AnnotationProcessorEnvironment's Filer API should be
114      * used to add those files in this phase. The adding of such files at this point
115      * should typically not result in their emission to persistent storage (i.e. disk),
116      * but rather be kept in memory to be referenced by the check phase of other
117      * Declarations.
118      */
119     abstract public void check(Declaration decl);
120
121     /**
122      * The generate method is responsible for the generation of any additional artifacts
123      * (source, class, or binary) that are derived from the input Declaration.
124      */
125     abstract public void generate(Declaration decl);
126
127     protected AnnotationProcessorEnvironment getAnnotationProcessorEnvironment() {
128         return _env;
129     }
130
131     Set JavaDoc<AnnotationTypeDeclaration> _atds;
132     AnnotationProcessorEnvironment _env;
133 }
134
Popular Tags