Legacy mode, module mode, mixed mode

[Mandy Chung]

This note attempts to describe the different execution modes for
running legacy/modularized applications and how the current and
long-term implementation supports them.

I'll be sending out the webrev for the legacy mode support and
I think this note will help set the basis for the legacy mode
support discussion.

0. Module Images

   A module image consists of the jdk base module and a set of platform
   modules.  The jdk modules are installed in the system module
   library ($JAVA_HOME/lib/modules).

   jre-module-image is the full JRE (equivalent the legacy j2re-image).
   The "jdk.jre" module is the aggregator module representing the entire
   JRE.

   jdk-module-image is the full JDK (equivalent to the legacy j2sdk-image).
   The "jdk" module is the aggregator module representing the entire JDK.

   rt.jar, tools.jar and other jar files no longer exist in the module
   image.

I. Execution Mode

There will be 3 different execution modes.

A) Module mode

   Modularized applications will run in module mode in which classes
   are loaded from modules installed in module libraries.

   To run in module mode:
     $ java -L lib -m foo

B) Legacy mode

   Legacy applications that are pure class-path-based will run on
   a module image provided that they:
   * Don't depend upon the internal structure of the JDK/JRE
   * Only use supported APIs and other interfaces

   [Tools or applications depending upon files in $JAVA_HOME will
    require some change.]

   In the legacy mode, the system classes are loaded from the platform
   modules installed in the system module library whereas non-system
   classes are loaded from classpath, extension mechanism or custom
   class loader as it is today.

   To run in legacy mode:
     $ java -cp classes com.foo.Main

C) Mixed mode
C.a) A legacy application running with classpath and with third-party modules

   This will be supported to ease migration to enable libraries to
   migrate to modules which legacy applications can continue to work.

   This will require some change in the legacy applications to specify its
   required modules and versions.

   One option is to extend the manifest of the legacy application jar file:
      Main-Class: com.greetings.Main
      Required-Modules: org.astro at 1.2.3
      Required-Platform-Modules: jdk.base, jdk.logging

C.b) A modularized application to run with jars and classpath

   This will not be supported.  Can be mitigated by creating a tool that
   can convert simple jar files into modules (to be investigated).

II. Bootclasspath

A) Module mode
   Bootclasspath will no longer exist.  The -Xbootclasspath{/p,/a}
   options are not supported.

   See below III for the current implementation.

B) Legacy mode

   There are various ways to alter the bootclasspath that will continue
   to work in legacy mode:

   1. -Xbootclasspath/p to prepend bootclasspath
   2. Endorsed directory to prepend the default bootclasspath
      via -Djava.endorsed.dirs (one or more directories) and
      the default $JAVA_HOME/lib/endorsed directory
   3. -Xbootclasspath/a to append bootclasspath
   4. JVMTI and java.lang.instrument to append the bootclasspath

   We need a solution to replace "alt-rt.jar" that is prepended
   in the bootclasspath when -XX:+AggressiveOpts is specified.

C) Mixed mode
C.a) Same as II.B above
C.b) Not supported

III. Finding system classes from the platform modules

   The current implementation leverages the bootclasspath so that
   the VM built-in class loader can find system classes.  Ultimately,
   we want to eliminate the bootclasspath.  The VM will find the
   primordial classes from the boot module through some jigsaw
   native interface.

A) Module mode

1. Current implementation

   - The module boot path is passed by the java launcher as a
     "sun.java.launcher.module.boot" system property and the
     VM will find the primordial classes from that path.

   - org.openjdk.jigsaw.BootLoader is the module loader to
     load system classes.  The current implementation extends
     the bootclasspath at startup time for all platform modules
     required by the modularized application and delegates to
     the null loader to define the system classes.

2. Long-term solution

   The VM needs the ability to find classes from the boot module
   and the module library to replace the bootclasspath search.

   In addition, there is an optimization in the VM that during
   class resolution, if the initiating loader is null, the
   defining loader has to be null and so the VM can find a class
   from the bootclasspath and load it directly rather than calling
   out to Java.  The VM may need a way to determine if a class
   is in a platform context (equivalent to if a class can be
   found in the bootclasspath).

   This work is independent to the legacy mode support described
   below.

B) Legacy mode

1. Current implementation

   - The java launcher constructs the bootclasspath for all modules
     installed in the system module library and set the -Xbootclasspath/p
     option before launching the VM.

   - The default bootclasspath also hardcodes the path of the
     boot module in the VM for creating the JVM directly from other
     applications.

2. Long-term solution

   This will remove the hack in the launcher that constructs the
   bootclasspath.  In legacy mode, it needs to set up the platform
   contexts from which the VM can find system classes during the
   startup.

   Since BootLoader, the module loader for the platform contexts,
   delegates to the null loader to define the system classes,
   the current implementation (III.A.1) will continue to use
   the bootclasspath searching.  When III.A.2 is implemented,
   the VM will use the module library searching.

C) Mixed mode
C.a) A legacy class-path-based application to run with third-party
     modules

   The legacy application will need to specify the required third-
   party modules and the legacy launcher needs to set up a configuration
   that resolves the specified dependencies at startup time.
   In addition, the application can also specify the platform modules
   it requires to override the default one.

   A special class loader (say LegacyLoader) will be created for finding
   classes from the required modules.  LegacyLoader will be the
   parent class loader of the extension class loader so that the
   required modules will always be searched first.  The application
   class loader and extension class loader will continue to work as it is.

   Issues:
   1. Existing applications may depend on the "sun.boot.class.path"
      system property.
   2. The parent of extension class loader is expected to be null.
   3. Should the third-party modules be searched before the extension
      class path?