Type Annotations in the language model API

[Alex Buckley]

As raised by Joe Darcy elsewhere, the language model needs to consider 
the only truly new construct in the language for type annotations: the 
'this' pseudo-parameter which allows annotations on the type of the 
object on which a method/ctor is invoked.

The question is whether to expose a mirror for that type via:

i) a new method ExecutableElement.getReceiverType() that returns a 
TypeMirror, or

ii) inserting a VariableElement for 'this' into the result of 
Executable.getParameters(), from which clients can get a TypeMirror via 
asType().

I favor (i) for three reasons:

- The EG agreed previously that a method parameter named 'this' is not 
truly a formal parameter declaration. It isn't reified in a method 
descriptor, and it's best not to let it be annotated by a 
PARAMETER-targeting annotation. Therefore it doesn't deserve a 
VariableElement.

- getReceiverType() is easy to implement in ExecutableElement because 
the result can always be based on the result of asType() from the 
enclosing TypeElement. Just sprinkle in the type annotations from a 
'this' pseudo-parameter if available from source.

- getReceiverType() loosely follows 
j.l.r.Method.getAnnotatedReceiverType(). 
(ExecutableElement.getAnnotatedReceiverType() would not be a good name 
because in the language model, we've pushed annotations into type 
mirrors per Joe's "has-a" comment.)

Alex

On 2/15/2013 12:51 PM, Alex Buckley wrote:
> Experts,
>
> Previously [1], we proposed to represent type annotations in the
> language model API via an AnnotatedTypeMirror hierarchy that parallels
> the TypeMirror hierarchy. This proposal was driven by an abundance of
> caution for language model implementations that share TypeMirror objects
> across different use sites, such as a single TypeMirror object for both
> uses of String in "@Foo String f1; @Bar String f2;". In addition, we
> proposed new methods on {Type,Variable,Executable}Element to expose
> AnnotatedTypeMirror objects.
>
> We now think our proposal was excessively concerned about freedom for
> implementers of the language model API, rather than keeping a simple
> conceptual model for users of the API.
>
> In keeping with how the Java language now supports annotations on both
> declarations and type uses, we propose to expose annotations uniformly
> on javax.lang.model.element.Element (declarations) and
> javax.lang.model.type.TypeMirror (type uses).
>
> To this end, we propose to pull the annotation methods of Element into a
> new interface which is implemented by both Element and TypeMirror:
>
> package javax.lang.model;
> interface AnnotatedConstruct {
>    <A extends Annotation> A         getAnnotation(Class<A>);
>    <A extends Annotation> A[]       getAnnotationsByType(Class<A>)
>    List<? extends AnnotationMirror> getAnnotationMirrors();
> }
>
> (getAnnotationsByType is a new method for repeating annotations,
> discussed on the enhanced-metadata-spec-discuss list.)
>
> The implication for implementers is that a TypeMirror object cannot
> _always_ be shared across multiple uses of a type in
> class/interface/field/method/ctor declarations. Previously, a TypeMirror
> object could _always_ be shared in this manner.
>
> For example, suppose v1 is the VariableElement for the field "@Foo
> String f1;" and v2 is the VariableElement for the field "@Bar String
> f2;". In Java SE 8, v1.asType() must not return the same TypeMirror
> object as v2.asType(). But suppose v3 is the VariableElement for "@Quux
> String f3;" and v4 is the VariableElement for "@Quux String f4;".
> v3.AsType() may return the same TypeMirror object as v4.asType().
>
> Essentially, the concept which TypeMirror has always represented - "type
> in the Java programming language" - is now expanded to "potentially
> annotated type in the Java programming language".
>
> For compatibility, the utility methods for type comparison in
> javax.lang.model.util.Types should ignore annotations. New methods can
> be added, but comparing annotations may be a rathole, so please let's
> use a new thread for utility methods.
>
> We don't propose to revisit type annotations in the core reflection API.
> There, we need new methods exposing a new AnnotatedType hierarchy
> because the legacy Type hierarchy is truly limited to declarations, both
> in concept and in implementation.
>
> Alex
>
> [1]
> http://mail.openjdk.java.net/pipermail/type-annotations-spec-experts/2012-September/000001.html
>