Proposal: #ReadabilityAddedByLayerCreator

Fri Nov 18 16:28:09 UTC 2016

Issue summary
-------------
 #ReadabilityAddedByLayerCreator --- Provide a means by which the code
 that creates a layer can add readability edges from the modules in that
 layer to other modules, whether those modules are in that layer or in
 other layers. [1]
Proposal
--------
Revise `java.lang.reflect.Layer` so that the multi-parent layer-creation
methods added for #NonHierarchicalLayers [2] return a capability object
rather than the resulting layer. The capability will be represented by
instances of a new nested class, `java.lang.reflect.Layer.Controller`,
which will define an `addReads` method and also a method to retrieve the
actual layer:
 public final static class Controller {
 /** Return the actual layer */
 public Layer layer();
 /**
 * Add the specified reads edge, if not already present.
 * Return this controller, so that invocations can be
 * chained.
 */
 public Controller addReads(Module source, Module target);
 }
Typical usage would be:
 Layer.Controller lc = Layer.defineModules(cf, parents, clf);
 Module m1 = lc.layer().findModule("m1").get();
 Module m2 = otherLayer.findModule("m2").get();
 lc.addReads(m1, m2); // Ensures m1.canRead(m2) == true
The source module must be in the controller's layer; the target module
can be in any layer. This method does nothing if the source module can
already read the target module.
Like all capability objects, instances of `Layer.Controller` must be
handled with care since leaking them could enable malicious use.
[1] http://openjdk.java.net/projects/jigsaw/spec/issues/#ReadabilityAddedByLayerCreator
[2] http://mail.openjdk.java.net/pipermail/jpms-spec-experts/2016-October/000442.html