JEP 261: Module System

AuthorsAlan Bateman, Alex Buckley, Jonathan Gibbons, Mark Reinhold
OwnerMark Reinhold
Created2014/10/23 15:05
Updated2017/09/22 20:18
TypeFeature
StatusClosed / Delivered
ScopeSE
JSR376
Discussionjigsaw dash dev at openjdk dot java dot net
EffortXL
DurationL
Priority1
Reviewed byAlan Bateman, Alex Buckley, Chris Hegarty, Jonathan Gibbons, Mandy Chung, Paul Sandoz
Endorsed byBrian Goetz
Release9
Issue8061972
BlocksJEP 200: The Modular JDK
JEP 282: jlink: The Java Linker
DependsJEP 220: Modular Run-Time Images
JEP 260: Encapsulate Most Internal APIs

Summary

Implement the Java Platform Module System, as specified by JSR 376, together with related JDK-specific changes and enhancements.

Description

The Java Platform Module System (JSR 376) specifies changes and extensions to the Java programming language, the Java virtual machine, and the standard Java APIs. This JEP implements that specification. As a consequence, the javac compiler, the HotSpot virtual machine, and the run-time libraries implement modules as a fundamental new kind of Java program component and provide for the reliable configuration and strong encapsulation of modules in all phases of development.

This JEP also changes, extends, and adds JDK-specific tools and APIs, which are outside the scope of the JSR, that are related to compilation, linking, and execution. Related changes to other tools and APIs, e.g., the javadoc tool and the Doclet API, are the subject of separate JEPs.

This JEP assumes that the reader is familiar with the latest State of the Module System document and also the other Project Jigsaw JEPs:

Phases

To the familiar phases of compile time (the javac command) and run time (the java run-time launcher) we add the notion of link time, an optional phase between the two in which a set of modules can be assembled and optimized into a custom run-time image. The linking tool, jlink, is the subject of JEP 282; many of the new command-line options implemented by javac and java are also implemented by jlink.

Module paths

The javac, jlink, and java commands, as well as several others, now accept options to specify various module paths. A module path is a sequence, each element of which is either a module definition or a directory containing module definitions. Each module definition is either

In the latter case the directory tree can be a compiled module definition, populated with individual class and resource files and a module-info.class file at the root or, at compile time, a source module definition, populated with individual source files and a module-info.java file at the root.

A module path, like other kinds of paths, is specified by a string of path names separated by the host platform's path-separator character (':' on most platforms, ';' on Windows).

Module paths are very different from class paths: Class paths are a means to locate definitions of individual types and resources, whereas module paths are a means to locate definitions of whole modules. Each element of a class path is a container of type and resource definitions, i.e., either a JAR file or an exploded, package-hierarchical directory tree. Each element of a module path, by contrast, is a module definition or a directory which each element in the directory is a module definition, i.e., a container of type and resource definitions, i.e., either a modular JAR file, a JMOD file, or an exploded module directory.

During the resolution process the module system locates a module by searching along several different paths, dependent upon the phase, and also by searching the compiled modules built-in to the environment, in the following order:

The module definitions present on these paths, together with the system modules, define the universe of observable modules.

When searching a module path for a module of a particular name, the module system takes the first definition of a module of that name. Version strings, if present, are ignored; if an element of a module path contains definitions of multiple modules with the same name then resolution fails and the compiler, linker, or virtual machine will report an error and exit. It is the responsibility of build tools and container applications to configure module paths so as to avoid version conflicts; it is not a goal of the module system to address the version-selection problem.

Root modules

The module system constructs a module graph by resolving the transitive closure of the dependences of a set of root modules with respect to the set of observable modules.

When the compiler compiles code in the unnamed module, or the java launcher is invoked and the main class of the application is loaded from the class path into the unnamed module of the application class loader, then the default set of root modules for the unnamed module is computed as follows:

Otherwise, the default set of root modules depends upon the phase:

It is occasionally necessary to add modules to the default root set in order to ensure that specific platform, library, or service-provider modules will be present in the resulting module graph. In any phase the option

--add-modules <module>(,<module>)*

where <module> is a module name, adds the indicated modules to the default set of root modules. This option may be used more than once.

As a special case at run time, if <module> is ALL-DEFAULT then the default set of root modules for the unnamed module, as defined above, is added to the root set. This is useful when the application is a container that hosts other applications which can, in turn, depend upon modules not required by the container itself.

As a further special case at run time, if <module> is ALL-SYSTEM then all system modules are added to the root set, whether or not they are in the default set. This is sometimes needed by test harnesses. This option will cause many modules to be resolved; in general, ALL-DEFAULT should be preferred.

As a final special case, at both run time and link time, if <module> is ALL-MODULE-PATH then all observable modules found on the relevant module paths are added to the root set. ALL-MODULE-PATH is valid at both compile time and run time. This is provided for use by build tools such as Maven, which already ensure that all modules on the module path are needed. It is also a convenient means to add automatic modules to the root set.

Limiting the observable modules

It is sometimes useful to limit the observable modules for, e.g., debugging, or to reduce the number of modules resolved when the main module is the unnamed module defined by the application class loader for the class path. The --limit-modules option can be used, in any phase, to do this. Its syntax is:

--limit-modules <module>(,<module>)*

where <module> is a module name. The effect of this option is to limit the observable modules to those in the transitive closure of the named modules plus the main module, if any, plus any further modules specified via the --add-modules option.

(The transitive closure computed for the interpretation of the --limit-modules option is a temporary result, used only to compute the limited set of observable modules. The resolver will be invoked again in order to compute the actual module graph.)

Increasing readability

When testing and debugging it is sometimes necessary to arrange for one module to read some other module, even though the first module does not depend upon the second via a requires clause in its module declaration. This may be needed to, e.g., enable a module under test to access the test harness itself, or to access libraries related to the harness. The --add-reads option can be used, at both compile time and run time, to do this. Its syntax is:

--add-reads <source-module>=<target-module>

where <source-module> and <target-module> are module names.

The --add-reads option can be used more than once. The effect of each instance is to add a readability edge from the source module to the target module. This is, essentially, a command-line form of a requires clause in a module declaration, or an invocation of an unrestricted form of the Module::addReads method. As a consequence, code in the source module will be able to access types in a package of the target module at both compile time and run time if that package is exported via an exports clause in the source module's declaration, an invocation of the Module::addExports method, or an instance of the --add-exports option (defined below). Such code will, additionally, be able to access types in a package of the target module at run time if that module is declared to be open or if that package is opened via an opens clause in the source module's declaration, an invocation of the Module::addOpens method, or an instance of the --add-opens option (also defined below).

If, for example, a test harness injects a white-box test class into the java.management module, and that class extends an exported utility class in the (hypothetical) testng module, then the access it requires can be granted via the option

--add-reads java.management=testng

As a special case, if the <target-module> is ALL-UNNAMED then readability edges will be added from the source module to all present and future unnamed modules, including that corresponding to the class path. This allows code in modules to be tested by test frameworks that have not, themselves, yet been converted to modular form.

Breaking encapsulation

It is sometimes necessary to violate the access-control boundaries defined by the module system, and enforced by the compiler and virtual machine, in order to allow one module to access some of the unexported types of another module. This may be desirable in order to, e.g., enable white-box testing of internal types, or to expose unsupported internal APIs to code that has come to depend upon them. The --add-exports option can be used, at both compile time and run time, to do this. Its syntax is:

--add-exports <source-module>/<package>=<target-module>(,<target-module>)*

where <source-module> and <target-module> are module names and <package> is the name of a package.

The --add-exports option can be used more than once, but at most once for any particular combination of source module and package name. The effect of each instance is to add a qualified export of the named package from the source module to the target module. This is, essentially, a command-line form of an exports clause in a module declaration, or an invocation of an unrestricted form of the Module::addExports method. As a consequence, code in the target module will be able to access public types in the named package of the source module if the target module reads the source module, either via a requires clause in its module declaration, an invocation of the Module::addReads method, or an instance of the --add-reads option.

If, for example, the module jmx.wbtest contains a white-box test for the unexported com.sun.jmx.remote.internal package of the java.management module, then the access it requires can be granted via the option

--add-exports java.management/com.sun.jmx.remote.internal=jmx.wbtest

As a special case, if the <target-module> is ALL-UNNAMED then the source package will be exported to all unnamed modules, whether they exist initially or are created later on. Thus access to the sun.management package of the java.management module can be granted to all code on the class path via the option

--add-exports java.management/sun.management=ALL-UNNAMED

The --add-exports option enables access to the public types of a specified package. It is sometimes necessary to go further and enable access to all non-public elements via the setAccessible method of the core reflection API. The --add-opens option can be used, at run time, to do this. It has the same syntax as the --add-exports option:

--add-opens <source-module>/<package>=<target-module>(,<target-module>)*

where <source-module> and <target-module> are module names and <package> is the name of a package.

The --add-opens option can be used more than once, but at most once for any particular combination of source module and package name. The effect of each instance is to add a qualified open of the named package from the source module to the target module. This is, essentially, a command-line form of an opens clause in a module declaration, or an invocation of an unrestricted form of the Module::addOpens method. As a consequence, code in the target module will be able to use the core reflection API to access all types, public and otherwise, in the named package of the source module so long as the target module reads the source module.

Open packages are indistinguishable from non-exported packages at compile time, so the --add-opens option may not be used in that phase.

The --add-exports and --add-opens options must be used with great care. You can use them to gain access to an internal API of a library module, or even of the JDK itself, but you do so at your own risk: If that internal API is changed or removed then your library or application will fail.

Patching module content

When testing and debugging it is sometimes useful to replace selected class files or resources of specific modules with alternate or experimental versions, or to provide entirely new class files, resources, and even packages. This can be done via the --patch-module option, at both compile time and run time. Its syntax is:

--patch-module <module>=<file>(<pathsep><file>)*

where <module> is a module name, <file> is the filesystem path name of a module definition, and <pathsep> is the host platform's path-separator character.

The --patch-module option can be used more than once, but at most once for any particular module name. The effect of each instance is to change how the module system searches for a type in the specified module. Before it checks the actual module, whether part of the system or defined on a module path, it first checks, in order, each module definition specified to the option. A patch path names a sequence of module definitions but it is not a module path, since it has leaky, class-path-like semantics. This allows a test harness, e.g., to inject multiple tests into the same package without having to copy all of the tests into a single directory.

The --patch-module option cannot be used to replace module-info.class files. If a module-info.class file is found in a module definition on a patch path then a warning will be issued and the file will be ignored.

If a package found in a module definition on a patch path is not already exported or opened by that module then it will, still, not be exported or opened. It can be exported or opened explicitly via either the reflection API or the --add-exports or --add-opens options.

The --patch-module option replaces the -Xbootclasspath:/p option, which has been removed (see below).

The --patch-module option is intended only for testing and debugging. Its use in production settings is strongly discouraged.

Compile time

The javac compiler implements the options described above, as applicable to compile time: --module-source-path, --upgrade-module-path, --system, --module-path, --add-modules, --limit-modules, --add-reads, --add-exports, and --patch-module.

The compiler operates in one of three modes, each of which implements additional options.

In legacy mode the compiler behaves in essentially the same way as it does in JDK 8.

Single-module mode is used to compile code organized in a traditional package-hierarchical directory tree. It is the natural replacement for simple uses of legacy mode of the form

$ javac -d classes -classpath classes -sourcepath src Foo.java

If a module descriptor in the form of a module-info.java or module-info.class file is specified on the command line, or is found on the source path or the class path, then source files will be compiled as members of the module named by that descriptor and that module will be the sole root module. Otherwise if the --module <module> option is present then source files will be compiled as members of <module>, which will be the root module. Otherwise source files will be compiled as members of the unnamed module, and the root modules will be computed as described above.

It is possible to put arbitrary classes and JAR files on the class path in this mode, but that is not recommended since it amounts to treating those classes and JAR files as part of the module being compiled.

Multi-module mode is used to compile one or more modules, whose source code is laid out in exploded-module directories on the module source path. In this mode the module membership of a type is determined by the position of its source file in the module source path, so each source file specified on the command line must exist within an element of that path. The set of root modules is the set of modules for which at least one source file is specified.

In contrast to the other modes, in this mode an output directory must be specified via the -d option. The output directory will be structured as an element of a module path, i.e., it will contain exploded-module directories which themselves contain class and resource files. If the compiler finds a module on the module source path but cannot find the source file for some type in that module then it will search the output directory for the corresponding class file.

In large systems the source code for a particular module may be spread across several different directories. In the JDK itself, e.g., the source files for a module may be found in any one of the directories src/<module>/share/classes, src/<module>/<os>/classes, or build/gensrc/<module>, where <os> is the name of the target operating system. To express this in a module source path while preserving module identities we allow each element of such a path to use braces ({ and }) to enclose commas-separated lists of alternatives and a single asterisk (*) to stand for the module name. The module source path for the JDK can then be written as

{src/*/{share,<os>}/classes,build/gensrc/*}

In both of the modular modes the compiler will, by default, generate various warnings related to the module system; these may be disabled via the option -Xlint:-module. More precise control of these warnings is available via the exports, opens, requires-automatic, and requires-transitive-automatic keys for the -Xlint option.

The new option --module-version <version> may be used to specify the version strings of the modules being compiled.

Class-file attributes

A JDK-specific class-file attribute, ModuleTarget, optionally records the target operating system and architecture of the module descriptor that contains it. Its format is:

ModuleTarget_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 os_arch_index; // index to a CONSTANT_utf8_info structure
}

The UTF-8 string in the constant pool at os_arch_index has the format <os>-<arch>, where <os> is typically one of linux, macos, solaris, or windows, and <arch> is typically one of x86, amd64, sparcv9, arm, or aarch64.

Packaging: Modular JAR files

The jar tool can be used without change to create modular JAR files, since a modular JAR file is just a JAR file with a module-info.class file in its root directory.

The jar tool implements the following new options to allow the insertion of additional information into module descriptors as modules are packaged:

The jar tool's --help option can be used to show a complete summary of its command-line options.

Two new JDK-specific JAR-file manifest attributes are defined to correspond to the --add-exports and --add-opens command-line options:

The value of each attribute is a space-separated list of slash-separated module-name/package-name pairs. A <module>/<package> pair in the value of an Add-Exports attribute has the same meaning as the command-line option --add-exports <module>/<package>=ALL-UNNAMED. A <module>/<package> pair in the value of an Add-Opens attribute has the same meaning as the command-line option --add-opens <module>/<package>=ALL-UNNAMED.

Each attribute can occur at most once, in the main section of a MANIFEST.MF file. A particular pair can be listed more than once. If a specified module was not resolved, or if a specified package does not exist, then the corresponding pair is ignored. These attributes are interpreted only in the main executable JAR file of an application, i.e., in the JAR file specified to the -jar option of the Java run-time launcher; they are ignored in all other JAR files.

Packaging: JMOD files

The new JMOD format goes beyond JAR files to include native code, configuration files, and other kinds of data that do not fit naturally, if at all, into JAR files. JMOD files are used to package the modules of the JDK itself; they can also be used by developers to package their own modules, if desired.

JMOD files can be used at compile time and link time, but not at run time. To support them at run time would require, in general, that we be prepared to extract and link native-code libraries on-the-fly. This is feasible on most platforms, though it can be very tricky, and we have not seen many use cases that require this capability, so for simplicity we have chosen to limit the utility of JMOD files in this release.

A new command-line tool, jmod, can be used to create, manipulate, and examine JMOD files. Its general syntax is:

$ jmod (create|extract|list|describe|hash) <options> <jmod-file>

For the create subcommand, <options> can include the --main-class, --module-version, --hash-modules, and ---module-path options described above for the jar tool, and also:

The extract subcommand accepts a single option, --dir, to indicate the directory into which the content of the specified JMOD file should be written. The directory will be created if it does not exist. If this option is not present then the content will be extracted into the current directory.

The list subcommand lists the content of the specified JMOD file; the describe subcommand displays the module descriptor of the specified JMOD file, in the same format as the --describe-module options of the jar and java commands. These subcommands accept no options.

The hash subcommand can be used to hash an existing set of JMOD files. It requires both the --module-path and --hash-modules options.

The jmod tool's --help option can be used to show a complete summary of its command-line options.

The details of the command-line linking tool, jlink, are described in JEP 282. At a high level its general syntax is:

$ jlink <options> ---module-path <modulepath> --output <path>

where the ---module-path option specifies the set of observable modules to be considered by the linker and the --output option specifies the path of the directory that will contain the resulting run-time image. The other <options> can include the ---limit-modules and ---add-modules options, described above, as well as additional linker-specific options.

The jlink tool's --help option can be used to show a complete summary of its command-line options.

Run time

The HotSpot virtual machine implements the options described above, as applicable to run time: --upgrade-module-path, --module-path, --add-modules, --limit-modules, --add-reads, --add-exports, --add-opens, and --patch-module. These options can be passed to the command-line launcher, java, and also to the JNI invocation API.

An additional option specific to this phase and supported by the launcher is:

Additional diagnostic options supported by the launcher include:

The stack traces generated for exceptions at run time have been extended to include, when present, the names and version strings of relevant modules. The detail strings of exceptions such as ClassCastException, IllegalAccessException, and IllegalAccessError have also been updated to include module information.

The existing -jar option has been enhanced so that if the manifest file of the JAR file being launched contains a Launcher-Agent-Class attribute then the JAR file is launched as both an application and as an agent for that application. This allows java -jar foo.jar to be used in place of the more verbose java -javaagent:foo.jar -jar foo.jar.

Relaxed strong encapsulation

In this release the strong encapsulation of some of the JDK's packages is relaxed by default, as permitted by the Java SE 9 Platform Specification. This relaxation is controlled at run time by a new launcher option, --illegal-access, which works as follows:

When deny becomes the default illegal-access mode then permit will likely remain supported for at least one release, so that developers can continue to migrate their code. The permit, warn, and debug modes will, over time, be removed, as will the --illegal-access option itself. (For launch-script compatibility the unsupported modes will most likely just be ignored, after issuing a warning to that effect.)

The default mode, --illegal-access=permit, is intended to make you aware when you have code on the class path that reflectively accesses some JDK-internal API at least once. To prepare for the future you can use the warn or debug modes to learn about all such accesses. For each library or framework on the class path that requires illegal access you have two options:

If you must continue to use a component that requires illegal access then you can eliminate the warning messages by using one or more --add-opens options to open just those internal packages to which access is required.

To verify that your application is ready for the future, run it with --illegal-access=deny along with any necessary --add-opens options. Any remaining illegal-access errors will most likely be due to static references from compiled code to JDK-internal APIs. You can identify those by running the jdeps tool with the --jdk-internals option. (The run-time system does not issue warnings for illegal static-access operations because that would require deep VM changes and degrade performance.)

The warning message issued when an illegal reflective-access operation is detected has the following form:

WARNING: Illegal reflective access by $PERPETRATOR to $VICTIM

where:

In the default mode, --illegal-access=permit, at most one of these warning messages will be issued, accompanied by additional instructive text. Here is an example, from running Jython:

$ java -jar jython-standalone-2.7.0.jar
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper (file:/tmp/jython-standalone-2.7.0.jar) to method sun.nio.ch.SelChImpl.getFD()
WARNING: Please consider reporting this to the maintainers of jnr.posix.JavaLibCHelper
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
Jython 2.7.0 (default:9987c746f838, Apr 29 2015, 02:25:11) 
[OpenJDK 64-Bit Server VM (Oracle Corporation)] on java9
Type "help", "copyright", "credits" or "license" for more information.
>>> ^D

The run-time system makes a best-effort attempt to suppress duplicate warnings for the same $PERPETRATOR and $VICTIM.

An extended example

Suppose we have an application module, com.foo.bar, which depends upon a library module, com.foo.baz. If we have the source code for both modules in the module-path directory src:

src/com.foo.bar/module-info.java
src/com.foo.bar/com/foo/bar/Main.java
src/com.foo.baz/module-info.java
src/com.foo.baz/com/foo/baz/BazGenerator.java

then we can compile them, together:

$ javac --module-source-path src -d mods $(find src -name '*.java')

The output directory, mods, is a module-path directory containing exploded, compiled definitions of the two modules:

mods/com.foo.bar/module-info.class
mods/com.foo.bar/com/foo/bar/Main.class
mods/com.foo.baz/module-info.class
mods/com.foo.baz/com/foo/baz/BazGenerator.class

Assuming that the com.foo.bar.Main class contains the application's entry point, we can run these modules as-is:

$ java -p mods -m com.foo.bar/com.foo.bar.Main

Alternatively, we can package them up into modular JAR files:

$ jar --create -f mlib/com.foo.bar-1.0.jar \
      --main-class com.foo.bar.Main --module-version 1.0 \
      -C mods/com.foo.bar .
$ jar --create -f mlib/com.foo.baz-1.0.jar \
      --module-version 1.0 -C mods/com.foo.baz .

The mlib directory is a module-path directory containing the packaged, compiled definitions of the two modules:

$ ls -l mlib
-rw-r--r-- 1501 Sep  6 12:23 com.foo.bar-1.0.jar
-rw-r--r-- 1376 Sep  6 12:23 com.foo.baz-1.0.jar

We can now run the packaged modules directly:

$ java -p mlib -m com.foo.bar

jtreg enhancements

The jtreg test harness supports a new declarative tag, @modules, to express a test's dependences upon the modules in the system being tested. It takes a series of space-separated arguments, each of which can be of the form

A default set of @modules arguments, which will be used for all tests in a directory hierarchy that do not include such a tag, can be specified as the value of the modules property in a TEST.ROOT file or in any TEST.properties file.

The existing @compile tag accepts a new option, /module=<module>. This has the effect of invoking javac with the --module <module> option, defined above, to compile the specified classes as members of the indicated module.

Class loaders

The Java SE Platform API historically specified two class loaders: The bootstrap class loader, which loads classes from the bootstrap class path, and the system class loader, which is the default delegation parent for new class loaders and, typically, the class loader used to load and start the application. The specification does not mandate the concrete types of either of these class loaders, nor their precise delegation relationship.

The JDK has, since the 1.2 release, implemented a three-level hierarchy of class loaders, where each loader delegates to the next:

JDK 9 retains this three-level hierarchy, in order to preserve compatibility, while making the following changes to implement the module system:

The platform class loader is retained not only for compatibility but, also, to improve security. Types loaded by the bootstrap class loader are implicitly granted all security permissions (AllPermission), but many of these types do not actually require all permissions. We have de-privileged modules that do not require all permissions by defining them to the platform loader rather than the bootstrap class loader, and by granting them the permissions they actually need in the default security policy file. The Java SE and JDK modules defined to the platform class loader are:

java.activation*            jdk.accessibility
java.compiler*              jdk.charsets
java.corba*                 jdk.crypto.cryptoki
java.scripting              jdk.crypto.ec
java.se                     jdk.dynalink
java.se.ee                  jdk.incubator.httpclient
java.security.jgss          jdk.internal.vm.compiler*
java.smartcardio            jdk.jsobject
java.sql                    jdk.localedata
java.sql.rowset             jdk.naming.dns
java.transaction*           jdk.scripting.nashorn
java.xml.bind*              jdk.security.auth
java.xml.crypto             jdk.security.jgss
java.xml.ws*                jdk.xml.dom
java.xml.ws.annotation*     jdk.zipfs

(An asterisk, '*', in these lists indicates an upgradeable module.)

JDK modules that provide tools or export tool APIs are defined to the application class loader:

jdk.aot                     jdk.jdeps
jdk.attach                  jdk.jdi
jdk.compiler                jdk.jdwp.agent
jdk.editpad                 jdk.jlink
jdk.hotspot.agent           jdk.jshell
jdk.internal.ed             jdk.jstatd
jdk.internal.jvmstat        jdk.pack
jdk.internal.le             jdk.policytool
jdk.internal.opt            jdk.rmic
jdk.jartool                 jdk.scripting.nashorn.shell
jdk.javadoc                 jdk.xml.bind*
jdk.jcmd                    jdk.xml.ws*
jdk.jconsole

All other Java SE and JDK modules are defined to the bootstrap class loader:

java.base                   java.security.sasl
java.datatransfer           java.xml
java.desktop                jdk.httpserver
java.instrument             jdk.internal.vm.ci
java.logging                jdk.management
java.management             jdk.management.agent
java.management.rmi         jdk.naming.rmi
java.naming                 jdk.net
java.prefs                  jdk.sctp
java.rmi                    jdk.unsupported

The three built-in class loaders work together to load classes as follows:

The application and platform class loaders delegate to their respective parent loaders in order to ensure that the bootstrap class path is still searched when a class is not found in a module defined to one of the built-in loaders.

Removed: Bootstrap class-path options

In earlier releases the -Xbootclasspath option allows the default bootstrap class path to be overridden, and the -Xbootclasspath/p option allows a sequence of files and directories to be prepended to the default path. The computed value of this path is reported via the JDK-specific system property sun.boot.class.path.

With the module system in place the bootstrap class path is empty by default, since bootstrap classes are loaded from their respective modules. The javac compiler only supports the -Xbootclasspath option in legacy mode, the java launcher no longer supports either of these options, and the system property sun.boot.class.path has been removed.

The compiler's --system option can be used to specify an alternate source of system modules, as described above, and its -release option can be used to specify an alternate platform version, as described in JEP 247 (Compile for Older Platform Versions). At run time the --patch-module option, mentioned above, can be used to inject content into modules in the initial module graph.

A related option, -Xbootclasspath/a, allows files and directories to be appended to the default bootstrap class path. This option, and the related API in the java.lang.instrument package, is sometimes used by instrumentation agents, so for compatibility it is still supported at run time. Its value, if specified, is reported via the JDK-specific system property jdk.boot.class.path.append. This option can be passed to the command-line launcher, java, and also to the JNI invocation API.

Testing

Many existing tests were affected by the introduction of the module system. In JDK 9 the @modules tag, described above, was added to the unit and regression tests as needed, and tests that used the -Xbootclasspath/p option or assumed that the system class loader is a URLClassLoader were updated.

There is, of course, an extensive set of unit tests for the module system itself. In the JDK 9 source forest the run-time tests are in the test/jdk/modules directory of the jdk repository and the runtime/modules directory of the hotspot repository; the compile-time tests are in the tools/javac/modules directory of the langtools repository.

Early-access builds containing the changes described here were available throughout the development of the module system. Members of the Java community were strongly encouraged to test their tools, libraries, and applications against these builds to help identify compatibility issues.

Risks and Assumptions

The primary risks of this proposal are ones of compatibility due to changes to existing language constructs, APIs, and tools.

Changes due primarily to the introduction of the Java Platform Module System (JSR 376) include:

Modules that define Java EE APIs, or APIs primarily of interest to Java EE applications, have been deprecated and will be removed in a future release. They are not resolved by default for code on the class path:

The run-time behavior of some Java SE APIs has changed, though in ways that continue to honor their existing specifications:

There are several source-incompatible Java SE API changes:

Finally, changes due to revisions to JDK-specific APIs and tools include:

Dependences

JEP 200 (The Modular JDK) originally defined the modules present in the JDK in an XML document, as an interim measure. This JEP moved those definitions to proper module descriptors, i.e., module-info.java and module-info.class files, and the modules.xml file in the root source-code repository was removed.

The initial implementation of JEP 220 (Modular Run-Time Images) in JDK 9 used a custom build-time tool to construct JRE and JDK images. This JEP replaced that tool with the jlink tool.

Modular JAR files can also be Multi-Release JAR files, per JEP 238.