FYI, JSR 308 and the annotation processing discovery process

[Joe Darcy]

On 03/29/2013 03:10 PM, Alex Buckley wrote:
> 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".

Quite!

>
>> "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.

I will tighten up the wording accordingly; thanks for the careful reading.

>
>> 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?

No. "For the purposes of JSR 308" is just for the purposes of this email 
thread :-)

> That would be wrong, as a JSR number is pure administration and the 
> API spec should deal only in features.

Agreed.

>
> 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.
>
>

Annotations on declarations, including declarations of type parameters, 
are included in discovery.

-Joe