JavaFX Incubator Modules #1375
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # JavaFX Incubator Modules | ||
|
|
||
| ## Overview | ||
|
|
||
| In [JEP 11](https://openjdk.org/jeps/11), the JDK provides incubator modules as a means of putting non-final API in the hands of developers, while the API progresses towards either finalization or removal in a future release. | ||
|
|
||
| Similarly, some JavaFX APIs would benefit from spending a period of time in a JavaFX release prior to being deemed stable. Being in the mainline `jfx` repository, and thus in downstream binaries such as those at jdk.java.net, makes it easier for interested parties outside of the immediate OpenJDK Community to use the new feature. Experience gained and fed back through the usual channels such as blogs, mailing lists, outreach programs, and conferences can then be acted upon before finalizing, or else removing, the feature in a future release. | ||
|
|
||
| This is especially useful for complex features with a large API surface. Such features are nearly impossible to get right the first time, even after an extensive review. Using an incubator module will allow the API to evolve in future releases without the strict compatibility constraints that core JavaFX modules have. | ||
|
|
||
| ## Description | ||
|
|
||
| An incubating feature is an API of non-trivial size, that is under development for eventual inclusion in the core set of JavaFX APIs. The API is not yet sufficiently proven, so it is desirable to defer finalization for a small number of feature releases in order to gain additional experience and feedback. | ||
|
|
||
| See [JEP 11](https://openjdk.org/jeps/11) for a description of incubator modules. | ||
|
|
||
| JavaFX incubator modules have a few differences from JDK incubator modules: | ||
|
|
||
| - A JavaFX incubator module is identified by the `jfx.incubator.` prefix in its module name. | ||
| - A JavaFX incubating API is identified by the `jfx.incubator.` prefix in its exported package names. An incubating API is exported only by an incubator module. | ||
| - Incubator modules must export incubating APIs only, i.e., packages in the `jfx.incubator` namespace. Consequently: | ||
| - JavaFX incubator modules must not export core JavaFX APIs in the `javafx.` namespace. This distinguishes incubator modules from core modules such as `javafx.base`. | ||
| - JavaFX non-incubator modules must not specify `requires transitive` dependences upon incubator modules, or otherwise expose types exported from incubator modules in their own exported APIs. In exceptional cases, it may be acceptable for non-incubator modules to specify `requires` dependences (as opposed to `requires transitive`) upon incubator modules. | ||
| - JavaFX incubator modules can specify requires or requires transitive dependences upon other incubator modules. | ||
| - A warning must be issued when first loading a class from a publicly exported package in a JavaFX incubator module, even if the module is not jlinked into the JDK. We will provide a utility method in `javafx.base` to facilitate this. | ||
| - To either make a JavaFX incubating API final, or to remove it, a new JEP should be submitted, referencing the original incubator JEP. | ||
| - By default, a JavaFX feature that is delivered in an incubator module will re-incubate in subsequent versions (the default in the JDK is to drop the feature). If any changes are needed to the API, they will be done with new JBS enhancement along with an associated CSR. However, this is not intended to suggest the possibility of a permanently incubating feature. As with incubating features in the JDK, if an incubating API is not promoted to final status after a reasonably small number of JavaFX feature releases, then it will be dropped: its packages and incubator module will be removed. As a guideline: | ||
| - An incubating API that was not updated in the current shipping feature release and has not been updated in the feature release being developed, is either stable or is not being actively developed. Such an API should either be finalized or dropped. | ||
| - An incubating API that spans beyond a 24-month period (4 feature releases), and is not yet ready to be finalized, will need explicit approval from a Project Lead to remain incubating for some additional period at the discretion of a Project Lead. Otherwise, a Project Lead will submit a removal JEP. | ||
| - The submitter of the original JEP can propose to remove it at any time. | ||
|
|
||
| ## How to add a new incubator module | ||
|
|
||
| Use [this patch](https://github.com/openjdk/jfx/pull/1375.diff) as a starting point for your incubator module. Then do the following: | ||
| - Rename `modules/jfx.incubator.myfeature` to the desired name of your module, keeping the `jfx.incubator. prefix` | ||
| - Modify `build.gradle`, `settings.gradle`, and `modules/javafx.base/src/main/java/module-info.java` to update the name of your module. Look for comments of the form `// TODO: incubator template` for where to make the changes. | ||
| - Develop your module as you would with any JavaFX module, keeping in mind the rules in this JEP about public exports and dependencies. | ||
|
|
||
| FIXME: find a permanent home for the incubator module template patch, possibly in the jfx-sandbox repo. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| /* | ||
| * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
| * under the terms of the GNU General Public License version 2 only, as | ||
| * published by the Free Software Foundation. Oracle designates this | ||
| * particular file as subject to the "Classpath" exception as provided | ||
| * by Oracle in the LICENSE file that accompanied this code. | ||
| * | ||
| * This code is distributed in the hope that it will be useful, but WITHOUT | ||
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| * version 2 for more details (a copy is included in the LICENSE file that | ||
| * accompanied this code). | ||
| * | ||
| * You should have received a copy of the GNU General Public License version | ||
| * 2 along with this work; if not, write to the Free Software Foundation, | ||
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | ||
| * | ||
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| * or visit www.oracle.com if you need additional information or have any | ||
| * questions. | ||
| */ | ||
|
|
||
| // TODO: incubator dependency | ||
| package com.sun.javafx; | ||
|
|
||
| import java.security.AccessController; | ||
| import java.security.PrivilegedAction; | ||
| import java.util.HashSet; | ||
| import java.util.Set; | ||
|
|
||
| /** | ||
| * Module utilities. | ||
| */ | ||
| public class ModuleUtil { | ||
|
|
||
| private static final Set<Module> warnedModules = new HashSet<>(); | ||
| private static final Set<Package> warnedPackages = new HashSet<>(); | ||
|
|
||
| private static final Module MODULE_JAVA_BASE = Module.class.getModule(); | ||
|
|
||
| @SuppressWarnings("removal") | ||
| public static void incubatorWarning() { | ||
|
There was a problem hiding this comment. perhaps we can add a javadoc to this method explaining why it is here and giving a usage example? |
||
| AccessController.doPrivileged((PrivilegedAction<Void>) () -> { | ||
| var stackWalker = StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE); | ||
| var callerClass = stackWalker.walk(s -> | ||
| s.dropWhile(f -> { | ||
| var clazz = f.getDeclaringClass(); | ||
| return ModuleUtil.class.equals(clazz) || MODULE_JAVA_BASE.equals(clazz.getModule()); | ||
| }) | ||
| .map(StackWalker.StackFrame::getDeclaringClass) | ||
| .findFirst() | ||
| .orElseThrow(IllegalStateException::new)); | ||
| //System.err.println("callerClass = " + callerClass); | ||
| var callerModule = callerClass.getModule(); | ||
|
|
||
| // If we are using incubating API from the unnamed module, issue | ||
| // a warning one time for each package. This is not a supported | ||
| // mode, but can happen if the modular jar is put on the classpath. | ||
| if (!callerModule.isNamed()) { | ||
| var callerPackage = callerClass.getPackage(); | ||
| if (!warnedPackages.contains(callerPackage)) { | ||
| System.err.println("WARNING: Using incubating API from an unnamed module: " + callerPackage); | ||
| warnedPackages.add(callerPackage); | ||
| } | ||
| return null; | ||
| } | ||
|
|
||
| // Issue warning one time for this module | ||
| if (!warnedModules.contains(callerModule)) { | ||
| // FIXME: Check whether this module is jlinked into the runtime | ||
| // and thus has already printed a warning. Skip the warning in that | ||
| // case to avoid duplicate warnings. | ||
| System.err.println("WARNING: Using incubator modules: " + callerModule.getName()); | ||
| warnedModules.add(callerModule); | ||
| } | ||
|
|
||
| return null; | ||
| }); | ||
| } | ||
|
|
||
| // Prevent instantiation | ||
| private ModuleUtil() { | ||
| } | ||
| } | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this change fixed the jenkins build of the rich text area incubator, thank you!