Preview features for JavaFX

Wed Feb 7 13:22:10 UTC 2024

Hi,

I don't think it's possible to give a custom warning at compile time 
without the user having a specific annotation processor active (ie, to 
get the warning, they'd first need to set up an annotation processor 
which FX provides).  The problem here is that we can't enforce the use 
of the annotation processor unconditionally.

The only annotation that you can use to intentionally create a compiler 
warning is the @Deprecated annotation (perhaps the compiler team should 
look into more annotations for this purpose).

The deprecated annotation was used at the time of the first preview 
features to indicate their status, from JEP-12:

> The earliest version of this JEP proposed to use the deprecation 
> mechanism for flagging APIs associated with preview features. 
> Consequently, in Java SE 12 and 13, the APIs associated with preview 
> features were terminally deprecated at birth, that is, annotated 
> with|@Deprecated(forRemoval=true, since=...)|when they were 
> introduced. For example, Java SE 13 declared anessential API 
> associated with text blocks 
> <https://docs.oracle.com/en/java/javase/13/docs/api/java.base/java/lang/String.html#stripIndent%28%29>, 
> and areflective API associated with switch expressions 
> <https://docs.oracle.com/en/java/javase/13/docs/api/jdk.compiler/com/sun/source/tree/SwitchExpressionTree.html>. 
> However, the deprecation-based approach was eventually dropped because 
> it was confusing to see an API element introduced in the same Java SE 
> release as it was deprecated, that is, to see|@since 
> 13|and|@Deprecated(forRemoval=true, since="13")|on the same API element.
The PreviewFeature annotation can't be used I think, it's part of 
`jdk.internal.javac`.

--John

On 07/02/2024 13:21, Kevin Rushforth wrote:
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240207/9561d122/attachment.htm>