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,38 @@
+# NOTES: JavaFX Incubator Modules
+
+## Overview
+
+These are notes regarding the implementation of JavaFX incubator modules.
+
+## Changes / additions in the javafx.incubator branch
+
+The `javafx.incubator` branch has three main types of changes:
+
+1. The [JavaFX Incubator Modules JEP](INCUBATOR-MODULES.md) and these implementation notes.
+2. Changes needed to support incubator modules. These 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.
+3. A sample incubator module, `jfx.incubator.myfeature`.
+
+Note that this 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`).
+
+## RFE: Support incubator modules
+
+The changes reflected in item 2 in the previous section need to be integrated into mainline ahead of the first incubator module, so a separate PR will be made from a branch that has just those changes. In support of this, the needed changes have been highlighted using comments of the following pattern:
+
+```
+// RFE: incubator dependency
+```
+
+These identify the blocks that are needed as part of the RFE to add the needed dependencies. The PR that includes them will remove the `RFE: incubator dependency` line, since that is only there to differentiate those changes needed to support incubator modules in general from those changes that add the specific sample incubator module (`jfx.incubator.myfeature`). The sample incubator module changes must be reverted in the branch that will be used to add the dependencies.
+
+Some of the incubator dependency changes include comments about where to add build logic when creating an incubator module. Those comment will be part of the incubator dependency PR. For example:
+
+```
+        // RFE: incubator dependency
+        // Add an entry for each incubator module here, leaving the incubator
+        // placeholder lines as an example.
+        // BEGIN: incubator placeholder
+        //'incubator.mymod',
+        // END: incubator placeholder
+```
+
+When proposing the incubator dependency PR, the `// RFE: incubator dependency` line will be removed (since it only exists to help identify the needed dependency), but the rest of the comment block (e.g., starting with `Add an entry for each incubator ...`) will be part of the PR.

build.gradle

@@ -2874,6 +2874,114 @@ project(":controls") {
     addValidateSourceSets(project, sourceSets)
 }
 
+// RFE: incubator dependency
+// Add a project declaration for each incubator module here, leaving the
+// incubator placeholder lines as an example.
+// 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,
@@ -4030,7 +4138,28 @@ project(":systemTests") {
         testImplementation project(":swing").sourceSets.test.output
     }
 
-    def dependentProjects = [ 'base', 'graphics', 'controls', 'media', 'jsobject', 'web', 'swing', 'fxml' ]
+    // RFE: incubator dependency
+    def dependentProjects = [
+        'base',
+        'graphics',
+        'controls',
+
+        // RFE: incubator dependency
+        // 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 testJavaPolicyFile = new File(rootProject.buildDir, TESTJAVAPOLICYFILE);
@@ -4475,9 +4604,29 @@ task javadoc(type: Javadoc, dependsOn: createMSPfile) {
     group = "Basic"
     description = "Generates the JavaDoc for all the public API"
     executable = JAVADOC
+    // RFE: incubator dependency
     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"),
+
+        // RFE: incubator dependency
+        // 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]
     }));
@@ -5843,6 +5992,8 @@ compileTargets { t ->
                 def modnames = []
                 moduleProjList.each { project ->
                     if (project.hasProperty("moduleName") && project.buildModule) {
+                        // RFE: incubator dependency
+                        def incubating = project.hasProperty("incubating") && project.ext.incubating
                         modnames << project.ext.moduleName
                         File dir;
                         if (project.sourceSets.hasProperty('shims')) {
@@ -5854,16 +6005,19 @@ compileTargets { t ->
                         def dstModuleDir = cygpath(dir.path)
                         modpath << "${dstModuleDir}"
 
-                        String themod = dir.toURI()
-                        testJavaPolicyFile <<  "grant codeBase \"${themod}\" {\n" +
-                        "    permission java.security.AllPermission;\n" +
-                        "};\n"
-
-                        dir = new File(TEST_SDK_PATH, "sdk/lib/${project.ext.moduleName}.jar")
-                        themod = dir.toURI()
-                        runJavaPolicyFile <<  "grant codeBase \"${themod}\" {\n" +
-                        "    permission java.security.AllPermission;\n" +
-                        "};\n"
+                        // RFE: incubator dependency
+                        if (!incubating) {
+                            String themod = dir.toURI()
+                            testJavaPolicyFile <<  "grant codeBase \"${themod}\" {\n" +
+                            "    permission java.security.AllPermission;\n" +
+                            "};\n"
+
+                            dir = new File(TEST_SDK_PATH, "sdk/lib/${project.ext.moduleName}.jar")
+                            themod = dir.toURI()
+                            runJavaPolicyFile <<  "grant codeBase \"${themod}\" {\n" +
+                            "    permission java.security.AllPermission;\n" +
+                            "};\n"
+                        }
                     }
                 }
 
@@ -5909,6 +6063,9 @@ compileTargets { t ->
             def jmodName = "${moduleName}.jmod"
             def jmodFile = "${jmodsDir}/${jmodName}"
 
+            // RFE: incubator dependency
+            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
@@ -5950,6 +6107,11 @@ compileTargets { t ->
                         if (sourceDateEpoch != null) {
                             args("--date", extendedTimestamp)
                         }
+                        // RFE: incubator dependency
+                        if (incubating) {
+                            args("--do-not-resolve-by-default")
+                            args("--warn-if-resolved=incubating")
+                        }
                         args(jmodFile)
                     }
                 }