JEP 12: Treatment of standard APIs supporting preview features
alex.buckley at oracle.com
Wed Mar 14 23:49:49 UTC 2018
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 188.8.131.52. 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.
More information about the jdk-dev