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

[Michael Ernst]

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.

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.

		    -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