Preview APIs in the Java Platform

[Bill Shannon]

It needs more than just the annotation, it needs the compiler and runtime
support to go with it.

Ryan Schmitt wrote on 3/4/20 12:19 PM:
> Might I suggest a @java.lang.Unstable or @java.lang.Experimental annotation,
> to go with @Deprecated? It seems that every non-trivial project eventually has
> to make their own stability annotations, and standard ones in the JDK would at
> least allow IDEs to render unstable usages differently (analogous to how uses
> of deprecated APIs are struck through).
>
> On Wed, Mar 4, 2020 at 11:36 AM Bill Shannon <bill.shannon at oracle.com
> <mailto:bill.shannon at oracle.com>> wrote:
>
>     That's unfortunate.
>
>     It seemed like the mechanism could be useful for other projects, even if
>     the policy for use of that mechanism wasn't identical to the Java SE policy.
>
>     Would you recommend that we propose a similar but different mechanism in
>     Java SE that could be used by layered products?
>
>     Or do you believe that layered products should be allowed to introduce
>     preview features similar to Java SE?
>
>     Or perhaps you see a way to support the needs of layered products without
>     any changes to Java SE?
>
>
>     Alex Buckley wrote on 3/4/20 11:22 AM:
>     > 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
>