JavaFX must warn when the javafx.* modules are loaded from the classpath

Summary

The JavaFX classes must be loaded from a set of named javafx.* modules. This restriction should be documented, and a warning should be logged if the JavaFX classes are loaded from the classpath.

Problem

JavaFX is built and distributed as a set of named modules, each in its own modular jar file. This supports running both modular and non-modular applications.

The JavaFX runtime expects its classes to be loaded from a set of named javafx.* modules, and does not support loading those modules from the classpath. The Java launcher will fail to load applications that extend javafx.application.Application unless the javafx.graphics module is on the module path.

Applications that do not extend javafx.application.Application can be loaded even if the javafx.* classes are loaded from the classpath, but this is an unsupported configuration.

This creates the perception that there is a problem with the standard case of loading a subclass of javafx.application.Application, since it fails to load in the case where the JavaFX classes are loaded from the classpath. Further, allowing applications to run in an unsupported mode that likely has bugs creates a maintenance burden. Another problem is that when the JavaFX classes are loaded from the classpath, it breaks encapsulation, since we mo longer get the benefit of the java module system.

Solution

Modify the platform startup code to log a warning if the javafx.graphics classes are not loaded from the named javafx.graphics module. Document this restriction in the javafx.graphics module docs, the Application class docs, and the Platform::startup method docs.

Specification

javafx/application/Application.java

@@ -80,6 +80,12 @@
  * {@link #stop} method returns or {@link System#exit} is called.
  * </p>
  *
+ * <p><b>Note:</b> The JavaFX classes must be loaded from a set of
+ * named {@code javafx.*} modules on the <em>module path</em>.
+ * Loading the JavaFX classes from the classpath is not supported.
+ * See {@link Platform#startup(Runnable) Platform.startup}
+ * for more information.
+ *
  * <p><b>Deploying an Application as a Module</b></p>
  * <p>
  * If the {@code Application} subclass is in a named module then that class

javafx/application/Platform.java

@@ -90,6 +90,14 @@
      * that the JavaFX runtime be started once.
      * </p>
      *
+     * <p><b>Note:</b> The JavaFX classes must be loaded from a set of
+     * named {@code javafx.*} modules on the <em>module path</em>.
+     * Loading the JavaFX classes from the classpath is not supported.
+     * A warning is logged when the JavaFX runtime is started if the JavaFX
+     * classes are not loaded from the expected named module.
+     * This warning is logged regardless of whether the JavaFX runtime was
+     * started by calling this method or automatically as described above.
+     *
      * @throws IllegalStateException if the JavaFX runtime is already running
      *
      * @param runnable the Runnable whose run method will be executed on the

javafx.graphics : module-info.java

@@ -30,6 +30,12 @@
  * as well as APIs for animation, css, concurrency, geometry, printing, and
  * windowing.
  *
+ * <p><b>Note:</b> The JavaFX classes must be loaded from a set of
+ * named {@code javafx.*} modules on the <em>module path</em>.
+ * Loading the JavaFX classes from the classpath is not supported.
+ * See {@link javafx.application.Platform#startup(Runnable) Platform.startup}
+ * for more information.
+ *
  * @moduleGraph
  * @since 9
  */