JEP 12: Treatment of standard APIs supporting preview features

[Alex Buckley]

On 3/5/2018 9:12 PM, Dan Smith wrote:
> If we're comfortable making liberal use of deprecation in the case of
> preview feature-related APIs, that's a reasonable way out. That might
> include adding notices to the javadoc: "This API is part of a preview
> feature. Use at your own risk."
>
> If that's the consensus, maybe we could call this out in JEP 12 and
> in the deprecation policies? (Is there some document somewhere that
> describes deprecation policies?)

We'd like to use deprecation-for-removal-at-birth as the way to flag 
"this API is intimately connected to a preview feature". If the preview 
feature becomes permanent, then the deprecation would be removed. This 
jump from terminal-deprecation to no-deprecation is novel, but not mad 
-- deprecation has a variety of meanings, and its historical use in the 
JDK is not a good guide to anything.

(JEP 277 has much background on this. Note in particular its first 
sentence: "Deprecation is a technique to communicate information about 
the life cycle of an API: to encourage applications to migrate away from 
the API, to discourage applications from forming new dependencies on the 
API, and *****to inform developers of the risks of continuing dependence 
upon the API.*****" -- the last clause captures why we like deprecation 
for snipping at the use of a preview API.)

I have expanded the "Relationship to Java SE APIs" section in the JEP, 
and noted some of the risks in "Process issues".

> Are there any API changes that might be needed to support a preview
> feature that _wouldn't_ be easy to deprecate? New methods, classes,
> fields, enum constants are all straightforward. I'm wondering if
> there are other possible API changes that wouldn't work out so well?

Let's speak solely of new API elements, so that we can set aside 
behavioral API changes made to support a preview feature in N+1 which 
are then undone in N+2 when the preview feature is dropped.

As you say, first-class API elements can be annotated, so we're looking 
for second-class elements. I offer the strings accepted by 
@SuppressWarnings, per JLS 9.6.4.5. Suppose a preview language feature 
meant that a String could never be null, and safety concerns led to a 
mandatory compile-time warning when String is used in a formal 
parameter, akin to an unchecked warning; the JLS would want to 
standardize suppression of the "dangerousnull" warning. (Separately, I 
can imagine that first-class API elements _which are implicitly 
declared_ -- think Enum::values -- would be hard to deprecate.) But 
we're in the weeds now, so let's move on.

Alex