JEP 261: Module SystemJEP 261: Module SystemAuthorsAlan Bateman, Alex Buckley, Jonathan Gibbons, Mark ReinholdOwnerMark ReinholdTypeFeatureScopeSEStatusClosed / DeliveredRelease9JSR376Discussionjigsaw dash dev at openjdk dot java dot netEffortXLDurationLBlocksJEP 200: The Modular JDKJEP 282: jlink: The Java LinkerDependsJEP 220: Modular Run-Time ImagesJEP 260: Encapsulate Most Internal APIsRelates toJEP 396: Strongly Encapsulate JDK Internals by DefaultJEP 403: Strongly Encapsulate JDK InternalsReviewed byAlan Bateman, Alex Buckley, Chris Hegarty, Jonathan Gibbons, Mandy Chung, Paul SandozEndorsed byBrian GoetzCreated2014/10/23 15:05Updated2024/04/28 18:11Issue8061972Summary
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:

200: The Modular JDK
201: Modular Source Code
220: Modular Run-Time Images
260: Encapsulate Most Internal APIs
282: jlink: The Java Linker

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


A module artifact, i.e., a modular JAR file or a JMOD file
containing a compiled module definition, or else


An exploded-module directory whose name is, by convention, the
module's name and whose content is an "exploded" directory tree
corresponding to a package hierarchy.


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 compilation module path (specified by the command-line option
--module-source-path) contains module definitions in source form
(compile time only).


The upgrade module path (--upgrade-module-path) contains compiled
definitions of modules intended to be used in preference to the
compiled definitions of any upgradeable modules present amongst the
system modules or on the application module path (compile time and
run time).


The system modules are the compiled modules built-in to the
environment (compile time and run time).  These typically include
Java SE and JDK modules but, in the case of a custom linked
image, can also include library and application modules.  At compile
time the system modules can be overridden via the --system option,
which specifies a JDK image from which to load system modules.


The application module path (--module-path, or -p for short)
contains compiled definitions of library and application modules (all
phases).  At link time this path can also contain Java SE and JDK
modules.


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:


The java.se module is a root, if it exists.  If it does not exist
then every java.* module on the upgrade module path or among the
system modules that exports at least one package, without
qualification, is a root.


Every non-java.* module on the upgrade module path or among the
system modules that exports at least one package, without
qualification, is also a root.


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


At compile time it is usually the set of modules being compiled (more
on this below);


At link time it is empty; and


At run time it is the application's main module, as specified via the
--module (or -m for short) launcher option.


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.

Legacy mode is enabled when the compilation environment, as defined
by the -source, -target, and --release options, is less than or
equal to 8.  None of the modular options described above may be used.

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

Single-module mode is enabled when the compilation environment is 9
or later and the --module-source-path option is not used.  The
other modular options described above may be used; the existing
options -bootclasspath, -Xbootclasspath, -extdirs,
-endorseddirs, and -XXuserPathsFirst may not be used.

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 enabled when the compilation environment is 9
or later and the --module-source-path option is used.  The existing
-d option to name the output directory must also be used; the other
modular options described above may be used; the existing options
-bootclasspath, -Xbootclasspath, -extdirs, -endorseddirs, and
-XXuserPathsFirst may not be used.

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:


--main-class=<class-name>, or -e <class-name> for short, causes
<class-name> to be recorded in the module-info.class file as the
class containing the module's public static void main entry point.
(This is not a new option; it already records the main class in the
JAR file's manifest.)


--module-version=<version> causes <version> to be recorded in the
module-info.class file as the module's version string.


--hash-modules=<pattern> causes hashes of the content of the
specific modules that depend upon this module, in a particular set of
observable modules, to be recorded in the module-info.class file
for later use in the validation of dependencies.  Hashes are only
recorded for modules whose names match the regular expression
<pattern>.  If this option is used then the ---module-path
option, or -p for short, must also be used to specify the set of
observable modules for the purpose of computing the modules that
depend upon this module.


--describe-module, or -d for short, displays the module
descriptor, if any, of the specified JAR file.


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:

Add-Exports: <module>/<package>( <module>/<package>)*
Add-Opens: <module>/<package>( <module>/<package>)*

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:


--class-path <path> specifies a class path whose content will be
copied into the resulting JMOD file.


--cmds <path> specifies one or more directories containing native
commands to be copied.


--config <path> specifies one or more directories containing
configuration files to be copied.


--exclude <pattern-list> specifies files to be excluded, where
<pattern-list> is a comma-separated list of patterns of the form
<glob-pattern>, glob:<glob-pattern>, or regex:<regex-pattern>.


--header-files <path> specifies one or more directories containing
C and C++ header files to be copied.


--legal-notices <path> specifies one or more directories containing
legal notices to be copied.


--libs <path> specifies one or more directories containing native
libraries to be copied.


--man-pages <path> specifies one or more directories containing
manual pages to be copied.


--target-platform <os>-<arch> specifies the target operating system
and architecture, to be recorded in the ModuleTarget attribute of
the module-info.class file.


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.
Link time
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:

--module <module>, or -m <module> for short, specifies the main
module of a modular application.  This will be the default root
module for the purpose of constructing the application's initial
module graph.  If the main module's descriptor does not indicate a
main class then the syntax <module>/<class> can be used, where
<class> names the class that contains the application's public static void main entry point.

Additional diagnostic options supported by the launcher include:


--list-modules displays the names and version strings of the
observable modules and then exits, in the same manner as java --version.


--describe-module <module>, or -d <module> for short, displays
the module descriptor of the specified module, in the same format as
the jar -d option and the jmod describe subcommand, and then
exits.


--validate-modules validates all the observable modules, checking
for conflicts and other potential errors, and then exits.


--dry-run initializes the virtual machine and loads the main class
but does not invoke the main method; this is useful for validating
the configuration of the module system.


--show-module-resolution causes the module system to describe its
activities as it constructs the initial module graph.


-Dsun.reflect.debugModuleAccessChecks causes a thread dump to be
shown whenever an access check in the java.lang.reflect API fails
with an IllegalAccessException or an InaccessibleObjectException.
This is useful for debugging when the underlying reason for a failure
is hidden because the exception is caught and not re-thrown.


-Xlog:module+[load|unload][=[debug|trace]] causes the VM to log
debug or trace messages as modules are defined and changed in the
run-time module graph.  These options generate voluminous output
during startup.


-verbose:module is a shorthand for -Xlog:module+load -Xlog:module+unload.


-Xlog:init=debug causes a stack trace to be displayed if the
initialization of the module system fails.


--version, --show-version, --help, and --help-extra display
the same information and work in the same way as the existing
-version, -show-version, -help, and -Xhelp options,
respectively, except that they write the help text to the standard
output stream rather than the standard error stream.


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:


--illegal-access=permit opens each package in each module in the
run-time image to code in all unnamed modules, i.e., to code on the
class path, if that package existed in JDK 8.  This enables both
static access, i.e., by compiled bytecode, and deep reflective
access, via the platform's various reflection APIs.
The first reflective-access operation to any such package causes a
warning to be issued, but no warnings are issued after that point.
This single warning describes how to enable further warnings.  This
warning cannot be suppressed.
This mode is the default in JDK 9.  It will be phased out in a future
release and, eventually, removed.


--illegal-access=warn is identical to permit except that a
warning message is issued for each illegal reflective-access
operation.


--illegal-access=debug is identical to warn except both a warning
message and a stack trace are issued for each illegal
reflective-access operation.


--illegal-access=deny disables all illegal-access operations except
for those enabled by other command-line options, e.g., --add-opens.
This mode will become the default in a future release.


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 the component's maintainers have already released a new, fixed
version that no longer uses JDK-internal APIs then you can consider
upgrading to that version.


If the component still needs to be fixed then we encourage you to
contact its maintainers and ask them to replace their use of
JDK-internal APIs with proper exported APIs, if available.


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:


$PERPETRATOR is the fully-qualified name of the type containing
the code that invoked the reflective operation in question plus
the code source (i.e., JAR-file path), if available, and


$VICTIM is a string that describes the member being accessed,
including the fully-qualified name of the enclosing type


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


<module>, where <module> is a module name, to indicate that the
specified module must be present;


<module>/<package>, to indicate that the specified module must be
present and the specified package must be exported to the test's
module; or


<module>/<package>:<flag>, to indicate that the specified module
must be present and, if the flag is open then the specified package
must be opened to the test's module, or else if the flag is +open
then the specified package must be both exported and opened to the
test's module.


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:


The application class loader, an instance of
java.net.URLClassLoader, loads classes from the class path and is
installed as the system class loader unless an alternate system
loader is specified via the system property
java.system.class.loader.


The extension class loader, also an instance of URLClassLoader,
loads classes available via the extension mechanism and, also,
some resources and service providers built-in to the JDK.  (This
loader is not mentioned explicitly in the Java SE Platform API
Specification.)


The bootstrap class loader, which is implemented solely within the
virtual machine and is represented by null in the ClassLoader
API, loads classes from the bootstrap class path.


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


The application class loader is no longer an instance of
URLClassLoader but, rather, of an internal class.  It is the
default loader for named modules that are neither Java SE nor JDK
modules.


The extension class loader is no longer an instance of
URLClassLoader but, rather, of an internal class.  It no longer
loads classes via the extension mechanism, which was removed by
JEP 220.  It does, however, define selected Java SE and JDK
modules, about which more below.  In its new role this loader is
known as the platform class loader, it is available via the new
ClassLoader::getPlatformClassLoader
method, and it will be required by the
Java SE Platform API Specification.


The bootstrap class loader is implemented in both library code and
within the virtual machine, but for compatibility it is still
represented by null in the ClassLoader API.  It defines the core
Java SE and JDK modules.


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 class loader first searches the named modules defined
to all of the built-in loaders.  If a suitable module is defined to
one of these loaders then that loader will load the class.  If a
class is not found in a named module defined to one of these loaders
then the application class loader delegates to its parent.  If a
class is not found by its parent then the application class loader
searches the class path.  Classes found on the class path are loaded
as members of this loader's unnamed module.


The platform class loader searches the named modules defined to all
of the built-in loaders.  If a suitable module is defined to one of
these loaders then that loader will load the class.  (The platform
class loader can, consequently, now delegate to the application class
loader, which can be useful when a module on the upgrade module path
depends upon a module on the application module path.)  If a class is
not found in a named module defined to one of these loaders then the
platform class loader delegates to its parent.


The bootstrap class loader searches the named modules defined to
itself.  If a class is not found in a named module defined to the
bootstrap loader then the bootstrap class loader searches the files
and directories added to the bootstrap class path via the
-Xbootclasspath/a option.  Classes found on the bootstrap class
path are loaded as members of this loader's unnamed module.


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:


Applying the public modifier to an API element no longer guarantees
that the element will be everywhere accessible.  Accessibility now
depends also upon whether the package containing that element is
exported or opened by its defining module, and whether that module is
readable by the module containing the code that is attempting to
access it.  For example, code of the following form might not work
correctly:
Class<?> c = Class.forName(...);
if (Modifier.isPublic(c.getModifiers()) {
    // Assume that c is accessible
}


If a package is defined in both a named module and on the class path
then the package on the class path will be ignored.  The class path
can, therefore, no longer be used to augment packages that are built
into the environment.  The javax.transaction package, e.g., is
defined by the java.transaction module, so the class path will not
be searched for types in that package.  This restriction is important
to avoid splitting packages across class loaders and across modules.
At compile time and run time the upgrade module path can be used to
upgrade modules that are built-in into the environment.  The
--patch-module option can be used for other ad-hoc patching.


The ClassLoader::getResource* methods can no longer be used to
locate JDK-internal resources other than class files.  Module-private
non-class resources can be read via the Class::getResource*
methods, the Module::getResourceAsStream method or via the jrt:
URL scheme and filesystem defined in JEP 220.


The java.lang.reflect.AccessibleObject::setAccessible
method cannot be used to gain access to public
members of packages that are not exported or opened by their defining
modules, or to non-public members of packages that are not opened by
their defining modules; in either case, an
InaccessibleObjectException will be thrown.  If a framework
library, such as a serializer, needs access to such members at run
time then the relevant packages must be opened to the framework
module by declaring the containing module to be open, by declaring
that package to be open, or by opening that package via the
--add-opens command-line option.


JVM TI agents can no longer instrument Java code that runs early in
the startup of the run-time environment.  The ClassFileLoadHook
event, in particular, is no longer sent during the primordial phase.
The VMStart event, which signals the beginning of the start phase,
is only posted after the the VM is initialized to the point where it
can load classes in modules other than java.base.  Two new
capabilities, can_generate_early_class_hook_events and
can_generate_early_vmstart, can be added by agents that are
carefully written to handle events early in VM initialization.  More
details can be found in the updated description of the class file load hook event
and the start event.


The == syntax in security policy files has been revised to augment
the permissions granted to standard and JDK modules rather than
override them.  Applications that override other aspects of the JDK's
default policy file therefore do not need to copy the default
permissions granted to the standard and JDK modules.


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 default set of root modules for the unnamed module is based upon
the java.se module rather than the java.se.ee module.  Thus, by
default, code in the unnamed module will not have access to APIs in
the following modules:
java.activation
java.corba
java.transaction
java.xml.bind
java.xml.ws
java.xml.ws.annotation
This is an intentional, if painful, choice, driven by two goals:


To avoid unnecessary conflicts with popular libraries that define
types in some of the same packages.  The widely-used
jsr305.jar, e.g., defines annotation types in the
javax.annotation package, which is also defined by the
java.xml.ws.annotation module.


To make it easier for existing application servers to migrate to
JDK 9.  Application servers often override the content of
one or more of these modules, and in the near term they are most
likely to do so by continuing to place the necessary non-modular
JAR files on the class path.  If these modules were resolved by
default then the maintainers of application servers would have to
take awkward actions to exclude them in order to override them.


These modules are still part of JDK 9.  Code on the class path
can be granted access to one or more of these modules, as needed, via
the --add-modules option.


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


The application and platform class loaders are no longer instances of
the java.net.URLClassLoader class, as noted above.  Existing code
that invokes ClassLoader::getSystemClassLoader and blindly casts
the result to URLClassLoader, or does the same thing with the
parent of that class loader, might not work correctly.


Some Java SE types have been de-privileged and are now loaded by the
platform class loader rather than the bootstrap class loader, as
noted above.  Existing custom class loaders that delegate directly to
the bootstrap class loader might not work correctly; they should be
updated to delegate to the platform class loader, which is easily
available via the new ClassLoader::getPlatformClassLoader
method.


Instances of java.lang.Package created by the built-in class
loaders for packages in named modules do not have specification or
implementation versions.  In previous releases this information was
read from the manifest of rt.jar.  Existing code that expects the
Package::getSpecification* or Package::getImplementation* methods
always to return non-null values might not work correctly.


There are several source-incompatible Java SE API changes:


The java.lang package includes two new top-level classes, Module
and ModuleLayer.  The java.lang package is implicitly imported on
demand (i.e., import java.lang.*).  If code in an existing source
file imports some other package on demand, and that package declares
a Module or ModuleLayer type, and the existing code refers to
that type, then the file will not compile without change.


The java.lang.instrument.Instrumentation interface declares two new
abstract methods, redefineModule and isModifiableModule.  This
interface is not intended to be implemented outside of the
java.instrument module.  If there are external implementations then
they will not compile on JDK 9 without change.


The five-parameter transform method declared in the
java.lang.instrument.ClassFileTransformer interface is now a
default method.  The interface now also declares a new transform
method that makes the relevant java.lang.reflect.Module object
available to the transformer when instrumenting classes at load time.
Existing compiled code will continue to run, but existing source code
that uses the existing five-parameter transform method as a
functional interface will no longer compile.


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


Most of the JDK's internal APIs are inaccessible by default at
compile time, as described in JEP 260.  Existing code that
compiled against these APIs with warnings in previous releases will
no longer compile.  A workaround is to break encapsulation via the
--add-exports option, defined above.


Selected critical internal APIs in the sun.misc and sun.reflect
packages have been moved to the jdk.unsupported module, as
described in JEP 260.  Non-critical internal APIs in these
packages, such as sun.misc.BASE64{De,En}coder, have been either
moved or removed.


If a security manager is present then the run-time permission
accessSystemModules is required in order to access JDK-internal
resources via the ClassLoader::getResource* or
Class::getResource* methods; in previous releases, permission to
read the file ${java.home}/lib/rt.jar was required.


The -Xbootclasspath and -Xbootclasspath/p options have been
removed, as noted above.  At compile time, the new --release option
can be used to specify an alternate platform version (see
JEP 247).  At run time, the new --patch-module option,
described above, can be used to inject content into system modules.


The JDK-specific system property sun.boot.class.path has been
removed, since the bootstrap class path is empty by default.
Existing code that uses this property might not work correctly.


The JDK-specific annotation @jdk.Exported, introduced by
JEP 179, has been removed since the information it conveys
is now recorded in the exports declarations of module descriptors.
We have seen no evidence of this annotation being used by tools
outside of the JDK.


The META-INF/services resource files previously found in rt.jar
and other internal artifacts are not present in the corresponding
system modules, since service providers and dependences are now
declared in module descriptors.  Existing code that scans for such
files might not work correctly.


The JDK-specific system property file.encoding can be set on the
command line via the -D option, as before, but it must specify a
charset defined in the base module.  If any other charset is
specified then the run-time system will fail to start.  Existing
launch scripts that specify such charsets might not work correctly.


The com.sun.tools.attach API can no longer be used, by default, to
attach an agent to the current process or an ancestor of the current
process.  Such attachment operations can be enabled by setting the
system property jdk.attach.allowAttachSelf on the command line.


The dynamic loading of JVM TI agents will be disabled by default in a
future release.  To prepare for that change we recommend that
applications that allow dynamic agents start using the option
-XX:+EnableDynamicAgentLoading to enable that loading explicitly.
The option -XX:-EnableDynamicAgentLoading disables dynamic agent
loading.


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.
InstallingContributingSponsoringDevelopers' GuideVulnerabilitiesJDK GA/EA BuildsMailing listsWiki
                      · IRCBylaws · CensusLegalWorkshopJEP ProcessSource codeMercurialGitHubToolsGitjtreg harnessGroups(overview)AdoptionBuildClient LibrariesCompatibility & Specification ReviewCompilerConformanceCore LibrariesGoverning BoardHotSpotIDE Tooling & SupportInternationalizationJMXMembersNetworkingPortersQualitySecurityServiceabilityVulnerabilityWebProjects(overview,
      archive)AmberBabylonCRaCCaciocavalloClosuresCode ToolsCoinCommon VM InterfaceCompiler GrammarDetroitDevelopers' GuideDevice I/ODukeGalahadGraalIcedTeaJDK 7JDK 8JDK 8 UpdatesJDK 9JDK
      (…,
       21,
       22,
       23)JDK UpdatesJavaDoc.NextJigsawKonaKullaLambdaLanaiLeydenLilliputLocale EnhancementLoomMemory Model UpdateMetropolisMission ControlMulti-Language VMNashornNew I/OOpenJFXPanamaPenrosePort: AArch32Port: AArch64Port: BSDPort: HaikuPort: Mac OS XPort: MIPSPort: MobilePort: PowerPC/AIXPort: RISC-VPort: s390xPortolaSCTPShenandoahSkaraSumatraTiered AttributionTsanType AnnotationsValhallaVeronaVisualVMWakefieldZeroZGC

        © 2024 Oracle Corporation and/or its affiliates
        Terms of Use
        ·
        
            License: GPLv2
        · Privacy
        · Trademarks
