[type-annos-observers] FYI, JSR 308 and the annotation processing discovery process

[Joe Darcy]

Hello,

On 03/31/2013 10:56 AM, Michael Ernst wrote:
> Joe-
>
> Thanks for sharing this, and for the updates you are making.
>
> Adding to Alex's comments:
>
>> * TYPE_USE annotations are *not* included as part of discovery
> An annotation can be marked as targeting both TYPE_USE and other targets.
> Presumably you mean only those that target only TYPE_USE, or maybe you mean
> only those uses that are resolved to target TYPE_USE.

If an annotation appears on a declaration, it will be included in 
discovery and if an annotation appears on a type use, it will *not* be 
included in discovery. If an annotation type is declared to be able to 
be applied to both declarations and type use, only the former 
applications will be visible to discovery.

>
> I would find the text easier to understand with a sentence of explanation
> that remarks that the current annotation processing API is designed for,
> and suited for, declaration annotations, but it is not suited for
> processing type annotations.  That explains why you are making the choices
> to ignore type annotations.

The processing API from circa 2004 - 2006 was built around the 
assumption that annotations were only on declarations / elements. For 
example, for a round of processing there are methods to return the 
declarations / elements annotated with a particular annotation type:

http://download.java.net/jdk8/docs/api/javax/annotation/processing/RoundEnvironment.html#getElementsAnnotatedWith(java.lang.Class)
http://download.java.net/jdk8/docs/api/javax/annotation/processing/RoundEnvironment.html#getElementsAnnotatedWith(javax.lang.model.element.TypeElement)

Consistency properties like "given the set of annotations to be 
processed on a round, you can find all the constructs annotated with 
those annotations by iterating over the elements annotated with each 
annotation" could not be maintained if type use annotations were 
included in discovery.

This sort of rationale is useful, but generally not the sort of material 
we put into the javadoc of an API. However, it will certainly be germane 
to the maintenance review of JSR 269 for Java SE 8.

Thanks,

-Joe

>
> 		    -Mike
>
>
>> Subject: Re: FYI, JSR 308 and the annotation processing discovery process
>> From: Alex Buckley <alex.buckley at oracle.com>
>> To: Joe Darcy <joe.darcy at oracle.com>
>> Date: Fri, 29 Mar 2013 15:10:41 -0700
>>
>> On 3/28/2013 10:39 PM, Joe Darcy wrote:
>>> FYI, as the JSR 269 maintenance lead, besides updating the
>>> javax.lang.model.* API to handle new-in-Java-SE-8 features, I'm not
>>> looking at updating the javax.annotation.processing API to deal with
>>> those new annotation-related features too.
>> "not looking"? Surely "now looking".
>>
>>> "The tool uses a discovery process to find annotation processors and
>>> decide whether or not they should be run. [...] Which processors the
>>> tool asks to run is a function of what annotations are present on the
>>> root elements, what annotation types a processor processes, and whether
>>> or not a processor claims the annotations it processes. [...] For a
>>> given round, the tool computes the set of annotation types on the root
>>> elements. If there is at least one annotation type present, as
>>> processors claim annotation types, they are removed from the set of
>>> unmatched annotations."
>> Close reading of the above paragraph reveals that:
>>
>> - a processor _claims_ annotation types
>> - a processor _claims_ annotations
>> - a processor _processes_ annotations
>> - from a set of annotations, it is possible to remove annotation _types_
>>
>> I contend there is at least one kind error going on here.
>>
>>> To this, I plan to add a paragraph explaining how type annotations do
>>> not interact with the this discovery process; something like:
>>>
>>> "<p>An annotation type is considered present if there is at least one
>>> annotation of that type on a declaration enclosed within the root
>>> elements of a round. For this purpose, a type parameter is considered
>>> to be enclosed by its generic element. Annotations on type uses are
>>> <em>not</em> considered as part of the computation.
>> There is quite a phase shift between the "For this purpose" sentence and
>> the type uses sentence. I think a new paragraph is warranted: "Annotations
>> on type uses are ignored when computing the set of annotation types present
>> on the root elements."
>>
>>> For the purposes of JSR 308:
>>>
>>> * Declaration annotations on type parameters are included in discovery
>>> * TYPE_USE annotations are *not* included as part of discovery
>> You mean to put "For the purposes of JSR 308" into the SE 8 API spec? That
>> would be wrong, as a JSR number is pure administration and the API spec
>> should deal only in features.
>>
>> For the bullet points, beware: an annotation whose type targets TYPE_USE
>> can appear on a type declaration or a type parameter declaration. Surely
>> you want such an annotation on class Foo's declaration to be discovered. Do
>> you mean:
>>
>> - Annotations on type parameter declarations are included in discovery.
>> - Annotations on type uses are not included in discovery.
>>
>> Alex