stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8213256: Clarify runtime vs compile time annotations for RoundEnvironment.getElementsAnnotatedWith(Class)

Browse Source 
Reviewed-by: jjg, jlahoda
This commit is contained in:
Joe Darcy 2018-11-02 18:49:10 -07:00
parent 4b813da8c8
commit 24d201cb54
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
View File

@ -143,11 +143,26 @@ public interface RoundEnvironment {
* simply because a {@code module-info} file for that module was * simply because a {@code module-info} file for that module was
* created. * created.
* *
* <p> Note: An implementation of this method typically performs
* an internal conversion from the runtime reflective
* representation of an annotation type as a {@code Class} object
* to a different representation used for annotation
* processing. The set of annotation types present in the runtime
* context may differ from the set of annotation types present in
* the context of annotation processing in a particular
* environmental configuration. If an runtime annotation type is
* not present in the annotation processing context, the situation
* is not treated as an error and no elements are found for that
* annotation type.
*
* @param a annotation type being requested * @param a annotation type being requested
* @return the elements annotated with the given annotation type, * @return the elements annotated with the given annotation type,
* or an empty set if there are none * or an empty set if there are none
* @throws IllegalArgumentException if the argument does not * @throws IllegalArgumentException if the argument does not
* represent an annotation type * represent an annotation type
*
* @see javax.lang.model.AnnotatedConstruct#getAnnotation(Class)
* @see javax.lang.model.AnnotatedConstruct#getAnnotationsByType(Class)
*/ */
Set<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a); Set<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a);
@ -155,6 +170,18 @@ public interface RoundEnvironment {
* Returns the elements annotated with one or more of the given * Returns the elements annotated with one or more of the given
* annotation types. * annotation types.
* *
* <p> Note: An implementation of this method typically performs
* an internal conversion from the runtime reflective
* representation of an annotation type as a {@code Class} object
* to a different representation used for annotation
* processing. The set of annotation types present in the runtime
* context may differ from the set of annotation types present in
* the context of annotation processing in a particular
* environmental configuration. If an runtime annotation type is
* not present in the annotation processing context, the situation
* is not treated as an error and no elements are found for that
* annotation type.
*
* @apiNote This method may be useful when processing repeating * @apiNote This method may be useful when processing repeating
* annotations by looking for an annotation type and its * annotations by looking for an annotation type and its
* containing annotation type at the same time. * containing annotation type at the same time.
@ -172,6 +199,10 @@ public interface RoundEnvironment {
* @throws IllegalArgumentException if the any elements of the * @throws IllegalArgumentException if the any elements of the
* argument set do not represent an annotation type * argument set do not represent an annotation type
* @jls 9.6.3 Repeatable Annotation Types * @jls 9.6.3 Repeatable Annotation Types
*
* @see javax.lang.model.AnnotatedConstruct#getAnnotation(Class)
* @see javax.lang.model.AnnotatedConstruct#getAnnotationsByType(Class)
*
* @since 9 * @since 9
*/ */
default Set<? extends Element> getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations){ default Set<? extends Element> getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations){