Preview APIs in the Java Platform

[Volker Simonis]

There's one major difference between the "Preview" and the "Incubator"
approach which doesn't seemed to have been covered in this thread.

"Preview" features have "Java SE" scope. They are, though not final,
still part of the Java SE specification. As such they require a
complete TCK and they have to be agreed upon in the corresponding JCP
Expert Group and voted on in the JCP Executive Committee. Finally,
because they are part of the SE specification, they have to be
implemented by all Java implementations, no matter if they are based
on the OpenJDK or not.

"Incubator" features are a much more "lightweight" approach of
introducing new APIs. Because they are not in the "Java SE" scope,
they neither need to pass through the JCP nor do they require a
complete TCK (although it would always be nice to have one). Finally,
other Java vendors are not required to ship and support the same set
of incubator modules like the OpenJDK and because the "jdk." package
is not restricted like the "java." package they could even decide to
"incubate" own features before even proposing them for inclusion into
the OpenJDK (see [1]).

[1] https://mail.openjdk.java.net/pipermail/jdk9-dev/2016-December/thread.html#5319

On Fri, Mar 6, 2020 at 12:58 PM Chris Hegarty <chris.hegarty at oracle.com> wrote:
>
>
> >>> ...
> >>> On 03/03/2020 21:15, Alex Buckley wrote:
> >>>> 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.
>
>
> When working on the HTTP Client ( incubated in JDK 9, re-incubated in
> JDK 10, and standardized in Java 11 ), it would have been cosmetically
> nice to have been able to locate the API in java.net.http from the
> beginning, but in reality having it in its own incubator module/package
> didn't burden the implementation all that much. As was said previously,
> this is because the HTTP Client is largely a "user-level" library, which
> has very little ( if any ) coupling with java.base.
>
> When working on JEP 11 ( Incubator Modules ), we knew that features
> requiring tight coupling with java.base ( or the VM itself ) would
> likely emerge, and that squeezing such features into the incubation
> mechanism would require some "implementation pain". This seemed like an
> acceptable trade-off at the time, to enable the opportunity to better
> solicit feedback for such features. Remember, all this predates JEP 12.
>
> Fast forward to where we are now, and given the issues that the Foreign
> Memory API has had to deal with to squeeze into incubation, maybe there
> is a better way of achieving the goal - to gather feedback before
> standardizing. With the move to already have Preview Feature related
> API elements in java.*, then it seems ( to me ) a natural progression
> to expand this to, what are effectively, Preview APIs.
>
> Would HTTP Client have previewed ( rather than incubated )? Impossible
> to say for sure, but as one of the developers working on the feature, it
> is my opinion that we would not have previewed HTTP Client in 9. The
> reason being that I do not think the feature would meet the higher
> completeness level required by Preview. If Preview was an option back
> in the 9 time frame, then, again this is just my opinion, I think I
> would have held off incubating in 9 and iterated a little longer so that
> it could preview in 10. ( yes, while I said it would have been
> "cosmetically nice" to have used java.net.http from the beginning,
> avoiding the temporary incubation name would likely have avoided some
> developer confusion, which for me, on balance, would have been worth
> doing )
>
> ---
>
> If there is a specific issue with recognising if preview features are
> enabled or not, then maybe that issue can be addressed by adding a
> property, API, or some such, that will reveal the enable-preview status
> at run-time.
>
> -Chris.
>