Yes, something like an opt-in property might be workable and is worth
considering. We would also want to explore ideas for producing a
compile-time warning along with with a pattern to document them. I'm not
familiar enough with what you can do with annotations, but maybe there
is something there that could help.
We should explore this further for JavaFX 23.
-- Kevin
On 2/7/2024 1:22 AM, John Hendrikx wrote:
Hi Kevin, Michael,
I think throwing an exception when using features that are preview
without a prerequisite property being present or set to some value
would be a good idea. JavaFX has quite a few properties already, and
a special one for previews would make it possible to ensure that such
a feature is not being used without being aware of it.
I would suggest making the property consists of keys (comma separated)
so you must opt-in to each preview feature separately, or having
multiple properties that follow a specific pattern.
A preview check can be as simple as:
if (!Boolean.getProperty("javafx.enablePreview.platformPrefs") )
throw new UnsupportedOperationException(STANDARD_DISCLAIMER + "preview
feature, please enable: xyz");
The disclaimer can be a standard piece of text explaining what a
preview feature is, what it means, and what guarantees we offer (as
limited as they might be). For example, I think preview features are
still guaranteed to be maintained for the release version they target,
but that may be altered or completely removed in a next major release.
I think a warning line is insufficient, especially when preview
feature use may be inherited via a dependency.
--John
On 07/02/2024 02:06, Michael Strauß wrote:
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.rushfo...@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
