JDK 9 request for specification changes of JDK-8032230: Enhance javax.a.p.RoundEnvironment after repeating annotations

[Alex Buckley]

On 5/18/2016 12:55 PM, joe darcy wrote:
> Please review the patch below which proposes a new method to address
>
>      JDK-8032230: Enhance javax.a.p.RoundEnvironment after repeating
> annotations
>
> At present, this is just a review of the specification of the default
> method in the interface and *not* a more optimized implementation in the
> javac RoundEnvironemnt implementation (and not any tests that would be
> needed for the new functionality).

The rationale for a new method is that it "may be useful [to consider] 
looking for an annotation type and its containing annotation type at the 
same time".

I guess there's an assumption that the pre-existing method 
getElementsAnnotatedWith(Class<? extends Annotation>) is called first 
with an argument Foo.class and then if no results is called again with 
an argument FooContainer.class. It would certainly be behaviorally 
incompatible for the pre-existing method to be changed to detect when 
Foo.class is a repeatable annotation type and go off looking for 
@FooContainer annotations of its own accord.

So, if we want to look for an @Foo annotation and an @FooContainer 
annotation "at the same time", then how about the new method being:

-----
Set<...> getElementsAssociatedWith(Class<? extends Annotation> a)

Returns the elements with which annotations of the given type are 
_associated_. [Cross-ref to j.l.r.AnnotatedElement where the richness of 
"associated" is explained.]
-----

If you prefer the method proposed below, consider a varargs Class 
parameter rather than a Set.

Alex

> Note that the bug proposes adding two methods
>
>      RoundEnvironment.getElementsAnnotatedWith(Set<Class<? extends
> Annotation>> s)
> RoundEnvironment.getElementsAnnotatedWith(Set<AnnotationMirror> s)
>
> but these methods would clash since their erasure is the same. *sad
> tromphone*
>
> Therefore, I'm only proposing to add the Class-based variant since that
> one is the more commonly used of the two.
>
> Thanks,
>
> -Joe
>
>
> +    /**
> +     * Returns the elements annotated with any of the given annotation
> +     * types.
> +     *
> +     * @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.
> +     *
> +     * @implSpec The default implementation of this method creates an
> +     * empty result set, iterates over the annotations in the argument
> +     * set calling {@link #getElementsAnnotatedWith(TypeElement)} on
> +     * each annotation and adding those results to the result
> +     * set. Finally, the contents of the result set are returned as an
> +     * unmodifiable set.
> +     *
> +     * @param annotations  annotation type being requested
> +     * @return the elements annotated with the given annotation types,
> +     * or an empty set if there are none
> +     * @throws IllegalArgumentException if the any elements of the
> +     * argument set do not represent an annotation type
> +     * @since 9
> +     */
> +    default Set<? extends Element> getElementsAnnotatedWith(Set<Class<?
> extends Annotation>> annotations){
> +        HashSet<Element> result = new HashSet<>();
> +        for (Class<? extends Annotation> annotation : annotations) {
> +            result.addAll(getElementsAnnotatedWith(annotation));
> +        }
> +        return Collections.unmodifiableSet(result);
> +    }
>