Some thoughts on javax.lang.model support for preview language features

[Joseph D. Darcy]

Hello,

As you may have seen elsewhere, JEP 12: Preview Language and VM Features 
(http://openjdk.java.net/jeps/12) is proposing to include preview 
language features as part of the platform. The JEP has been discussed in 
various threads on jdk-dev ([1], [2], etc.) Since one of the various and 
sundry aspects of supporting a language is updating the language model 
API [3], it is worthwhile to discuss a few alternatives in terms of how 
the language model API could support preview features

The javax.lang.model APIs are part of the Java SE API and thus live by 
the strict compatibility rules of that space, with some slight 
accommodations for certain technical aspects of the API.

For the sake of argument, let's assume we do *not* want to change 
mainline javax.lang.model API to describe the preview features. The 
ElementKind.OTHER and TypeKind.OTHER values are meant to indicate an 
object is outside of the values for the standardized system. Subtypes of 
the modeling interfaces and visitors can then be used as needed for the 
specialized and extended system. (Joel Borggren-Franck and I used this 
approach in the javax.lang.model backed by core reflection prototype 
from a few years back, JEP 119: javax.lang.model Implementation Backed 
by Core Reflection.)

However, using such an extended API inside javac (or in annotation 
processors) is tedious.

One could imagine a system where a different, updated, version of 
javax.lang.model were used when the incubating features were unlocked 
via upgrading its module or the like, but that would be awkward as well.

If our intention is to only support one preview version at a time, part 
of the API approach could be to add a "PREVIEW" constant to 
SourceVersion that was always the most latest version. In other words in 
JDK 11 we'd have

     RELEASE_0,
     ...
     RELEASE_11,
     PREVIEW;

and in JDK 12

     RELEASE_0,
     ...
     RELEASE_11,
     RELEASE_12,
     PREVIEW;

Processors could them indicate they support the "PREVIEW" release value.

The longer-term javax.lang.model API evolution to-do list includes 
thinking about other ways to evolve the visitors to support new language 
features. We've stopped automatically adding new visitors with every 
release, now only adding them as needed and we didn't need a new batch 
for 10. We could potentially have a similar structure for visitors with 
a cadre of "Preview" visitors as the most specialized versions in a 
release and new per-release visitors getting introduced as superclasses 
afterward.

The main risk is pulling or changing the incubating feature in some way 
that would be incompatible with the API support added for it.

Recent discussions have suggested @Deprecating new API items added to 
support preview features. Can is a reasonable precaution to discourage 
accidental dependence on them, but at times the behavior of existing 
methods is also changes so deprecation would not be a good fit.

Cheers,

-Joe

[1] http://mail.openjdk.java.net/pipermail/jdk-dev/2018-January/000515.html

[2] http://mail.openjdk.java.net/pipermail/jdk-dev/2018-March/000831.html

[3] 
https://blogs.oracle.com/darcy/so-you-want-to-change-the-java-programming-language