Proposal: #ReadabilityAddedByLayerCreator

[Thomas Watson]

I think this proposal will work fine for the usage I have in mind.  I like 
the approach of a Controller because it provides a place to put other 
commands which a framework could use to control the modules within the 
Layer.  I see you have taken advantage of that in other proposals.

I look forward to trying out the API when it gets into a build.

Thanks

Tom


> From: mark.reinhold at oracle.com
> To: jpms-spec-experts at openjdk.java.net
> Date: 11/18/2016 10:28 AM
> Subject: Proposal: #ReadabilityAddedByLayerCreator
> Sent by: "jpms-spec-observers" 
<jpms-spec-observers-bounces at openjdk.java.net>
> 
> 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
>