64
Preview APIs for preview features -- JDK 14+
source link: https://mail.openjdk.java.net/pipermail/jdk-dev/2019-August/003234.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Preview APIs for preview features
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK