JEP 12: Treatment of standard APIs supporting preview features

[Dan Smith]

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.

—Dan