Preview features for JavaFX

[Kevin Rushforth]

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