JEP 12: Treatment of standard APIs supporting preview features

[Alex Buckley]

On 3/5/2018 2:16 PM, Dan Smith wrote:
> 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.

Since a language feature doesn't know whether it's going to be a preview 
feature until its JEP is proposed to target, it would be proper for the 
language feature to give itself any support in java.lang that it deems 
necessary or useful. (Iterable, AutoCloseable, FunctionalInterface, 
Deprecated::forRemoval, ...)

The decision to target the JEP as a preview language feature in JDK $N 
would have to consider the risk of removing the java.lang support in JDK 
$N+1 if the feature turns out to be a dud. This reminds us that the 
stability and completeness bar for including a preview language feature 
is ALWAYS extraordinarily high.

A more likely factor in the targeting decision is the risk of the 
java.lang support in JDK $N being changed incompatibly in JDK $N+1. Bear 
in mind that code which uses the preview language feature in JDK $N will 
have to be recompiled for JDK $N+1 anyway, so the silent compatibility 
risk is for code which used the java.lang changes "directly" (maybe by 
instantiating anonymous subclasses of Iterable, to continue the for-each 
example). But fundamentally we can deprecate-for-removal to push that 
code in the right direction.

Alex