hg: jep/jeps: 119: javax.lang.model Implementation Backed by Core Reflection
joe.darcy at oracle.com
Mon Nov 7 22:23:46 UTC 2011
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. )
Like the apt mirror API, the jaxax.lang.model API was informed by the
mirrors design philosophy for reflective APIs. 
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.  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
* Supporting more capabilities, such as being able to invoke
* 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.
 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.
 See discussion in slides 20-29 of
More information about the discuss