JEP 261 update: -Xoverride becomes -Xpatch

[mark.reinhold at oracle.com]

Based on some initial experience we now have answers to the open issues
in JEP 261 [1] regarding the -Xoverride option.

We've seen two kinds of use cases for -Xoverride:

  - By JDK developers, to replace system classes with new versions in
    active development, so that they don't have to rebuild the entire
    module (or all the modules) on which they're working; and

  - By test harnesses, to arrange for white-box tests to run in the same
    package as the code being tested, even when that package is not
    exported by its defining module.

The -Xoverride option as it stands works well enough for development, but
it's fairly clumsy for test harnesses.  So, to answer the open questions:

  - Should it take a module path rather than a single directory?

Yes.  If a harness is going to run multiple tests in the same test run,
which is of course highly desirable for efficiency, then it may need to
inject test classes into many different unexported packages.  It could in
principle do that by copying all such classes into a single directory
tree, but that's just busywork.

The parameter to -Xoverride should not, however, exactly be a module
path.  For testing purposes it's more convenient to treat it like a class
path, with "leaky" path semantics.  That is, given a module name and a
class name the search should examine every module definition of that name
on the path, in order, for a class of that name, rather than stop after
the first module.  That way a test harness can inject multiple tests into
the same package without having to copy files around.

  - Can it be used to override `module-info.class` files?

No.  The primary use case here is wanting to arrange for a module under
test to invoke the test harness in a different module, or to export
additional packages for the test harness to exercise.  This entails
amending the declaration of the module under test with new `requires` or
`exports` clauses.  Since we have no way to express the augmentation of
a module declaration in either source or binary form (and would really
rather avoid that complexity!), a test would need to maintain a complete
revised declaration for the module under test and keep it in sync with
the actual module definition.  This would lead to tests that are
difficult to maintain.

If a test needs to augment the declaration of a module under test then
the harness should do so, on its behalf, via the reflection API or
command-line options.  At present a harness can use the -XaddExports
option to, effectively, add `exports` clauses at run time.  There is,
however, no way to add `requires` clauses (i.e., reads edges) to the
module graph via the command line, so we'll add an -XaddReads option to
do that.  (This option was actually present in earlier versions of the
prototype, so this change just amounts to bringing it back.)  The
parameter to -XaddReads will have the same syntax as -XaddExports,
and ALL-UNNAMED will be supported.

  - Can it be used to add packages to modules?  (If it can be used to
    override `module-info.class` files then this is implied.)

Yes.  This ability is useful in the case of working on the JDK itself;
consider, e.g., refactoring an existing package into two packages.

Packages added in this way will, by default, not be exported, but they
can be exported via the reflection API or the -XaddExports option.

  - Can it be used to override non-class resources?  (The implementation
    currently disallows this.)

Yes.  Allowing this is consistent with allowing new packages.

  - Is there a better name for this option?

Yes.  With the ability to add packages and resources it's no longer about
overriding existing definitions but, in fact, patching the entire system,
so we'll rename this to "-Xpatch".

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.

- Mark


[1] http://openjdk.java.net/jeps/261