Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8194812 Extend class-data sharing to support the module path
  3. JDK-8198565

Release Note: Extend Class Data Sharing (CDS) to Support the Module Path

    Details

    • Type: Sub-task
    • Status: Closed
    • Priority: P3
    • Resolution: Delivered
    • Affects Version/s: 11
    • Fix Version/s: 11
    • Component/s: hotspot
    • Subcomponent:
    • Verification:
      Verified

      Description

      In JDK 11, Class Data Sharing (CDS) has been improved to support archiving classes from the module path.

      To create a CDS archive using the `--module-path` VM option, the command line syntax is as follows:

          $ java -Xshare:dump -XX:SharedClassListFile=<class list file> \
              -XX:SharedArchiveFile=<shared archive file> \
              --module-path=<path to modular jar> -m <module name>

      To run with a CDS archive using the `--module-path` VM option, the command line syntax is as follows:

          $ java -Xshare:on -XX:SharedArchiveFile=<shared archive file> \
              --module-path=<path to modular jar> -m <module name>

      The following table describes how the VM options related to module paths may be used along with the `-Xshare` option.

      <table>
        <thead>
          <tr>
            <th/>
            <th style="text-align: left; padding-left: 2em">-Xshare:dump</th>
            <th style="text-align: left; padding-left: 2em">-Xshare:{on,auto}</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>--module-path</code><sup>1</sup> &lt;mp&gt;</td>
            <td style="padding-left: 2em">Allowed</td>
            <td style="padding-left: 2em">Allowed<sup>2</sup></td>
          </tr>
          <tr>
            <td><code>--module</code></td>
            <td style="padding-left: 2em">Allowed</td>
            <td style="padding-left: 2em">Allowed</td>
          </tr>
          <tr>
            <td><code>--add-module</code></td>
            <td style="padding-left: 2em">Allowed</td>
            <td style="padding-left: 2em">Allowed</td>
          </tr>
          <tr>
            <td><code>--upgrade-module-path</code><sup>3</sup></td>
            <td style="padding-left: 2em">Disallowed (exits if specified)</td>
            <td style="padding-left: 2em">Allowed (disables CDS)</td>
          </tr>
          <tr>
            <td><code>--patch-module</code><sup>4</sup></td>
            <td style="padding-left: 2em">Disallowed (exits if specified)</td>
            <td style="padding-left: 2em">Allowed (disables CDS)</td>
          </tr>
          <tr>
            <td><code>--limit-modules</code><sup>5</sup></td>
            <td style="padding-left: 2em">Disallowed (exits if specified)</td>
            <td style="padding-left: 2em">Allowed (disables CDS)</td>
          </tr>
        </tbody>
      </table>

      <sup>1</sup>Although there are two ways of specifying a module in a `--module-path`, that is, modular `.jar` or exploded module, only modular `.jar` files are supported.

      <sup>2</sup>Different &lt;mp&gt; may be specified during dump time vs run time. If an archived class `K` was loaded from `mp1.jar` at dump time, but changes in &lt;mp&gt; cause it to be available from a different `mp2.jar` at run time, then the archived version of `K` will be disregarded at run time; `K` will be loaded dynamically.

      <sup>3</sup>Currently, only two system modules are upgradeable (`java.compiler` and `jdk.internal.vm.compiler`). These are seldom upgraded in production software.

      <sup>4</sup>As documented in [JEP 261](http://openjdk.java.net/jeps/261), `--patch-module` is strongly discouraged for production use.

      <sup>5</sup>`--limit-modules` is intended for testing purposes. It is seldom used in production software.

      If any one of `--upgrade-module-path`, `--patch-module`, or `--limit-modules` is specified at dump time, the following error will be printed and the JVM will exit. For example, if the `--limit-modules` option is specified at dump time, the user will see the following error:

          Error occurred during initialization of VM
          Cannot use the following option when dumping the shared archive: --limit-modules

      If any one of `--upgrade-module-path`, `--patch-module`, or `--limit-modules` is specified at run time, the following warning message will be printed indicating that CDS is disabled. For example, if the `--limit-modules` option is specified at run time, the user will see the following warning:

          Java HotSpot(TM) 64-Bit Server VM warning: CDS is disabled when the --limit-modules option is specified.

      A few other noteworthy things to mention:

      1. Any valid combinations of `-cp` and `--module-path` are supported.

      2. A non-empty directory in the module path causes a fatal error. The user will see the following error messages:

          Error: non-empty directory &lt;directory>
          Hint: enable -Xlog:class+path=info to diagnose the failure
          Error occurred during initialization of VM
          Cannot have non-empty directory in paths

      3. Unlike the class path, there's no restriction that the module path at dump time must be equal to or be a prefix of the module path at run time.

      4. The archive is invalidated if an existing JAR in the module path is updated after archive generation.

      5. Removing a JAR from the module path does not invalidate the shared archive. Archived classes from the removed JAR are not used at runtime.

        Attachments

          Activity

            People

            • Assignee:
              ccheung Calvin Cheung
              Reporter:
              mlautman Mary Lautman
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: