JEP 119: javax.lang.model Implementation Backed by Core Reflection

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 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.