hg: jep/jeps: 119: javax.lang.model Implementation Backed by Core Reflection

[Joseph Darcy]

Hello Florian,

On 11/7/2011 3:51 AM, Florian Weimer wrote:
> * mark reinhold:
>
>> Changeset: 965ff7e847f4
>> Author:    mr
>> Date:      2011-11-01 14:47 -0700
>> URL:       http://hg.openjdk.java.net/jep/jeps/rev/965ff7e847f4
>>
>> 119: javax.lang.model Implementation Backed by Core Reflection
> We have implemented something in this area, a unified API backed
> alternatively by javax.lang.model or reflection.  Our experience with
> javax.lang.model was not entirely positive because we noticed that our
> code tended to have accidental dependencies on javac implementation
> details.  That was our main motivation to add another layer of
> indirection.  (Another reason was that it was difficult to figure out
> how javax.lang.model was supposed to be implemented, but after the
> experience, it seems less daunting.)
>
> Testing the new implementation against the javac view will likely
> uncover bugs in Core Reflection, which should be fixed there, not worked
> around in the implementation.

The javax.lang.model.* API was always intended to be able to have 
different sources of information backing it.  (In the JSR 269 
implementation provided in javac, this different kind of backing happens 
in a small way when the information about a type comes from a source 
files versus a class file and the specification is designed to allow 
certain differences in behavior in this situation. [1])

Like the apt mirror API, the jaxax.lang.model API was informed by the 
mirrors design philosophy for reflective APIs. [2]

The apt and jaxax.lang.model APIs make distinctions between 
declarations/elements (the structure of entities the programmer 
declares) and the types of those entities.   [3] For example, the APIs 
are able to distinguish between

     * The declaration of the interface "java.util.Set"
     * The raw type "java.util.Set"
     * The type "java.util.Set<T>" and other instantiations of the 
generic type java.util.Set

Other reflective APIs often blur such distinctions when can lead to 
impedance mismatches when trying to place javax.lang.model on top if it.

The javax.lang.model API was designed to allow specializations of it.  
This surfaces in a few ways:

     * The API is mostly interfaces as opposed to classes.
     * Types for structures modeled in javax.lang.model.element 
correspond to stable JVM-level concepts.
     *  ElementKind.OTHER and TypeKind.OTHER allow for controlled extension.
     * Use of wilcards in return types like "List<? extends Element> 
Element.getEnclosedElements()"; a subtype can use a covariant return in 
an overriding method to provide more specific information.

So a core reflection specialized version of the javax.lang.model API 
might look a bit different than the stock API provided by javac (and 
other compilers); possibilities to explore include:

* New root interface "CoreReflectionElement extends 
javax.lang.model.Element".  This interface could then provide methods like
List<CoreReflectionElement> getEnclosedElements()" that do not use 
wildcards.
* Supporting more capabilities, such as being able to invoke 
CoreReflectionExecutableElement objects.
* Modeling of structures present in the JVM/core reflection but outside 
of the language model including bridge methods and synthetic methods.

There are cases where there are legitimate differences in modeling 
between a JVM/class file view of the world and a pure language model 
view, so I would not expect javax.lang.model backed by core reflection 
to behave identically to the javac implementation.  However, core 
reflection also certainly has its own bugs and misfeatures that might be 
addressed as a side-effect of this project.

Cheers,

-Joe

[1] 
http://download.java.net/jdk8/docs/api/javax/lang/model/element/package-summary.html

[2] Gilad Bracha and David Ungar. Mirrors: Design Principles for 
Meta-level Facilities of Object-Oriented Programming Languages. In Proc. 
of the ACM Conf. on Object-Oriented Programming, Systems, Languages and 
Applications, October 2004.

[3] See discussion in slides 20-29 of 
https://blogs.oracle.com/darcy/resource/J1_2005-TS-7425.pdf