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