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
71 *
72 * </ol>
73 *
74 * If a processor object is created and used without the above
75 * protocol being followed, then the processor's behavior is not
76 * defined by this interface specification.
77 *
78 * <p> The tool uses a <i>discovery process</i> to find annotation
79 * processors and decide whether or not they should be run. By
80 * configuring the tool, the set of potential processors can be
81 * controlled. For example, for a {@link javax.tools.JavaCompiler
82 * JavaCompiler} the list of candidate processors to run can be
83 * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
84 * set directly} or controlled by a {@linkplain
85 * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
86 * used for a {@linkplain java.util.ServiceLoader service-style}
87 * lookup. Other tool implementations may have different
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.AnnotatedConstruct;
31 import javax.lang.model.element.*;
32 import javax.lang.model.SourceVersion;
33
34 /**
35 * The interface for an annotation processor.
36 *
37 * <p>Annotation processing happens in a sequence of {@linkplain
38 * javax.annotation.processing.RoundEnvironment rounds}. On each
39 * round, a processor may be asked to {@linkplain #process process} a
40 * subset of the annotations found on the source and class files
41 * produced by a prior round. The inputs to the first round of
42 * processing are the initial inputs to a run of the tool; these
43 * initial inputs can be regarded as the output of a virtual zeroth
44 * round of processing. If a processor was asked to process on a
45 * given round, it will be asked to process on subsequent rounds,
46 * including the last round, even if there are no annotations for it
47 * to process. The tool infrastructure may also ask a processor to
48 * process files generated implicitly by the tool's operation.
49 *
50 * <p> Each implementation of a {@code Processor} must provide a
73 *
74 * </ol>
75 *
76 * If a processor object is created and used without the above
77 * protocol being followed, then the processor's behavior is not
78 * defined by this interface specification.
79 *
80 * <p> The tool uses a <i>discovery process</i> to find annotation
81 * processors and decide whether or not they should be run. By
82 * configuring the tool, the set of potential processors can be
83 * controlled. For example, for a {@link javax.tools.JavaCompiler
84 * JavaCompiler} the list of candidate processors to run can be
85 * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
86 * set directly} or controlled by a {@linkplain
87 * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
88 * used for a {@linkplain java.util.ServiceLoader service-style}
89 * lookup. Other tool implementations may have different
90 * configuration mechanisms, such as command line options; for
91 * details, refer to the particular tool's documentation. Which
92 * processors the tool asks to {@linkplain #process run} is a function
93 * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em>
94 * on the {@linkplain
95 * RoundEnvironment#getRootElements root elements}, what {@linkplain
96 * #getSupportedAnnotationTypes annotation types a processor
97 * processes}, and whether or not a processor {@linkplain #process
98 * claims the annotations it processes}. A processor will be asked to
99 * process a subset of the annotation types it supports, possibly an
100 * empty set.
101 *
102 * For a given round, the tool computes the set of annotation types on
103 * the root elements. If there is at least one annotation type
104 * present, as processors claim annotation types, they are removed
105 * from the set of unmatched annotations. When the set is empty or no
106 * more processors are available, the round has run to completion. If
107 * there are no annotation types present, annotation processing still
108 * occurs but only <i>universal processors</i> which support
109 * processing {@code "*"} can claim the (empty) set of annotation
110 * types.
111 *
112 * <p>An annotation type is considered present if there is at least
113 * one annotation of that type present on an element enclosed within
114 * the root elements of a round. Annotations on {@linkplain
115 * ElementType#TYPE_USE type uses} are <em>not</em> considered as part
116 * of the computation. For this purpose, a type parameter is
117 * considered to be enclosed by its {@linkplain
118 * TypeParameter#getGenericElement generic element}. An annotation is
119 * present if it meets the definition of being present given in {@link
120 * AnnotatedConstruct}. In brief, an annotation is considered present
121 * for the purposes of discovery if it is directly present or present
122 * via inheritance. An annotation is <em>not</em> considered present
123 * by virtue of being wrapped by a container
124 * annotation. Operationally, this is equivalent to an annotation
125 * being present on an element if and only if it would be included in
126 * the results of {@link Elements#getAllAnnotationMirrors()} called on
127 * that element. Since annotations inside container annotations are
128 * not considered present, to properly process {@linkplain
129 * java.lang.annotation.Repeatable repeatable annotation types},
130 * processors are advised to include both the annotation and its
131 * container in the set of {@linkplain #getSupportedAnnotationTypes()
132 * supported annotation types} of a processor.
133 *
134 * <p>Note that if a processor supports {@code "*"} and returns {@code
135 * true}, all annotations are claimed. Therefore, a universal
136 * processor being used to, for example, implement additional validity
137 * checks should return {@code false} so as to not prevent other such
138 * checkers from being able to run.
139 *
140 * <p>If a processor throws an uncaught exception, the tool may cease
141 * other active annotation processors. If a processor raises an
142 * error, the current round will run to completion and the subsequent
143 * round will indicate an {@linkplain RoundEnvironment#errorRaised
144 * error was raised}. Since annotation processors are run in a
145 * cooperative environment, a processor should throw an uncaught
146 * exception only in situations where no error recovery or reporting
147 * is feasible.
148 *
149 * <p>The tool environment is not required to support annotation
150 * processors that access environmental resources, either {@linkplain
151 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
152 * cross-round}, in a multi-threaded fashion.
|