Preview APIs in the Java Platform

[Remi Forax]

Hi Alex,
I really don't like your dilution argument which is condescending.
And given how Java twist semver, i don't think that using it as an example helps to understand your point.

I believe that opposing the preview API mechanism and the incubation module is a mistake, both are useful at different level.
If you are not adding feature to the language, the preview API is useless because it requires a very specific JVM version (and not a version or upward),
it's not something you want when you publish an API even an experimental one.

I thing the "preview API" mechanism is the wrong name, it should be named "preview language feature API" because it's only useful for APIs that are required by a language feature. 

regards,
Rémi

----- Mail original -----
> De: "Alex Buckley" <alex.buckley at oracle.com>
> À: "jdk-dev" <jdk-dev at openjdk.java.net>
> Envoyé: Mercredi 4 Mars 2020 20:22:24
> Objet: Re: Preview APIs in the Java Platform

> We are emphatically not proposing a mechanism for "Any API that is
> written in Java can be made 'unavailable by default' by its author."
> 
> We are proposing a mechanism for "An API in the Java SE Platform can be
> made 'unavailable by default' by the Java SE Platform Spec."
> 
> Our mechanism exists solely to support preview features in Java SE. Per
> JEP 12, preview features embody precise commitments about quality and
> readiness that we've signed up for when evolving the Java language, JVM,
> and SE API. We have no expectation that other platforms -- be they other
> languages on the JVM, or other APIs which sit above the SE API -- will
> share those commitments for their own evolution. Other platforms have no
> guarantee at all that the idea of preview features, and the commitments
> they represent, will evolve in a way that's useful or workable for those
> platforms.
> 
> Especially with Java 14, the entire Java developer community is becoming
> aware of the high quality, carefully delivered nature of preview
> features in Java SE. If we opened up the mechanism so that API authors
> could use it, they would do so -- and each would make slightly different
> commitments about quality and readiness. The preview concept would soon
> find itself in the same place as the semantic versioning concept: a
> simple "standard" for API authors to follow in theory, but a widely
> abused and mis-applied concept in practice. We are not going to take the
> risk of the preview concept being diluted, because it's something that
> every Java developer should recognize and understand when they peruse
> the latest "What's new in Java XX" article.
> 
> Alex
> 
> On 3/4/2020 10:26 AM, Bill Shannon wrote:
>> Alex, do you see any problems with using these new features with
>> "layered products"?
>> 
>> For example, could some Jakarta EE APIs mark modules as "preview"
>> and take advantage of the same compiler and runtime support that's
>> available to JDK modules?
>> 
>> Is there anything that limits this support to java.* modules?
>> 
>> 
>> Alex Buckley wrote on 3/3/20 1:15 PM:
>>> Java 14 will be the third release to contain preview language features. The idea
>>> of shipping non-final language features -- conceived by JEP 12 in 2018 -- is
>>> turning out well, producing better final features. This made us wonder if
>>> incubation -- conceived by JEP 11 in 2016 -- is the right channel for shipping
>>> non-final APIs, and if the recent introduction of APIs associated with preview
>>> language features (such as `java.lang.Record`) is a signpost to a better
>>> channel.
>>>
>>> Incubation follows the tenor of the old triennial release model, where features
>>> were chosen at the start of a release and their evolving implementations were
>>> shipped in the JDK's Early Access (EA) binaries for years before General
>>> Availability (GA). To signal that an API is non-final both before and after GA,
>>> incubation places it in the `jdk.incubator` namespace. Unfortunately, this
>>> distorts the API and its implementation [1][2], and means that signatures in
>>> `java.*` cannot refer to the new API even if such integration is desirable.
>>> These problems are not significant for user-level libraries such as the HTTP2
>>> client API which incubated in JDK 9, but they are significant for lower level
>>> libraries which need a privileged relationship with `java.base`, such as the
>>> Memory Access API which incubated in JDK 14.
>>>
>>> [1] https://mail.openjdk.java.net/pipermail/panama-dev/2019-June/005884.html
>>> [2] https://bugs.openjdk.java.net/browse/JDK-8237349
>>>
>>> In the new biannual release model, features are targeted to a release only when
>>> they are ready. Until then, they evolve in OpenJDK projects such as Panama and
>>> Valhalla, watching JDK releases sail by every six months. There is broad public
>>> awareness of these projects, and they generally offer EA binaries, so there is
>>> good potential for feedback in the time before a feature is targeted to a
>>> release. Also, because OpenJDK projects are blueprints for the future Java
>>> Platform, they can place non-final APIs directly in `java.base` and refer to
>>> them from signatures in `java.*`. This makes projects' EA binaries look more
>>> polished and should produce higher quality feedback.
>>>
>>> Ultimately, though, the best way to provoke feedback on a feature is to ship it
>>> in the GA binary of a JDK feature release. This approach has worked well for
>>> preview language features, where the Java community has accepted the idea of
>>> non-final features that are disabled by default and can thus be changed in
>>> response to feedback. Ideally, we want a way to ship highly-evolved but
>>> non-final APIs in a JDK feature release, without distorting the API by
>>> relocating its packages and modules, and without misleading developers about its
>>> status.
>>>
>>>
>>> Most "preview principles" carry over from language features to APIs:
>>>
>>> 1. A _preview API_ is a new method, field, class, package, or module in the Java
>>> Platform whose design, specification, and implementation are semantically
>>> complete, but which would benefit from a period of broad exposure and evaluation
>>> before achieving either final and permanent status in the Java Platform or else
>>> being refined or removed.
>>>
>>> We would recast the quality bar for all preview features from "95% done now" to
>>> "100% done within a year". This recognizes two points: first, our experience
>>> that two rounds of preview is normal, and second, the fact that an API has a
>>> larger surface area than a language/VM feature and thus undergoes more syntactic
>>> polishing on its way to final status.
>>>
>>> 2. A preview API will often reside in the `java.base` module, but may reside in
>>> another `java.*` module, including one introduced just for the preview API. For
>>> example, the HTTP2 client API could have previewed in the `java.net.http`
>>> module, where it ended up after incubation.
>>>
>>> A JEP that introduces many packages may designate them all as preview APIs and
>>> place them in different `java.*` modules as it sees fit.
>>>
>>> 3. Preview APIs are unavailable by default. To use them, a developer "opts in"
>>> in the same way as for preview language features: `--release N --enable-preview`
>>> at compile time. The class files of the developer's program are marked to depend
>>> on the preview APIs of Java version N, as if the program had used preview
>>> language features. Accordingly, the class files must be executed with
>>> `--enable-preview` at run time, and only the same JDK version.
>>>
>>> Java 14 already has "APIs associated with preview language features" that work
>>> this way, such as `java.lang.Record`. In future, such APIs would simply be cast
>>> as preview APIs. The existing private mechanism that identifies them to `javac`
>>> and `javadoc` -- `@jdk.internal.PreviewFeature` -- will be used for all preview
>>> APIs.
>>>
>>> 4. The class files of a preview API itself are _not_ marked. There are no
>>> changes to how the JDK is compiled, and every class file in the JDK will have a
>>> 0 minor_version as before.
>>>
>>> To allow for intra-JDK use of a preview API, code in the same module as a
>>> preview API is _not_ required to "opt in" in order to use the API. That is, when
>>> `--enable-preview` is missing, the effect of using a preview API element is a
>>> compile-time error _only for code in other modules_. This is similar to how the
>>> effect of using an `@Deprecated` element is a warning _only for code that is not
>>> itself deprecated_.
>>>
>>>
>>> Beyond APIs, incubation has been used for tools, e.g., `jdk.incubator.jpackage`
>>> in JDK 14. However, it has little real meaning there. A tool that's good enough
>>> to ship in a JDK feature release has already achieved a high level of quality
>>> and is ready for a final round of polishing for its command line options. As
>>> long as the tool displays a suitable message about its non-final status, it can
>>> legitimately be called a "preview tool" and placed in a module in the ordinary
>>> `jdk` namespace rather than the `jdk.incubator` namespace.
>>>
>>>
>>> We don't propose to deprecate incubation or delete JEP 11. It may be useful in
>>> future for non-final APIs that wish to live at arms' length from the JDK,
>>> outside the `java` namespace.
>>>
>>> I intend to update JEP 12 to incorporate preview APIs in the near future,
>>> hopefully in time for 15 so that projects such as Panama can benefit from them.
>>>
>>>
> >> Alex