Preview APIs for preview features -- JDK 14+

[Alex Buckley]

Hi,

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.

JEP 12 has traditionally forced compilers' hands by proposing that 
associated APIs are marked as terminally deprecated at birth 
(https://openjdk.java.net/jeps/12#Relationship-to-Java-SE-APIs). 
However, this results in compile-time warnings that express no 
relationship to preview features, and worse, can be permanently 
suppressed in source code.

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. Consequently:

- If code is compiled with preview features enabled (e.g. 
--enable-preview in javac; other compilers may differ), then the APIs 
can be used (i.e. invoked/overridden/subclassed) with only the 
compiler's usual warnings about use of preview features.

- If code is compiled _without_ preview features enabled, then use of 
the APIs would cause a compile-time error. The JLS would spell out this 
treatment for use of @PreviewFeature APIs (the rules are substantially 
the same as for use of @Deprecated APIs).

To be clear: this proposal means there will be APIs in the Java SE 
Platform that can only be used when preview features are enabled -- just 
as there are already language features in the Platform that can only be 
used when preview features are enabled.

JEP 12 already exhorts the owner of a preview feature to write javadoc 
for associated APIs that clearly describes how their presence and 
evolution is tied to the fate of the preview feature. That's still true; 
in fact, with a little support for @PreviewFeature in the standard 
doclet, the javadoc can highlight the association for casual readers of 
the API -- this will tend to dial down attempts to use the API standalone.

Alex

P.S. Starting in JLS 13, preview features will be enumerated in section 
1.1 "Organization of this Specification" and their actual specifications 
will be co-located with the JLS. This will underpin the new JLS section 
about @PreviewFeature when it refer to preview features, their 
enablement at compile time, and their associated APIs.