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

  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 &quot;<tt><i>name</i>.*</tt>&quot;
 237      * representing the set of all annotation types with canonical
 238      * names beginning with &quot;<tt><i>name.</i></tt>&quot;.  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&trade; 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      *

   1 /*
   2  * Copyright (c) 2005, 2016, 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

  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 package element is <em>not</em> considered to
 121  * enclose the top-level types within that package. (A root element
 122  * representing a package is created when a {@code package-info} file
 123  * is processed.) Likewise, for this purpose, a module element is
 124  * <em>not</em> considered to enclose the packages within that
 125  * module. (A root element representing a module is created when a
 126  * {@code module-info} file is 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 &quot;<tt><i>name</i>.*</tt>&quot;
 247      * representing the set of all annotation types with canonical
 248      * names beginning with &quot;<tt><i>name.</i></tt>&quot;.
 249      *
 250      * In either of those cases, the name of the annotation type can
 251      * be optionally 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      *
 275      * <dt><i>DotStar:</i>
 276      * <dd><tt>.</tt> <tt>*</tt>
 277      * </dl>
 278      * </blockquote>
 279      *
 280      * where <i>TypeName</i> is as defined in
 281      * <cite>The Java&trade; Language Specification</cite>.
 282      *
 283      * @return the names of the annotation types supported by this processor
 284      * @see javax.annotation.processing.SupportedAnnotationTypes
 285      * @jls 3.8 Identifiers
 286      * @jls 6.5.5 Meaning of Type Names
 287      */
 288     Set<String> getSupportedAnnotationTypes();
 289 
 290     /**
 291      * Returns the latest source version supported by this annotation
 292      * processor.
 293      *