JEP 261 update: -Xoverride becomes -Xpatch

Mon Sep 28 18:10:07 UTC 2015

2015/9/28 9:40 -0700, mark.reinhold at oracle.com:
> ...
> 
> Alan has already pushed changes to the Jake forest to implement (most of)
> the -XaddReads option, and the rename of -Xoverride to -Xpatch.  These
> will be available in the next Jigsaw EA build, likely later this week.
> I'll update JEP 261 shortly.

Done: http://openjdk.java.net/jeps/261

Patch attached below for reference.

- Mark

--- 261.md.orig	2015-09-25 14:29:28.386792119 -0700
+++ 261.md	2015-09-28 10:56:41.555335035 -0700
@@ -180,20 +180,66 @@
 `-limitmods` option is also specified, then the name of the main module
 is added to the set of modules named by the `-limitmods` option so that
 the main module is included in the module graph.
 
 (The transitive closure computed for the interpretation of the
  `-limitmods` 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, _e.g._, in order for a module under test to access
+the test harness itself, or to access libraries related to the harness.
+The `-XaddReads` option can be used, at both compile time and run time,
+to do this.  Its syntax is:
+
+    -XaddReads:<read>(,<read>)*
+
+where each `<read>` is of the form
+
+    <target-module>=<source-module>
+
+where `<target-module>` and `<source-module>` are module names.
+
+The effect of each `<read>` is to add a [readability edge][sotms-rd] from
+the target module to the source 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][api-addReads].  As a consequence, code in the target module will
+be able to access types in packages of the source module so long as each
+package is exported via an `exports` clause in the source module's
+declaration, an invocation of the `Module::addExports`
+[method][api-addExports], or a use of the `-XaddExports` option (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
+
+    -XaddReads:java.management=testng
+
+As a special case, if the `<source-module>` is `ALL-UNNAMED` then
+readability edges will be added from the target 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.
+
+[sotms-rd]: http://openjdk.java.net/projects/jigsaw/spec/sotms/#readability
+[api-addReads]: http://cr.openjdk.java.net/~mr/jigsaw/spec/api/java/lang/reflect/Module.html#addReads-java.lang.reflect.Module-
+
+
 ### 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
 `-XaddExports` option can be used, at both compile time and run time, to
 do this.  Its syntax is:
@@ -201,25 +247,28 @@
     -XaddExports:<export>(,<export>)*
 
 where each `<export>` is of the form
 
     <source-module>/<package>=<target-module>
 
 where `<source-module>` and `<target-module>` are module names and
 `<package>` is the name of a package.
 
 The effect of each `<export>` is to add a [qualified export][sotms-qe] of
-the named package from the source module to the target module.  Code in
-the target module will then be able to access 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 or an invocation of the
-`Module::addReads` method.
+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][api-addExports].  As a consequence, code in
+the target module will be able to access 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 a use of the `-XaddReads` 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
 
     -XaddExports: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
@@ -228,46 +277,60 @@
 to all code on the class path via the option
 
     -XaddExports:java.management/sun.management=ALL-UNNAMED
 
 > **The `-XaddExports` option must be used with great care.  You can use
     it 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
     changes or is removed then your library or application will fail.**
 
 [sotms-qe]: http://openjdk.java.net/projects/jigsaw/spec/sotms/#qualified-exports
+[api-addExports]: http://cr.openjdk.java.net/~mr/jigsaw/spec/api/java/lang/reflect/Module.html#addExports-java.lang.String-java.lang.reflect.Module-
 
 
-### Overriding module content
+### Patching module content
 
 When testing and debugging it is sometimes useful to replace selected
-class files of specific modules with alternate or experimental versions.
-This can be done via the `-Xoverride` option, at both compile time and
-run time.  Its syntax is:
-
-    -Xoverride:<dir>
-
-where `<dir>` is a directory that contains exploded-module directories
-whose content will override the content of any corresponding modules in
-the initial module graph.  This option replaces the `-Xbootclasspath:/p`
+class files or resources of specific module definitions with alternate or
+experimental versions, or to provide entirely new class files, resources,
+and even packages.  This can be done via the `-Xpatch` option, at both
+compile time and run time.  This option replaces the `-Xbootclasspath:/p`
 option, which has been removed (see below).
 
-> **The `-Xoverride` option is intended only for testing and debugging.
+The parameter to `-Xpatch` is a path of directories that contain module
+definitions, but it is not a module path.  When searching a module path
+for a module of a particular name, the module system only considers the
+first definition of a module of that name.  That can be inconvenient when
+testing and debugging, so the patch path is interpreted with "leaky",
+class-path-like semantics: When searching the patch path for a class in a
+module of a given name, the module system examines every definition of a
+module of that name, in order, until it finds the requested class.  This
+allows a test harness, _e.g._, to inject multiple tests into the same
+package without having to copy files.
+
+The `-Xpatch` option cannot be used to replace `module-info.class` files;
+any such files will be ignored.
+
+If a package found in a module on the patch path is not already exported
+by that module then it will not be exported.  It can be exported
+explicitly via either the reflection API or the `-XaddExports` option.
+
+> **The `-Xpatch` 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: `-modulesourcepath`, `-upgrademodulepath`,
 `-systemmodulepath`, `-modulepath`, `-addmods`, `-limitmods`,
-`-XaddExports`, and `-Xoverride`.
+`-XaddExports`, and `-Xpatch`.
 
 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.
@@ -424,21 +487,21 @@
 options, described above, as well as additional linker-specific options.
 
 The `jlink` tool's `--help` option can be used to get a complete summary
 of its command-line options.
 
 
 ### Run time
 
 The Java command-line launcher, `java`, implements the options described
 above, as applicable to run time: `-upgrademodulepath`, `-modulepath`,
-`-addmods`, `-limitmods`, `-XaddExports`, and `-Xoverride`.  The
+`-addmods`, `-limitmods`, `-XaddExports`, and `-Xpatch`.  The
 additional options specific to this phase are:
 
   - `-m <module>` 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.
 
   - `-listmods` shows the names and version strings of the modules
@@ -640,22 +703,22 @@
 
 With the module system in place there is no longer a bootstrap class path
 as such, so the `javac` compiler only supports the `-Xbootclasspath`
 option in legacy mode, the `java` launcher no longer supports either
 option, and the system property `sun.boot.class.path` will be removed.
 
 The compiler's `-systemmodulepath` 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)][jep247].
-At run time the `-Xoverride` option, mentioned above, can be used to
-override the content of modules in the initial module graph.
+At run time the `-Xpatch` 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 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`.
 
 [jep247]: http://openjdk.java.net/jeps/247
 
@@ -663,38 +726,20 @@
 ### Open design issues
 
   - For ease of use, if both the `-limitmods` and `-addmods` options are
     specified then it might be worth treating the `-addmods` arguments as
     additional `-limitmods` arguments, to avoid redundancies on the
     command line as well as potentially-confusing errors.
 
   - Should the `-addmods` option allow the intended class loader of the
     added modules to be specified?
 
-  - Should we reintroduce the `-XaddReads` option, which can add
-    arbitrary readability edges to the module graph from the command
-    line, in order to support white-box testing?
-
-  - Issues related to the `-Xoverride` option:
-
-      - Should it take a module path rather than a single directory?
-
-      - Can it be used to override non-class resources?  (The
-        implementation currently disallows this.)
-
-      - Can it be used to override `module-info.class` files?
-
-      - Can it be used to add packages to modules?  (If it can be used to
-        override `module-info.class` files then this is implied.)
-
-      - Is there a better name for this option?
-
   - In `javac`'s legacy mode, are `module-info.java` source files
     rejected, or are they ignored?
 
   - In `javac`'s multi-module mode the `-sourcepath` and `-classpath`
     options are confusing.  Should we disallow them?
 
   - The `-systemmodulepath` option implemented by `javac` should be
     renamed, perhaps simply to `-system`, since it does not specify an
     actual module path.
 
@@ -826,22 +871,22 @@
     these APIs might not work correctly.  A workaround is to break
     encapsulation via the `-XaddExports` option, defined above.  (The
     movement of the `sun.misc` and `sun.reflect` packages to a
     `jdk.internal` module, proposed in JEP 260, has not yet been
     implemented in the prototype; for now, the `java.base` module exports
     both of these packages.)
 
   - The `-Xbootclasspath` and `-Xbootclasspath/p` options will be
     removed, as noted above.  At compile time, the new `-release` option
     can be used to specify an alternate platform version (see
-    [JEP 247][jep247]).  At run time, the new `-Xoverride` option,
-    described above, can be used to override the content of system
+    [JEP 247][jep247]).  At run time, the new `-Xpatch` option,
+    described above, can be used to inject content into system
     modules.
 
   - The JDK-specific system property `sun.boot.class.path` will be
     removed, since there is no longer a bootstrap class path.  Existing
     code that uses this property might not work correctly.  (This has not
     yet been implemented in the prototype; the value of this property is,
     at the moment, not a valid class path.)
 
   - The JDK-specific annotation `@jdk.Exported`, introduced by
     [JEP 179][jep179], will be removed since the information it conveys
