Legacy mode, module mode, mixed mode

[Karen Kinnear]

Mandy,

This is really helpful - thank you for writing this up. A few minor  
questions/
comments below.
On Jun 2, 2010, at 7:30 PM, Mandy Chung wrote:

> 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

Do we also want to outline options for applications that use .jnlp or
command-line without a jar file?
>
> 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.
How?
>
>  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.
I'm not sure I understand the overall search order when we mix
legacy apps and modules.

>
>  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?

>
thanks,
Karen