Preview APIs for preview features -- JDK 14+
Alex Buckley
alex.buckley at oracle.com
Mon Aug 5 18:23:14 UTC 2019
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.
More information about the jdk-dev
mailing list