FYI, JSR 308 and the annotation processing discovery process
Alex Buckley
alex.buckley at oracle.com
Fri Jun 28 12:00:13 PDT 2013
In Processor:
Line 96 says "what {@linkplain #getSupportedAnnotationTypes annotation
types a processor processes}" - you mean "a processor _supports_". Let's
strongly distinguish a processor's fixed set of supported types from its
changeable set of claimed types. In a similar vein, I might phrase lines
108/109 as "... but only <i>universal processors</i> which support all
annotation types ({@code "*"}) can claim ..."
Line 102: correctness: "the tool computes the set of annotation types
_that are present_ on the root elements."
Line 104: style: "_then_ as processors claim annotation types"
Lines 105 says "they are removed from the set of unmatched annotations"
but you mean annotation types.
Line 112: First a stylistic comment, then a semantic comment. The
paragraph's three assertions are positive / negative / positive, but I
think it would flow better to have the two positive assertions first
(annotation-type-considered-present +
type-parameter-considered-enclosed) and then the negative assertion
(annotations-on-type-uses-ignored). Then, semantically, I'm still
confused - this paragraph is about _annotation types_ but you say
"_Annotations_ on type uses ...". Maybe you want to say: "An annotation
type that targets type uses _is considered present_ if at least one
annotation of that type appears on an element enclosed within the root
elements of a round; annotations on type uses are not considered in this
computation."
The new para at line 121 is good.
Alex
P.S. I was thinking about terminology recently. Annotation types ought
to have been called "schema types" to draw a bright line between the
declaration of a thing (the type) and a use of the thing (the
annotation). Then, annotation is to schema as object is to class.
On 6/27/2013 11:00 PM, Joe Darcy wrote:
> Hello,
>
> Swapping discussion of this specification back in so it can be brought
> to a conclusion.
>
> Diffs of changed specification text are below. FYI, full webrev,
> including supporting implementation changes, viewable at:
>
> http://cr.openjdk.java.net/~darcy/7162089.3/
>
> On 05/23/2013 11:59 AM, Alex Buckley wrote:
>> Thanks very much Joe. Some distressingly tricky stuff below:
>>
>> On 5/22/2013 10:07 PM, Joe Darcy wrote:
>>> @@ -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 @@
>>
>> It would be clearer and more kind-correct to say:
>>
>> "Which processors the tool asks to run is a function of i) the types
>> of the annotations present on the root elements, ii) the annotation
>> types supported by a processor, and iii) the annotation types claimed
>> by a processor."
>
> The full situation is a bit more complicated. There is a set of
> annotation types. The processing environment keeps looking for
> processors to process them until the set is empty or until there are no
> processors to ask. If a processor claims annotation (types), they are
> removed from the set of unmatched annotation types. Therefore, the types
> of annotation a processor is asked to process depends on the annotation
> types claimed by processors earlier on the search path.
>
>>
>> The idea that a processor CLAIMS annotation types comes from line 104.
>> And if this is right, Processor#process must be clarified. It takes a
>> set of types - great - and returns whether the processor claims all
>> annotations of those types. If you intend to draw an equivalence
>> between "claiming all annotations of types X and Y" and "claiming the
>> annotation types X and Y", please be explicit about it. Right now, the
>> following method spec simply does not parse: "Processes a set of
>> ANNOTATION TYPES on type elements originating from the prior round and
>> returns whether or not THESE ANNOTATIONS are claimed by this processor."
>
> I've gone through and changed the wording of Processor and
> AbstractProcessor to use "annotation types" consistently.
>
>>
>> It would also be good to say "(see below)" when line 104 introduces
>> the idea of annotation types being present, since the more common
>> concept is of annotations being present.
>>
>> OK, moving to the new text...
>>
>>> + * <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.
>>
>> An annotation might be able to target type uses _and_ traditional
>> declaration locations. I think you want to ignore annotations which
>> are _solely_ interested in targeting type uses. At the same time,
>> remember that ElementType.TYPE_USE means "type uses _and_ type
>> declarations and type parameter declarations". So, given an annotation
>> type Foo with @Target(TYPE_USE) and no other @Target, would @Foo being
>> present on a type declaration mean that annotation type Foo is
>> present? The answer should be "yes", because the intent of
>> ElementType.TYPE_USE is to supersede ElementType.TYPE (no doubt the
>> prior @Target of Foo) and previous annotation processors would have
>> processed @Foo on a type declaration just fine.
>
> Clarified intention.
>
>>
>> BTW, line 102 should say "the tool computes the set of annotation
>> types PRESENT on the root elements."
>>
>>> + * For this purpose, a type parameter is
>>> + * considered to be enclosed by its {@linkplain
>>> + * TypeParameter#getGenericElement generic element}.
>>
>> Big context switch here from type-oriented stuff to element-oriented.
>> Please put it in in TypeParameterElement's spec.
>
> This is compensating for a design but in the initial JSR 269 where type
> parameters were not enclosed by their declaring method/constructor or type.
>
>>
>> Please have a paragraph break before the "annotation is present" stuff.
>>
>>> + * 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.
>>
>> This was going great until: "advised to include both the annotation
>> and its container in the set of ..." - it should be "include both the
>> repeatable annotation type and its containing annotation type in the
>> set of ...".
>>
>
> Reworded.
>
> Thanks,
>
> -Joe
>
> diff -r 5c548a8542b8
> src/share/classes/javax/annotation/processing/Processor.java
> --- a/src/share/classes/javax/annotation/processing/Processor.java Thu
> Jun 27 17:45:56 2013 -0400
> +++ b/src/share/classes/javax/annotation/processing/Processor.java Thu
> Jun 27 22:59:40 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -26,6 +26,8 @@
> package javax.annotation.processing;
>
> import java.util.Set;
> +import javax.lang.model.util.Elements;
> +import javax.lang.model.AnnotatedConstruct;
> import javax.lang.model.element.*;
> import javax.lang.model.SourceVersion;
>
> @@ -88,11 +90,12 @@
> * 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
> - * claims the annotations it processes}. A processor will be asked to
> + * claims the annotation types it processes}. A processor will be
> asked to
> * process a subset of the annotation types it supports, possibly an
> * empty set.
> *
> @@ -106,6 +109,32 @@
> * 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}, as opposed to annotations on
> + * elements, 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}.
> + *
> + * <p>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 repeatable annotation
> + * type and its containing annotation type 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
> @@ -257,10 +286,10 @@
> /**
> * Processes a set of annotation types on type elements
> * originating from the prior round and returns whether or not
> - * these annotations are claimed by this processor. If {@code
> - * true} is returned, the annotations are claimed and subsequent
> + * these annotation types are claimed by this processor. If {@code
> + * true} is returned, the annotation types are claimed and subsequent
> * processors will not be asked to process them; if {@code false}
> - * is returned, the annotations are unclaimed and subsequent
> + * is returned, the annotation types are unclaimed and subsequent
> * processors may be asked to process them. A processor may
> * always return the same boolean value or may vary the result
> * based on chosen criteria.
> @@ -271,7 +300,7 @@
> *
> * @param annotations the annotation types requested to be processed
> * @param roundEnv environment for information about the current
> and prior round
> - * @return whether or not the set of annotations are claimed by
> this processor
> + * @return whether or not the set of annotation types are claimed
> by this processor
> */
> boolean process(Set<? extends TypeElement> annotations,
> RoundEnvironment roundEnv);
>
> diff -r 5c548a8542b8
> src/share/classes/javax/annotation/processing/AbstractProcessor.java
> ---
> a/src/share/classes/javax/annotation/processing/AbstractProcessor.java
> Thu Jun 27 17:45:56 2013 -0400
> +++
> b/src/share/classes/javax/annotation/processing/AbstractProcessor.java
> Thu Jun 27 23:00:00 2013 -0700
> @@ -38,7 +38,7 @@
> * superclass for most concrete annotation processors. This class
> * examines annotation values to compute the {@linkplain
> * #getSupportedOptions options}, {@linkplain
> - * #getSupportedAnnotationTypes annotations}, and {@linkplain
> + * #getSupportedAnnotationTypes annotation types}, and {@linkplain
> * #getSupportedSourceVersion source version} supported by its
> * subtypes.
> *
>
More information about the type-annotations-spec-comments
mailing list