Proposal: #NonHierarchicalLayers

[Thomas Watson]

> From: mark.reinhold at oracle.com
> To: jpms-spec-experts at openjdk.java.net
> Date: 10/31/2016 03:23 PM
> Subject: Proposal: #NonHierarchicalLayers
> Sent by: "jpms-spec-observers" 
<jpms-spec-observers-bounces at openjdk.java.net>
> 
> Issue summary
> -------------
> 
>   #NonHierarchicalLayers --- Layers are presently constrained to be
>   hierarchical, i.e., each layer has at most one parent.  Should this
>   restriction be relaxed so that a layer can have more than one parent?
>   Some have argued that this will be essential to the adoption of the
>   module system by a future version of the Java EE Platform.  It would
>   also enable bidirectional interoperation with existing module systems
>   such as OSGi. [1]
> 
> 
> Proposal
> --------
> 
> Revise `java.lang.module.Configuration` and `java.lang.reflect.Layer` to
> augment the existing instance methods that treat `this` as the parent of
> the child being created with corresponding static methods that take a
> list of parents.
> 
> The list of the parents of a configuration can be thought of as a search
> path.  To construct a new configuration the resolver searches for 
modules
> in the given parent configurations in the order in which they occur in
> the list, and for any given parent it searches its parents recursively 
in
> the same fashion, before moving on to the next parent in the list.  This
> search order is, thus, not only depth-first but also determined by the
> order of the parents in each list.  The latter property makes it easy to
> tell when one candidate module will shadow another.
> 
> To instantiate a new layer from a given configuration, the list of the
> configurations of its parent layers must be identical to the list of the
> parents of that configuration.
> 
> The service providers for a module in a given layer are located in the
> same way that the resolver searches for modules, i.e., depth-first and
> in list order.
> 
> 
> [1] 
http://openjdk.java.net/projects/jigsaw/spec/issues/#NonHierarchicalLayers
> 

Overall the API works well for scenarios that map existing module systems 
to JPMS.  I have questions about the new javadoc for the static methods on 
Layer and Configuration.  I would have expected the javadoc for the static 
vs. the single parent non-static methods to be largely identical.  But 
there seems to be more details on what causes errors on the static methods 
as well as additional API notes related to atomic behavior.  Is this an 
oversight, or are there more error conditions for the static methods?

Should the non-static methods be updated to state the behavior is 
equivalent to calling the static method with this Configuration/Layer as 
the single parent? 

Tom