Summary

Initial integration of the Java Platform Module System into the JDK.

Problem

This CCC tracks the initial integration of the Java Platform Module System being defined by JSR 376, and implemented by JEP 261, into JDK 9.

The proposal addresses two fundamental needs of large Java applications, namely reliable configuration and strong encapsulation.

The initial integration takes in the following JEPs:

• JEP 200: The Modular
• JDK JEP 260: Encapsulate Most Internal APIs
• JEP 261: Module System
• JEP 282: jlink: The Java Linker

Snapshots of the JEPs are attached (as per CCC policy).

Solution

The module system that is being defined by JSR 376, implemented in JEP 261, in conjunction with JEP 200, JEP 260 and JEP 282.

JEP 200 describes the modular JDK and the design principles that guide its structure. The standard modules, the graph of modules with module names starting with "java.", will be defined by the JSR for Java SE 9.

In the case of JEP 260 then non-critical internal APIs will be encapsulated. The proposed jdk.unsupported will not be in place for the initial integration but will follow soon afterwards.

In the case of JEP 282 then the linker tool, as described in the JEP, will be integrated along with 11 plug-ins. Many of these plug-ins are not intended to be documented or are currently experimental. The options that these add to the jlink command-line interface are not described in this CCC.

Specification

The specification changes in this CCC is a snapshot for the initial integration into JDK 9. JSR 376 is expected to submit an EDR soon and that EDR will be inline with the changes to Java SE proposed in this CCC.

JLS/JVMS Attached is a snapshot of "Modules in the Java Language and JVM" that will eventually evolve and move into the JLS and JVMS.

API docs: Attached as specdiffs.

JNI specification: Three JNI functions are proposed, attached as specdiffs.

JVM TI specification: One new function and changes the ClassFileLoadHook and VMStart events are proposed. Attached as specdiffs.

JDWP specification: Attached as specdiffs.

JDI specification (JDK-specific) Attached as specdiffs.

JMOD format: A new packaging format for modules is proposed by JEP 261. The format is JDK-specific and not documented. It is only supported at packaging (jmod tool) and link time.

Bootstrap class-path:

• Remove: java -Xbootclasspath and -Xbootclasspath/p command-line options
• javac: will only support the -Xbootclasspath command-line option when targeting a release < 9.

The corresponding system property sun.boot.class.path has been removed.

JEP 261 (and JEP 282 in the case of jlink) documents many of the new command-line options. For completeness, we list all new/changed command line options here:

javac:

  -modulesourcepath <module-source-path>
Specify where to find input source files for multiple modules

  -modulepath <path>
  -mp <path>
Specify where to find application modules

  -upgrademodulepath <path>
Override location of upgradeable modules

  -system <jdk>|none
Override location of system modules

  -m <module-name>
Compile only the specified module, check timestamps

  -addmods <module>(,<module>)*
Root modules to resolve in addition to the initial modules, or all modules
on the module path if <module> is ALL-MODULE-PATH.

  -limitmods <module>(,<module>)*
Limit the universe of observable modules

  -Xpatch:<path>
Specify location of module class files to patch

  -XaddExports:<module>/<package>=<other-module>(,<other-module>)*
Specify a package to be considered as exported from its defining module
to additional modules, or to all unnamed modules if <other-module> is ALL-UNNAMED.

  -XaddReads:<module>=<other-module>(,<other-module>)*
Specify additional modules to be considered as required by a given module.
<other-module> may be ALL-UNNAMED to require the unnamed module.

  -Xmodule:<module-name>
Specify a module to which the classes being compiled belong.



java:

    -mp <module path>
    -modulepath <module path>...
                  A : separated list of directories, each directory
                  is a directory of modules.
    -upgrademodulepath <module path>...
                  A : separated list of directories, each directory
                  is a directory of modules that replace upgradeable
                  modules in the runtime image
    -m <modulename> | <modulename>/<mainclass>
                  the initial or main module to resolve
    -addmods <modulename>[,<modulename>...]
                  root modules to resolve in addition to the initial module
    -limitmods <modulename>[,<modulename>...]
                  limit the universe of observable modules
    -listmods[:<modulename>[,<modulename>...]]
                  list the observable modules and exit

    -XaddReads:<module>=<other-module>(,<other-module>)*
                      <module> reads other modules,
                      regardless of module declaration
    -XaddExports:<module>/<package>=<other-module>(,<other-module>)*
                      <module> exports <package> to other modules,
                      regardless of module declaration
    -Xpatch:<module>=<file>(:<file>)*
                      Override or augment a module with classes and resources
                      in JAR files or directories



javap:


  -m <module-name>         Specify module containing classes to be disassembled
  -upgrademodulepath <path>    Specify where to find upgradeable modules
  -system <jdk>            Specify where to find system modules
  -modulepath <path>       Specify where to find application modules




jdeps:

  -genmoduleinfo <dir>
Generate module-info.java under the specified directory.
The specified JAR files will be analyzed.
This option cannot be used with -dotoutput or -cp.

  -ct          -compile-time           
Compile-time view of transitive dependencies
i.e. compile-time view of -R option.  If a dependence
is found from a directory, a JAR file or a module,
all class files in that containing archive are analyzed.

  -mp <module path>...
  -modulepath <module path>...         
Specify module path

  -upgrademodulepath <module path>...  
Specify upgrade module path

  -m <module-name>
Specify the name of the module and its transitive
dependences to be analyzed.



jar:

In addition to new options, GNU style options have been added for the existing options.

  -c, --create               Create the archive
  -i, --generate-index=FILE  Generate index information for the specified jar
                             archives
  -t, --list                 List the table of contents for the archive
  -u, --update               Update an existing jar archive
  -x, --extract              Extract named (or all) files from the archive
  -p, --print-module-descriptor  Print the module descriptor

  -f, --file=FILE            The archive file name
  -v, --verbose              Generate verbose output on standard output

  -e, --main-class=CLASSNAME The application entry point for stand-alone
                             applications bundled into a modular, or executable,
                             jar archive
  -m, --manifest=FILE        Include the manifest information from the given
                             manifest file
  -M, --no-manifest          Do not create a manifest file for the entries
      --module-version=VERSION    The module version, when creating a modular
                             jar, or updating a non-modular jar
      --hash-dependencies=PATTERN  Compute and record the hashes of module
                             dependencies matched by the given pattern, when
                             creating a modular jar, or updating a non-modular
                             jar
      --modulepath           Location of module dependence for generating

  -0, --no-compress          Store only; use no ZIP compression



jmod (new tool):

Usage: jmod (create|list|describe) <OPTIONS> <jmod-file>

 Main operation modes:
  create    - Creates a new jmod archive
  list      - Prints the names of all the entries
  describe  - Prints the module details

 Option                             Description
 ------                             -----------
  --class-path <path>                Application jar files|dir containing
                                       classes
  --cmds <path>                      Location of native commands
  --config <path>                    Location of user-editable config files
  --exclude <pattern>                Exclude files, given as a PATTERN
  --hash-dependencies <pattern>      Compute and record hashes of
                                       dependencies matched by the pattern
  --help                             Print this usage message
  --libs <path>                      Location of native libraries
  --main-class <class-name>          Main class
  --module-version <module-version>  Module version
  --modulepath, --mp <path>          Module path
  --os-arch <os-arch>                Operating system architecture
  --os-name <os-name>                Operating system name
  --os-version <os-version>          Operating system version
  --version                          Version information
  @<filename>                        Read options from the specified file                        Read options from the specified file




jlink (JEP 282):

Usage: jlink <options> --modulepath <modulepath> --addmods <mods> --output <path>
Possible options include:
  --help                            Print this help message
  --modulepath <modulepath>         Module path
  --limitmods <mod>[,<mod>...]      Limit the universe of observable modules
  --addmods <mod>[,<mod>...]        Root modules to resolve
  --output <path>                   Location of output path
  --version                         Version information
  -G, --strip-debug                 Strip debug information
  -c, --compress=2                  Enable compression of resources (level 2)
  --plugin-module-path <modulepath> Custom plugins module path
  --list-plugins                    List available plugins
  @<filename>                       Read options from file

Finally, we propose jdk.rmi.rmic.Main, defining one method:

   public static void main(String... args)

as a JDK specific/supported API. The package jdk.rmi.rmic will be exported by the jdk.rmic module.

The arguments specified to this method are many of the options that the rmic allows. rmic -help has full list.