Preview APIs for preview features -- JDK 14+

[Alex Buckley]

On 8/5/2019 11:23 AM, Alex Buckley wrote:
> Preview language features such as text blocks (JEP 355) sometimes depend 
> on associated APIs in `java.*` (e.g. String::stripIndent). If a 
> developer enables preview features at compile time and explicitly calls 
> APIs associated with the preview feature, then all is well; but if a 
> developer _doesn't_ enable preview features and still calls those APIs, 
> then Java compilers need to shout loudly about how the API could change 
> or disappear in future, depending on the fate of the preview feature.
...
> Joe Darcy has proposed that associated APIs are annotated explicitly 
> (e.g. @java.lang.annotation.PreviewFeature) so that their use can be 
> detected at compile time. 

Further internal discussion led us to question if it's appropriate to 
indicate associated APIs via an annotation, even a Java SE annotation 
like @java.lang.annotation.PreviewFeature.

The short answer is "no". It will be a compile-time error to call an 
associated API when preview features are disabled, and the authority for 
such an error should start and end with the JLS. We do not want the 
presence of an annotation on one piece of code to appear responsible for 
the generation of a compile-time error in another piece of code -- 
avoiding that slippery slope is probably the most consistent piece of 
stewardship on these lists over the years.

Part of the justification for an annotation was documentary -- to 
trigger javadoc into rendering the annotated API in some striking 
"SUBJECT TO CHANGE! USE WITH CAUTION!" way. However, a new javadoc tag, 
`@preview`, can do this just fine. The tag even has an advantage of 
sorts over the annotation: the tag, while not technically limited to doc 
comments for Java SE APIs, will be hard to use outside the JDK because 
of the need to configure javadoc just right; the annotation, in 
contrast, could be applied easily to any code on the planet, with 
misleading results.

Platform enthusiasts will know that the Java SE 13 Edition of the JLS 
recently shared with the JSR-388 Expert Group [1] includes a new 
section, 1.5 "Preview Features". For the Java SE 14 Edition onwards, JLS 
1.5 will enumerate the relevant APIs as well as the preview features 
themselves. It will also specify the compile-time error and the 
non-suppressible warning that are due, respectively, when said APIs are 
used with preview features disabled and with preview features enabled.

Alex

[1] 
https://mail.openjdk.java.net/pipermail/java-se-spec-experts/2019-August/000150.html