8309381: Support JavaFX incubator modules

Reviewed-by: angorya, arapte

Author: kevinrushforth

build.gradle

@@ -2810,6 +2810,20 @@ 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
+
 project(":swing") {
 
     // We need to skip setting compiler.options.release for this module,
@@ -3965,7 +3979,21 @@ 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
+        'media',
+        'jsobject',
+        'web',
+        'swing',
+        'fxml'
+    ]
     commonModuleSetup(project, dependentProjects)
 
     File testRunArgsFile = new File(rootProject.buildDir,TESTRUNARGSFILE);
@@ -4407,8 +4435,21 @@ 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
+        project(":media"),
+        project(":swing"),
+        /*project(":swt"),*/
+        project(":fxml"),
+        project(":jsobject"),
+        project(":web")
+    ]
     source(projectsToDocument.collect({
         [it.sourceSets.main.java]
     }));
@@ -5787,6 +5828,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 +5871,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,11 @@
 
     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
         javafx.graphics,
         javafx.fxml,
         javafx.media,

settings.gradle

@@ -23,11 +23,30 @@
  * questions.
  */
 
-include "base", "graphics", "controls", "swing", "swt", "fxml", "jsobject", "web", "media", "systemTests"
+include "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
+        "swing",
+        "swt",
+        "fxml",
+        "jsobject",
+        "web",
+        "media",
+        "systemTests"
 
 project(":base").projectDir = file("modules/javafx.base")
 project(":graphics").projectDir = file("modules/javafx.graphics")
 project(":controls").projectDir = file("modules/javafx.controls")
+// Add an entry for each incubator module here, leaving the incubator
+// placeholder lines as an example.
+// BEGIN: incubator placeholder
+//project(":incubator.mymod").projectDir = file("modules/jfx.incubator.mymod")
+// END: incubator placeholder
 project(":swing").projectDir = file("modules/javafx.swing")
 project(":swt").projectDir = file("modules/javafx.swt")
 project(":fxml").projectDir = file("modules/javafx.fxml")