JDK 12 RFR of JDK-8213256: Clarify runtime vs ,compile time annotations for ,RoundEnvironment.getElementsAnnotatedWith(Class)

[Jan Lahoda]

Looks good to me.

Jan

On 2.11.2018 18:02, joe darcy wrote:
> Hello,
>
> As a follow-up to recent discussions, please review the proposed changes
> and CSR for
>
>      JDK-8213256: Clarify runtime vs ,compile time annotations for
> ,RoundEnvironment.getElementsAnnotatedWith(Class)
>      CSR:  https://bugs.openjdk.java.net/browse/JDK-8213310
>      webrev: http://cr.openjdk.java.net/~darcy/8213256.0/
>
> Patch below.
>
> Thanks,
>
> -Joe
>
> ---
> old/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
> 2018-11-02 09:55:44.074001000 -0700
> +++
> new/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
> 2018-11-02 09:55:43.902001000 -0700
> @@ -143,11 +143,26 @@
>        * simply because a {@code module-info} file for that module was
>        * 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
>        * @return the elements annotated with the given annotation type,
>        * or an empty set if there are none
>        * @throws IllegalArgumentException if the argument does not
>        * represent an annotation type
> +     *
> +     * @see AnnotatedConstruct.getAnnotation(Class)
> +     * @see AnnotatedConstruct.getAnnotationsByType(Class)
>        */
>       Set<? extends Element> getElementsAnnotatedWith(Class<? extends
> Annotation> a);
>
> @@ -155,6 +170,18 @@
>        * Returns the elements annotated with one or more of the given
>        * 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
>        * annotations by looking for an annotation type and its
>        * containing annotation type at the same time.
> @@ -172,6 +199,10 @@
>        * @throws IllegalArgumentException if the any elements of the
>        * argument set do not represent an annotation type
>        * @jls 9.6.3 Repeatable Annotation Types
> +     *
> +     * @see AnnotatedConstruct.getAnnotation(Class)
> +     * @see AnnotatedConstruct.getAnnotationsByType(Class)
> +     *
>        * @since 9
>        */
>       default Set<? extends Element>
> getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations){
>