Preview features for JavaFX

[Michael Strauß]

Hi Kevin,

my suggestion would be to annotate and document the preview API (at
least annotations do show up by default in most IDEs), and emit a
one-time runtime warning when the API is used (this works for methods
and constructors). This would make it quite visible to developers that
they are using a preview feature, or that a third-party library uses a
preview feature.

The runtime warning can be suppressed with a command line parameter
such as "javafx.enablePreviewFeatures". A more drastic approach would
be to throw an exception from new APIs when the parameter is not
specified.

Given that there are very tangible benefits to previewing new API,
this would seem to me like a good enough solution.


On Wed, Feb 7, 2024 at 12:59 AM Kevin Rushforth
<kevin.rushforth at oracle.com> wrote:
>
> In order for preview features and incubating features to not cause more
> problems than they solve, there needs to be a robust way to ensure that
> applications and libraries don't use them without knowing that they are
> doing so. We know how to do that for a feature that lives in its own
> module (an incubating feature), but not how to do that for something
> like a preview feature.
>
> For incubating features, this is relatively straight-forward, since they
> are delivered in a separate module that has "incubator" in the name,
> isn't resolved by default, and warns you at runtime when those modules
> are resolved. Adapting what the JDK does for JavaFX should be pretty
> easy, and retain the benefit that an app knows when they are using
> incubating features.
>
> I don't think it is feasible to do the same thing for preview features.
> The way the JDK preview features work is that a command line option is
> needed both at compile time and at runtime to opt into preview features
> for a specific release. This prevents using a preview API from an
> existing module and package without knowing that it is subject to
> change. Without a clear "opt in" mechanism to be able to use an API, an
> app would be able to accidentally use a feature whose API is unstable
> and quite possible might change. An annotation isn't good enough (and
> documentation certainly isn't sufficient). IDEs will still autocomplete
> and show the API, and once an app uses it -- accidentally or otherwise
> -- there is no indication at runtime that you are using a feature that
> will likely stop working without any notice in the next version.
>
> I don't see a good way to do this for JavaFX given the limitations.
>
> -- Kevin