I've created a proposal that defines preview features [0]. The
definition very closely matches the language used in JEP-12, but is
adapted for JavaFX in some places.
Additionally, I've created the internal helper class `PreviewFeature`
that can be used to verify that applications have opted into using
preview features at runtime.
If the system property "javafx.enablePreview" system property has not
been set, the `PreviewFeature.checkEnabled(<featureName>)` method will
throw an exception similar to the following:
<featureName> is a preview feature of JavaFX 23.
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 the system property has been set, the method will log a one-time
warning to the error output stream, similar to the following:
Note: This program uses the following preview feature of
JavaFX 23: <featureName>
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.suppressPreviewBanner=true
I think that we should use the @Depcreated annotation to document API
elements of preview features, with a @deprecated javadoc tag similar
to the following:
@deprecated This is a preview feature which may be changed
or removed in a future release.
The specification of @Deprecated specifically mentions this usage:
"An element may be deprecated for any of several reasons, for example,
its usage is likely to lead to errors; it may be changed incompatibly
or removed in a future version; it has been superseded by a newer,
usually preferable alternative; or it is obsolete."
Finally, all preview features of a JavaFX release should be listed in
the release notes.
[0] https://github.com/openjdk/jfx/pull/1359
