98 * claims the annotation types 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
103 * that are present on the elements enclosed within the root elements.
104 * If there is at least one annotation type present, then as
105 * processors claim annotation types, they are removed from the set of
106 * unmatched annotation types. When the set is empty or no more
107 * processors are available, the round has run to completion. If
108 * there are no annotation types present, annotation processing still
109 * occurs but only <i>universal processors</i> which support
110 * processing all annotation types, {@code "*"}, can claim the (empty)
111 * set of annotation types.
112 *
113 * <p>An annotation type is considered present if there is at least
114 * one annotation of that type present on an element enclosed within
115 * the root elements of a round. For this purpose, a type parameter is
116 * considered to be enclosed by its {@linkplain
117 * TypeParameterElement#getGenericElement generic
118 * element}. Annotations on {@linkplain
119 * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
120 * annotations on elements, are ignored when computing whether or not
121 * an annotation type is present.
122 *
123 * <p>An annotation is present if it meets the definition of being
124 * present given in {@link AnnotatedConstruct}. In brief, an
125 * annotation is considered present for the purposes of discovery if
126 * it is directly present or present via inheritance. An annotation is
127 * <em>not</em> considered present by virtue of being wrapped by a
128 * container annotation. Operationally, this is equivalent to an
129 * annotation being present on an element if and only if it would be
130 * included in the results of {@link
131 * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
132 * annotations inside container annotations are not considered
133 * present, to properly process {@linkplain
134 * java.lang.annotation.Repeatable repeatable annotation types},
135 * processors are advised to include both the repeatable annotation
136 * type and its containing annotation type in the set of {@linkplain
137 * #getSupportedAnnotationTypes() supported annotation types} of a
138 * processor.
218 * <dd>Syntactic identifier, including keywords and literals
219 * </dl>
220 * </blockquote>
221 *
222 * <p> A tool might use this information to determine if any
223 * options provided by a user are unrecognized by any processor,
224 * in which case it may wish to report a warning.
225 *
226 * @return the options recognized by this processor or an
227 * empty collection if none
228 * @see javax.annotation.processing.SupportedOptions
229 */
230 Set<String> getSupportedOptions();
231
232 /**
233 * Returns the names of the annotation types supported by this
234 * processor. An element of the result may be the canonical
235 * (fully qualified) name of a supported annotation type.
236 * Alternately it may be of the form "<tt><i>name</i>.*</tt>"
237 * representing the set of all annotation types with canonical
238 * names beginning with "<tt><i>name.</i></tt>". Finally, {@code
239 * "*"} by itself represents the set of all annotation types,
240 * including the empty set. Note that a processor should not
241 * claim {@code "*"} unless it is actually processing all files;
242 * claiming unnecessary annotations may cause a performance
243 * slowdown in some environments.
244 *
245 * <p>Each string returned in the set must be accepted by the
246 * following grammar:
247 *
248 * <blockquote>
249 * <dl>
250 * <dt><i>SupportedAnnotationTypeString:</i>
251 * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
252 * <dd><tt>*</tt>
253 *
254 * <dt><i>DotStar:</i>
255 * <dd><tt>.</tt> <tt>*</tt>
256 * </dl>
257 * </blockquote>
258 *
259 * where <i>TypeName</i> is as defined in
260 * <cite>The Java™ Language Specification</cite>.
261 *
262 * @return the names of the annotation types supported by this processor
263 * @see javax.annotation.processing.SupportedAnnotationTypes
264 * @jls 3.8 Identifiers
265 * @jls 6.5.5 Meaning of Type Names
266 */
267 Set<String> getSupportedAnnotationTypes();
268
269 /**
270 * Returns the latest source version supported by this annotation
271 * processor.
272 *
|
98 * claims the annotation types 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
103 * that are present on the elements enclosed within the root elements.
104 * If there is at least one annotation type present, then as
105 * processors claim annotation types, they are removed from the set of
106 * unmatched annotation types. When the set is empty or no more
107 * processors are available, the round has run to completion. If
108 * there are no annotation types present, annotation processing still
109 * occurs but only <i>universal processors</i> which support
110 * processing all annotation types, {@code "*"}, can claim the (empty)
111 * set of annotation types.
112 *
113 * <p>An annotation type is considered present if there is at least
114 * one annotation of that type present on an element enclosed within
115 * the root elements of a round. For this purpose, a type parameter is
116 * considered to be enclosed by its {@linkplain
117 * TypeParameterElement#getGenericElement generic
118 * element}.
119
120 * For this purpose, a top-level type is <em>not</em> considered to be
121 * enclosed by its enclosing package. A root element representing a
122 * package is created when a {@code package-info} file is processed.
123 * Likewise, for this purpose, a package is <em>not</em> considered to
124 * be enclosed by its enclosing named module (if any). A root element
125 * representing a module is created when a {@code module-info} file is
126 * processed.
127
128 * Annotations on {@linkplain
129 * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
130 * annotations on elements, are ignored when computing whether or not
131 * an annotation type is present.
132 *
133 * <p>An annotation is present if it meets the definition of being
134 * present given in {@link AnnotatedConstruct}. In brief, an
135 * annotation is considered present for the purposes of discovery if
136 * it is directly present or present via inheritance. An annotation is
137 * <em>not</em> considered present by virtue of being wrapped by a
138 * container annotation. Operationally, this is equivalent to an
139 * annotation being present on an element if and only if it would be
140 * included in the results of {@link
141 * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
142 * annotations inside container annotations are not considered
143 * present, to properly process {@linkplain
144 * java.lang.annotation.Repeatable repeatable annotation types},
145 * processors are advised to include both the repeatable annotation
146 * type and its containing annotation type in the set of {@linkplain
147 * #getSupportedAnnotationTypes() supported annotation types} of a
148 * processor.
228 * <dd>Syntactic identifier, including keywords and literals
229 * </dl>
230 * </blockquote>
231 *
232 * <p> A tool might use this information to determine if any
233 * options provided by a user are unrecognized by any processor,
234 * in which case it may wish to report a warning.
235 *
236 * @return the options recognized by this processor or an
237 * empty collection if none
238 * @see javax.annotation.processing.SupportedOptions
239 */
240 Set<String> getSupportedOptions();
241
242 /**
243 * Returns the names of the annotation types supported by this
244 * processor. An element of the result may be the canonical
245 * (fully qualified) name of a supported annotation type.
246 * Alternately it may be of the form "<tt><i>name</i>.*</tt>"
247 * representing the set of all annotation types with canonical
248 * names beginning with "<tt><i>name.</i></tt>".
249 *
250 * In either of those cases, the name of the annotation type can be
251 * optionally be preceded by a module name followed by a {@code
252 * "/"} character. For example, if a processor supports {@code
253 * "a.B"}, this can include multiple annotation types named {@code
254 * a.B} which reside in different modules. To only support {@code
255 * a.B} in the {@code Foo} module, instead use {@code "Foo/a.B"}.
256 *
257 * Finally, {@code "*"} by itself represents the set of all
258 * annotation types, including the empty set. Note that a
259 * processor should not claim {@code "*"} unless it is actually
260 * processing all files; claiming unnecessary annotations may
261 * cause a performance slowdown in some environments.
262 *
263 * <p>Each string returned in the set must be accepted by the
264 * following grammar:
265 *
266 * <blockquote>
267 * <dl>
268 * <dt><i>SupportedAnnotationTypeString:</i>
269 * <dd><i>ModulePrefix</i><sub><i>opt</i></sub> <i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
270 * <dd><tt>*</tt>
271 *
272 * <dt><i>ModulePrefix:</i>
273 * <dd><i>TypeName</i> <tt>/</tt>
274 * </dl>
275 *
276 * <dt><i>DotStar:</i>
277 * <dd><tt>.</tt> <tt>*</tt>
278 * </dl>
279 * </blockquote>
280 *
281 * where <i>TypeName</i> is as defined in
282 * <cite>The Java™ Language Specification</cite>.
283 *
284 * @return the names of the annotation types supported by this processor
285 * @see javax.annotation.processing.SupportedAnnotationTypes
286 * @jls 3.8 Identifiers
287 * @jls 6.5.5 Meaning of Type Names
288 */
289 Set<String> getSupportedAnnotationTypes();
290
291 /**
292 * Returns the latest source version supported by this annotation
293 * processor.
294 *
|