Summary

Support JavaFX Incubator Modules. 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.

Problem

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.

Solution

Add the necessary build-time support for incubator modules, specifically:

• Add link-time flags to the incubator jmod files to not resolve incubator modules by default and warn when resolving (same as is done for JDK incubator modules)
• Provide a utility that incubator modules will call at runtime to provide the same warning when not using a jlinked runtime that includes those modules

See JavaFX Incubator Modules, which builds on JEP 11, for more information.

Specification

There is no public API associated with this feature, but we specify the following requirements on JavaFX Incubator Modules:

• An incubator module must have the jfx.incubator. prefix in its module name
• All exported APIs in an incubator module must have the jfx.incubator. prefix in their exported package names
• Non-incubator modules must not specify requires transitive dependencies upon incubator modules, or otherwise expose types exported from incubator modules in their own exported APIs
• An incubator module must set project.ext.incubating = true in the module definition in the build.gradle script so that the jmod files produced by the build have the correct attributes set
• An incubator module must call the (internal) utility method com.sun.javafx.ModuleUtil::incubatorWarning from the static block of all primary classes in their module.

If an incubating module is linked into the JDK via jlink, it will not be resolved by default. The Java launcher will print the following warning if the incubating module is resolved:

WARNING: Using incubator modules: $MODULENAME

If an incubating module is not linked into the JDK via jlink, the following warning will be printed the first time any of the "primary" classes of the module are loaded:

WARNING: Using incubator modules: $MODULENAME

If an incubating module is placed on the classpath, the following warning will be printed for each package, the first time any of the "primary" classes of that package are loaded. This is not a supported mode of operation.

WARNING: Using incubating API from an unnamed module: $PACKAGENAME