Preview features for JavaFX

[John Hendrikx]

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.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