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?