Summary

Support JavaFX preview features. Preview features are a means of putting non-final APIs in the hands of developers, while the APIs progress towards either finalization or removal in a future release.

Problem

Some JavaFX APIs would benefit from spending a period of time in a JavaFX release prior to being deemed stable. Being in the mainline jfx repository, and thus in downstream binaries such as those at jdk.java.net, makes it easier for interested parties outside of the immediate OpenJDK Community to use the new feature. Experience gained and fed back through the usual channels such as blogs, mailing lists, outreach programs, and conferences can then be acted upon before finalizing, or else removing, the feature in a future release.

This is especially useful for complex features with a large API surface. Such features are nearly impossible to get right the first time, even after an extensive review. Using a preview feature will allow the API to evolve in future releases without the strict compatibility constraints that core JavaFX APIs have.

Solution

Add the necessary runtime support for preview features.

See JavaFX Preview Features, which builds on JEP 12, for more information.

Specification

• Add the com.sun.javafx.PreviewFeature enumeration, which is a utility class that preview APIs will call at runtime to provide a warning that an application has used a preview feature.
• Add the javafx.enablePreview system property that applications must specify in order to use preview APIs.
• Add the javafx.suppressPreviewWarning system property that applications can specify in order to suppress the preview API warning at runtime.

If an application uses a preview API without specifying the javafx.enablePreview system property, the API call fails with the following exception:

<FEATURE-NAME> is a preview feature of JavaFX %N.
Preview features may be removed in a future release, or upgraded to permanent features of JavaFX.
Programs can only use preview features when the following system property is set: -Djavafx.enablePreview=true

If an application uses a preview feature and specifies the javafx.enablePreview system property, the following warning is printed to the standard error stream once for each distinct preview feature:

Note: This program uses the following preview feature of JavaFX %N: <FEATURE-NAME>
Preview features may be removed in a future release, or upgraded to permanent features of JavaFX.
This warning can be disabled with the following system property: -Djavafx.suppressPreviewWarning=true