1 /*
2 * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.annotation.processing;
27
28 import java.util.Set;
29 import javax.lang.model.element.*;
30 import javax.lang.model.SourceVersion;
31
32 /**
33 * The interface for an annotation processor.
34 *
35 * <p>Annotation processing happens in a sequence of {@linkplain
36 * javax.annotation.processing.RoundEnvironment rounds}. On each
37 * round, a processor may be asked to {@linkplain #process process} a
38 * subset of the annotations found on the source and class files
39 * produced by a prior round. The inputs to the first round of
40 * processing are the initial inputs to a run of the tool; these
41 * initial inputs can be regarded as the output of a virtual zeroth
42 * round of processing. If a processor was asked to process on a
43 * given round, it will be asked to process on subsequent rounds,
44 * including the last round, even if there are no annotations for it
45 * to process. The tool infrastructure may also ask a processor to
46 * process files generated implicitly by the tool's operation.
47 *
48 * <p> Each implementation of a {@code Processor} must provide a
88 * configuration mechanisms, such as command line options; for
89 * details, refer to the particular tool's documentation. Which
90 * processors the tool asks to {@linkplain #process run} is a function
91 * of what annotations are present on the {@linkplain
92 * RoundEnvironment#getRootElements root elements}, what {@linkplain
93 * #getSupportedAnnotationTypes annotation types a processor
94 * processes}, and whether or not a processor {@linkplain #process
95 * claims the annotations it processes}. A processor will be asked to
96 * process a subset of the annotation types it supports, possibly an
97 * empty set.
98 *
99 * For a given round, the tool computes the set of annotation types on
100 * the root elements. If there is at least one annotation type
101 * present, as processors claim annotation types, they are removed
102 * from the set of unmatched annotations. When the set is empty or no
103 * more processors are available, the round has run to completion. If
104 * there are no annotation types present, annotation processing still
105 * occurs but only <i>universal processors</i> which support
106 * processing {@code "*"} can claim the (empty) set of annotation
107 * types.
108 *
109 * <p>Note that if a processor supports {@code "*"} and returns {@code
110 * true}, all annotations are claimed. Therefore, a universal
111 * processor being used to, for example, implement additional validity
112 * checks should return {@code false} so as to not prevent other such
113 * checkers from being able to run.
114 *
115 * <p>If a processor throws an uncaught exception, the tool may cease
116 * other active annotation processors. If a processor raises an
117 * error, the current round will run to completion and the subsequent
118 * round will indicate an {@linkplain RoundEnvironment#errorRaised
119 * error was raised}. Since annotation processors are run in a
120 * cooperative environment, a processor should throw an uncaught
121 * exception only in situations where no error recovery or reporting
122 * is feasible.
123 *
124 * <p>The tool environment is not required to support annotation
125 * processors that access environmental resources, either {@linkplain
126 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
127 * cross-round}, in a multi-threaded fashion.
|
1 /*
2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.annotation.processing;
27
28 import java.util.Set;
29 import javax.lang.model.util.Elements;
30 import javax.lang.model.element.*;
31 import javax.lang.model.SourceVersion;
32
33 /**
34 * The interface for an annotation processor.
35 *
36 * <p>Annotation processing happens in a sequence of {@linkplain
37 * javax.annotation.processing.RoundEnvironment rounds}. On each
38 * round, a processor may be asked to {@linkplain #process process} a
39 * subset of the annotations found on the source and class files
40 * produced by a prior round. The inputs to the first round of
41 * processing are the initial inputs to a run of the tool; these
42 * initial inputs can be regarded as the output of a virtual zeroth
43 * round of processing. If a processor was asked to process on a
44 * given round, it will be asked to process on subsequent rounds,
45 * including the last round, even if there are no annotations for it
46 * to process. The tool infrastructure may also ask a processor to
47 * process files generated implicitly by the tool's operation.
48 *
49 * <p> Each implementation of a {@code Processor} must provide a
89 * configuration mechanisms, such as command line options; for
90 * details, refer to the particular tool's documentation. Which
91 * processors the tool asks to {@linkplain #process run} is a function
92 * of what annotations are present on the {@linkplain
93 * RoundEnvironment#getRootElements root elements}, what {@linkplain
94 * #getSupportedAnnotationTypes annotation types a processor
95 * processes}, and whether or not a processor {@linkplain #process
96 * claims the annotations it processes}. A processor will be asked to
97 * process a subset of the annotation types it supports, possibly an
98 * empty set.
99 *
100 * For a given round, the tool computes the set of annotation types on
101 * the root elements. If there is at least one annotation type
102 * present, as processors claim annotation types, they are removed
103 * from the set of unmatched annotations. When the set is empty or no
104 * more processors are available, the round has run to completion. If
105 * there are no annotation types present, annotation processing still
106 * occurs but only <i>universal processors</i> which support
107 * processing {@code "*"} can claim the (empty) set of annotation
108 * types.
109 *
110 * <p>An annotation type is considered present if there is an
111 * annotation of that type on a declaration enclosed within the root
112 * elements of a round. For this purpose, a type parameter is
113 * considered to be enclosed by its {@linkplain
114 * TypeParameter#getGenericElement generic element}. Annotations on
115 * {@linkplain ElementType#TYPE_USE type uses} are <em>not</em>
116 * considered as part of the computation. To be present, an annotation
117 * must be returnable by {@link Elements#getAllAnnotationMirrors()},
118 * that is, the annotation must be present on the declaration of the
119 * element or present via inheritance. An annotation is <em>not</em>
120 * considered present by virtue of being wrapped by a container
121 * annotation. Therefore, to properly process {@linkplain
122 * java.lang.annotation.Repeatable repeatable annotation types},
123 * processors are advised to include both the annotation and its
124 * container in the set of {@linkplain #getSupportedAnnotationTypes()
125 * supported annotation types}.
126 *
127 * <p>Note that if a processor supports {@code "*"} and returns {@code
128 * true}, all annotations are claimed. Therefore, a universal
129 * processor being used to, for example, implement additional validity
130 * checks should return {@code false} so as to not prevent other such
131 * checkers from being able to run.
132 *
133 * <p>If a processor throws an uncaught exception, the tool may cease
134 * other active annotation processors. If a processor raises an
135 * error, the current round will run to completion and the subsequent
136 * round will indicate an {@linkplain RoundEnvironment#errorRaised
137 * error was raised}. Since annotation processors are run in a
138 * cooperative environment, a processor should throw an uncaught
139 * exception only in situations where no error recovery or reporting
140 * is feasible.
141 *
142 * <p>The tool environment is not required to support annotation
143 * processors that access environmental resources, either {@linkplain
144 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
145 * cross-round}, in a multi-threaded fashion.
|