Summary
-------

Provide an implementation of the `javax.lang.model.*` API backed by
core reflection rather than by `javac`.  In other words, provide an
alternate API to access and process the reflective information about
loaded classes provided by core reflection.


Goals
-----

Provide a uniform API to view compile-time and runtime reflective
information about types and their members.  Lower barriers to
experimentation with annotation-related language features.


Motivation
----------

The core reflection API has various design limitations; see
[Mirrors: Design Principles for Meta-level Facilities of Object-Oriented Programming Languages](http://www.bracha.org/mirrors.pdf) for details.

The `javax.lang.model.*` API is used in `javac` for its annotation
processing support; however, the `javax.lang.model.*` API is not
limited to modeling Java structures at compile-time.

If there were a `javax.lang.model.*` implementation backed by core
reflection, the same code could be used to analyze compile-time and
runtime views of types.  Additionally, since `javax.lang.model.*` is
based on interfaces, a specialization of the runtime model could be
used to allow much easier experimentation with alternate annotation
semantics.

For example, some parties have advocated the language's annotation
facility be changed to support *stereotyping*, where application of a
single annotation would logically be expanded to a set of other
annotations.  To support such a feature at runtime via core reflection
would require changes to at least one of `javac` and core reflection
so that the expansion could be performed.  Given a suitable
implementation of `javax.lang.model.*`, a minor specialization of the
`getAnnotation` method could be used to implement stereotyping, or
various other alternate annotation semantics, without having to modify
core aspects of the platform.


Description
-----------

The anticipated implementation approach is to provide a set of factory
methods which wrap core reflection objects with adapters implementing
the corresponding `javax.lang.model.*` construct.  For example, one
method when presented with a `java.lang.reflect.Method` object would
return a `javax.lang.model.element.ExecutableElement` object with a
kind of `METHOD` and a matching name, etc, likewise for other language
structures.  This approach is clearly feasible, a proof of concept
implementation went smoothly, but there are several open questions
about the design and implementation:

  * Should the API be JDK-specific or part of Java SE?

  * How much of the implementation should be exposed for specialization?

  * Should the standard `javax.lang.model.*` be updated to better
    support this use-case?  Strictly speaking, the particular
    requirements of `javax.lang.model.*` only apply when the API is
    being used for annotation processing.

  * Should a runtime-specific specialization of the `javax.lang.model.*`
   API be provided to access core reflection specific functionality,
   like invoking a method?


Testing
-------

The main challenge to testing an implementation of
`javax.lang.model.*` is not testing all the methods per se, but rather
testing all the methods on all the different kinds of language
structures.  The underlying structure of a language model API is the
language being modeled.  For example, to thoroughly test, say, the
`getModifiers` method, each kind of element that can have modifiers
(types, variables, parameters, etc.) should be probed for each set of
modifiers that are legal for that kind of element, which even for this
simple behavior is dozens of combinations.


Risks and Assumptions
---------------------

Impedance mismatches between core reflection, which fundamentally
provide a JVM-level view of the world, and a pure language model may
complicate the implementation.  One motivation for an API specialized
for core reflection is to sensibly handle synthetic structures which
by definition are outside of a pure language model.


Dependences
-----------

Various adjustments to the core reflection API, some of which have
already been made in JDK 8 builds, would simplify a
`javax.lang.model.*` implementation.  For example, the new
`Executable` superclass for `Method` and `Constructor` eases code
sharing.

Assuming runtime access to method/constructor parameter names is
implemented, this project is a natural client for those facilities.


Impact
------

  - Compatibility: There would be various differences between the
    behavior of `javax.lang.model.*` backed by core reflection and
    backed by `javac`.

  - Security: The underlying security mechanism of core reflection
    will be used.

  - TCK: If this API is shipped as part of Java SE, some of the JCK
    tests for JSR 269 may be able to be adapted to test the API.