JavaFX Incubator Modules

INCUBATOR-MODULES.md

@@ -0,0 +1,45 @@
+# JavaFX Incubator Modules
+
+## Summary
+
+JavaFX incubator modules are a means of putting non-final APIs in the hands of developers, while the APIs progress towards either finalization or removal in a future release. This JEP builds on [JEP 11](https://openjdk.org/jeps/11), which defines JDK incubator modules.
+
+## Goals
+
+Extends the benefits of [JEP 11](https://openjdk.org/jeps/11) to the JavaFX API.
+
+## Motivation
+
+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.

NOTES-INCUBATOR.md

@@ -0,0 +1,16 @@
+# NOTES: JavaFX Incubator Modules
+
+## Overview
+
+These are notes regarding the implementation of JavaFX incubator modules.
+
+## Changes / additions in the jfx.incubator branch
+
+The `jfx.incubator` branch includes the following:
+
+1. The [JavaFX Incubator Modules JEP](INCUBATOR-MODULES.md) and these implementation notes.
+2. A sample incubator module, `jfx.incubator.myfeature`.
+
+This branch is based on the [8309381-incubator](https://github.com/kevinrushforth/jfx/tree/8309381-incubator) branch, which has the changes needed to support incubator modules. I will create a PR from that branch to implement [JDK-8309381](https://bugs.openjdk.org/browse/JDK-8309381). Those changes include: build scripts (`build.gradle`, `settings.gradle`), qualified exports from `javafx.base`, and a utility class to produce warnings when first using an incubator module.
+
+Note that this `jfx.incubator` branch is meant to be illustrative in nature. It will _never_ be integrated, so the PR based on this branch will remain in Draft state as long as the PR is open (it will _never_ become `rfr`).

build.gradle

@@ -2810,6 +2810,114 @@ project(":controls") {
     addValidateSourceSets(project, sourceSets)
 }
 
+// Add a project declaration for each incubator module here, leaving the
+// incubator placeholder lines as an example.
+// See CSR JDK-8344644 for more information.
+// BEGIN: incubator placeholder
+//project(":incubator.mymod") {
+//    project.ext.buildModule = true
+//    project.ext.includeSources = true
+//    project.ext.moduleRuntime = true
+//    project.ext.moduleName = "jfx.incubator.mymod"
+//    project.ext.incubating = true
+//    ...
+//}
+// END: incubator placeholder
+
+// TODO: incubator template -- follow instruction below, then remove this comment
+// To create an incubator module:
+// 1) apply the changes from this patch
+// 2) Look for "TODO: incubator template" comments, and replace "myfeature"
+//    with the name of your feature
+// 3) Refactor / rename the files under "modules/javafx.incubator.myfeature"
+//    to match the name of your feature.
+// 4) Remove this comment block
+project(":incubator.myfeature") {
+    project.ext.buildModule = true
+    project.ext.includeSources = true
+    project.ext.moduleRuntime = true
+    project.ext.moduleName = "jfx.incubator.myfeature"
+    project.ext.incubating = true
+
+    sourceSets {
+        main
+        shims {
+            java {
+                compileClasspath += sourceSets.main.output
+                runtimeClasspath += sourceSets.main.output
+            }
+        }
+        test {
+            java {
+                compileClasspath += sourceSets.shims.output
+                runtimeClasspath += sourceSets.shims.output
+            }
+        }
+    }
+
+    project.ext.moduleSourcePath = defaultModuleSourcePath
+    project.ext.moduleSourcePathShim = defaultModuleSourcePathShim
+
+    commonModuleSetup(project, [ 'base', 'graphics', 'controls', 'incubator.myfeature' ])
+
+    dependencies {
+        testImplementation project(":base").sourceSets.test.output
+        testImplementation project(":graphics").sourceSets.test.output
+        testImplementation project(":controls").sourceSets.test.output
+        implementation project(':base')
+        implementation project(':graphics')
+        implementation project(':controls')
+    }
+
+    test {
+        jvmArgs "-Djavafx.toolkit=test.com.sun.javafx.pgstub.StubToolkit"
+    }
+
+    def modulePath = "${project.sourceSets.main.java.getDestinationDirectory().get().getAsFile()}"
+    modulePath += File.pathSeparator + "${rootProject.projectDir}/modules/javafx.controls/build/classes/java/main"
+    modulePath += File.pathSeparator + "${rootProject.projectDir}/modules/javafx.graphics/build/classes/java/main"
+    modulePath += File.pathSeparator + "${rootProject.projectDir}/modules/javafx.base/build/classes/java/main"
+
+// TODO: incubator template -- follow instruction below, then remove this comment block
+// The following block is used if and only if you have .css resource files
+// in your incubator module. If you do, uncomment the block and make the
+// appropriate changes for the location of your resource files. Otherwise,
+// delete the block.
+
+//    processResources {
+//      doLast {
+//        def cssFiles = fileTree(dir: "$moduleDir/com/sun/javafx/scene/control/skin")
+//        cssFiles.include "**/*.css"
+//        cssFiles.each { css ->
+//            logger.info("converting CSS to BSS ${css}");
+//
+//            javaexec {
+//                executable = JAVA
+//                workingDir = project.projectDir
+//                jvmArgs += patchModuleArgs
+//                jvmArgs += "--module-path=$modulePath"
+//                jvmArgs += "--add-modules=javafx.graphics"
+//                mainClass = "com.sun.javafx.css.parser.Css2Bin"
+//                args css
+//            }
+//        }
+//      }
+//    }
+//
+//    def copyShimBssTask = project.task("copyShimBss", type: Copy,
+//                            dependsOn: [project.tasks.getByName("compileJava"),
+//                                        project.tasks.getByName("processResources")]) {
+//        from project.moduleDir
+//        into project.moduleShimsDir
+//        include "**/*.bss"
+//    }
+//    processShimsResources.dependsOn(copyShimBssTask)
+
+    addMavenPublication(project, [ 'graphics' , 'controls'])
+
+    addValidateSourceSets(project, sourceSets)
+}
+
 project(":swing") {
 
     // We need to skip setting compiler.options.release for this module,
@@ -3965,7 +4073,24 @@ project(":systemTests") {
         testImplementation project(":swing").sourceSets.test.output
     }
 
-    def dependentProjects = [ 'base', 'graphics', 'controls', 'media', 'jsobject', 'web', 'swing', 'fxml' ]
+    def dependentProjects = [
+        'base',
+        'graphics',
+        'controls',
+        // Add an entry for each incubator module here, leaving the incubator
+        // placeholder lines as an example.
+        // BEGIN: incubator placeholder
+        //'incubator.mymod',
+        // END: incubator placeholder
+
+        // TODO: incubator template -- rename module, then remove this TODO comment
+        'incubator.myfeature',
+        'media',
+        'jsobject',
+        'web',
+        'swing',
+        'fxml'
+    ]
     commonModuleSetup(project, dependentProjects)
 
     File testRunArgsFile = new File(rootProject.buildDir,TESTRUNARGSFILE);
@@ -4407,8 +4532,24 @@ task javadoc(type: Javadoc, dependsOn: createMSPfile) {
     description = "Generates the JavaDoc for all the public API"
     executable = JAVADOC
     def projectsToDocument = [
-            project(":base"), project(":graphics"), project(":controls"), project(":media"),
-            project(":swing"), /*project(":swt"),*/ project(":fxml"), project(":jsobject"), project(":web")]
+        project(":base"),
+        project(":graphics"),
+        project(":controls"),
+        // Add an entry for each incubator module here, leaving the incubator
+        // placeholder lines as an example.
+        // BEGIN: incubator placeholder
+        //project(":incubator.mymod"),
+        // END: incubator placeholder
+
+        // TODO: incubator template -- rename module, then remove this TODO comment
+        project(":incubator.myfeature"),
+        project(":media"),
+        project(":swing"),
+        /*project(":swt"),*/
+        project(":fxml"),
+        project(":jsobject"),
+        project(":web")
+    ]
     source(projectsToDocument.collect({
         [it.sourceSets.main.java]
     }));
@@ -5787,6 +5928,8 @@ compileTargets { t ->
             def jmodName = "${moduleName}.jmod"
             def jmodFile = "${jmodsDir}/${jmodName}"
 
+            def incubating = project.hasProperty("incubating") && project.ext.incubating
+
             // On Windows, copy the native libraries in the jmod image
             // to a "javafx" subdir to avoid conflicting with the Microsoft
             // DLLs that are shipped with the JDK
@@ -5828,6 +5971,10 @@ compileTargets { t ->
                         if (sourceDateEpoch != null) {
                             args("--date", extendedTimestamp)
                         }
+                        if (incubating) {
+                            args("--do-not-resolve-by-default")
+                            args("--warn-if-resolved=incubating")
+                        }
                         args(jmodFile)
                     }
                 }

modules/javafx.base/src/main/java/com/sun/javafx/ModuleUtil.java

@@ -0,0 +1,89 @@
+/*
+ * 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.
+ */
+
+package com.sun.javafx;
+
+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();
+
+    /**
+     * Prints a warning that an incubator module was loaded. This warning is
+     * printed to {@code System.err} one time per module.
+     * An incubator module should call this method from the static initializer
+     * of each primary class in the module. A primary class is a publicly exported
+     * class that provides functionality that can be used by an application.
+     * An incubator module should choose the set of primary classes such that
+     * any application using an incubating API would access at least one of the
+     * primary classes.
+     */
+    public static void incubatorWarning() {
+        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;
+        }
+
+        // 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);
+        }
+    }
+
+    // Prevent instantiation
+    private ModuleUtil() {
+    }
+}

modules/javafx.base/src/main/java/module-info.java

@@ -47,6 +47,14 @@
 
     exports com.sun.javafx to
         javafx.controls,
+        // Add an entry for each incubator module here, leaving the incubator
+        // placeholder lines as an example.
+        // BEGIN: incubator placeholder
+        //jfx.incubator.mymod,
+        // END: incubator placeholder
+
+        // TODO: incubator template -- rename module, then remove this TODO comment
+        jfx.incubator.myfeature,
         javafx.graphics,
         javafx.fxml,
         javafx.media,