Updates to javax.annotation.processing.Processor for repeating annotations

[Alex Buckley]

Thanks Joe. Since annotation [type] discovery applies to type 
annotations as well as repeating annotations, I have responded to the 
spec update on the type-annotations-spec-comments list (which uses the 
same license as this list). Please see:

http://mail.openjdk.java.net/pipermail/type-annotations-spec-comments/2013-May/000034.html.

Alex

On 5/22/2013 9:56 PM, Joe Darcy wrote:
> Hello,
>
> Now that the new present, directly present, etc. terminology is worked
> out, the time has come to update the specification of the annotation
> processing discovery procedure to take into account repeating
> annotations (and other annotation updates in Java SE 8).
>
> Proposed diff below. Full webrev of proposed specification and
> implementation changes at:
>
>      http://cr.openjdk.java.net/~darcy/7162089.2/
>
> Thanks,
>
> -Joe
>
> @@ -88,7 +90,8 @@
>    * configuration mechanisms, such as command line options; for
>    * details, refer to the particular tool's documentation.  Which
>    * processors the tool asks to {@linkplain #process run} is a function
> - * of what annotations are present on the {@linkplain
> + * of the types of the annotations <em>{@linkplain AnnotatedConstruct
> present}</em>
> + * on the {@linkplain
>    * RoundEnvironment#getRootElements root elements}, what {@linkplain
>    * #getSupportedAnnotationTypes annotation types a processor
>    * processes}, and whether or not a processor {@linkplain #process
> @@ -106,6 +109,28 @@
>    * processing {@code "*"} can claim the (empty) set of annotation
>    * types.
>    *
> + * <p>An annotation type is considered present if there is at least
> + * one annotation of that type present on an element enclosed within
> + * the root elements of a round. Annotations on {@linkplain
> + * ElementType#TYPE_USE type uses} are <em>not</em> considered as part
> + * of the computation. For this purpose, a type parameter is
> + * considered to be enclosed by its {@linkplain
> + * TypeParameter#getGenericElement generic element}. An annotation is
> + * present if it meets the definition of being present given in {@link
> + * AnnotatedConstruct}. In brief, an annotation is considered present
> + * for the purposes of discovery if it is directly present or present
> + * via inheritance. An annotation is <em>not</em> considered present
> + * by virtue of being wrapped by a container
> + * annotation. Operationally, this is equivalent to an annotation
> + * being present on an element if and only if it would be included in
> + * the results of {@link Elements#getAllAnnotationMirrors()} called on
> + * that element. Since annotations inside container annotations are
> + * not considered present, to properly process {@linkplain
> + * java.lang.annotation.Repeatable repeatable annotation types},
> + * processors are advised to include both the annotation and its
> + * container in the set of {@linkplain #getSupportedAnnotationTypes()
> + * supported annotation types} of a processor.
> + *
>    * <p>Note that if a processor supports {@code "*"} and returns {@code
>    * true}, all annotations are claimed.  Therefore, a universal
>    * processor being used to, for example, implement additional validity
>