JEP 12: Treatment of standard APIs supporting preview features

Dan Smith daniel.smith at
Mon Mar 5 22:16:58 UTC 2018

JEP 12 proposes standardization of a "preview feature" capability in the Java language and JVM. It does not propose "preview features" in the standard API. I think this leaves the platform in an unstable place, so I want to spur a discussion about how interactions with APIs should be handled.

The document has this to say about Java SE APIs:


The feature "must receive appropriate treatment in the reflective and debugging APIs of the Java SE Platform"

"A preview language or VM feature in Java SE $N may rely on any API defined by Java SE $N. This includes APIs introduced in Java SE $N specifically to support the preview feature."

"If a preview language feature of Java SE $N is a declaration form (e.g., record type declarations) rather than a statement or expression form, then it is legitimate for the Language Model API and/or the Annotation Processing API to model the declaration form."


A defining characteristic of preview features is that we reserve the right to back out or redesign the feature. We make no compatibility promises. Putting something in an SE API is a compatibility promise.

So, for example: the for-each language feature depends on the java.lang.Iterable interface and some "extends" clauses added to existing interfaces. If it had been released as a preview feature, the choices would be:

- Introduce java.lang.Iterable as a standard API, and if it turns out that we abandon for-each, or its use of this API, it just remains as cruft. Maybe it gets deprecated.

- Design the preview feature in terms of the existing API (like Collection). Unfortunately, this means there won't be a chance to get any feedback on the API part of the feature until the language part is finalized.

- Introduce Iterable as a "preview standard API". Since the change touches existing classes, we'd really need something like a separate 'java.base' bundle, which would take priority over the standard bundle when the compiler/vm operates in preview mode. Lots of unexplored complexity here.

API dependencies vary widely from feature to feature—many have none. But I think it would be helpful to think through some of the more challenging scenarios, assume the feature gets dropped, and work out what we want to happen next.


More information about the jdk-dev mailing list