Preview APIs in the Java Platform

[Alex Buckley]

On 3/5/2020 10:21 AM, forax at univ-mlv.fr wrote:
> I agree that adding a public API in java.base is not covered by the
> incubator api.

Right. We see that as a problem to be solved. Shipping in java.base but 
in an EA binary has low uptake; shipping in jdk.incubator.foo in a GA 
binary has low uptake.

> For the http2 client, having a backlink from java.base to the module
> java.net.http is not a correct way to design thing, the module system
> doesn't allow circularity.

True, I shouldn't have raised that for a preview API in its own module. 
I was thinking about how having Memory Access in java.base would enable 
integration with java.lang.invoke signatures.

> For the foreign memory api, it is more low level that the nio buffer
> api and heavily use unsafe which are both inside java.base, that's
> why it's a PITA. That said, the trick to have the implementation in
> java.base in a package that is only exported to an incubator module
> and the API in the incubator module works.

It works, but it was a pain for Maurizio to have to refactor everything, 
add helper classes in java.base, etc, to accommodate the move to an 
incubator module. And he'll have to move it all back when Memory Access 
goes final! This API churn is confusing to understand. (Yes, I know that 
it's just a matter of changing some imports, but that's too literal a 
way of looking at the world. An API which changes its packages twice -- 
from java.* in EA, to jdk.incubator in GA, to java.* in a later GA -- is 
going to confuse people.)

> For loom (and for valhalla), I believe that using the preview API is
> not the right mechanism to do thing because you will want to be able
> to enable/disable them separately given that they both impact the VM
> in a different ways. Moreover there are 2 looms, you have "loom the
> fiber" and "loom the continuation" and you may want to expose one
> ("loom the fiber") without exposing the other ("loom the
> continuation"), which also suggest different flags.

Preview features are not experimental in any way. If Project Loom still 
has "2 looms" in flight, then it's experimental, and is not ready to 
preview.

>> Programs that choose to use an incubating API in JDK N do not have
>> their class files tagged to run only on JDK N, but in all
>> likelihood such programs will fail on JDK N+1 because of changes in
>> the incubating API -- so the "requires very specific JVM version"
>> angle is, in practice, common to incubating and preview APIs.
> 
> yes, but there is a difference between the VM refusing to read the
> bytecode and the VM throwing a NoSuchMethodError because the API has
> changed.

Yes. Literally, you are correct. Conceptually, this means that neither a 
program which uses an incubating API of JDK N, nor a program which uses 
a preview API of JDK N, can expect to run successfully on JDK N+1.

Alex