10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /**
27 * Classes to support module descriptors and creating configurations of modules
28 * by means of resolution and service binding.
29 *
30 * <h2><a name="resolution">Resolution</a></h2>
31 *
32 * <p> Resolution is the process of computing the transitive closure of a set
33 * of root modules over a set of observable modules by resolving the
34 * dependences expressed by {@link
35 * java.lang.module.ModuleDescriptor.Requires requires} clauses.
36 * The <em>dependence graph</em> is augmented with edges that take account of
37 * implicitly declared dependences ({@code requires transitive}) to create a
38 * <em>readability graph</em>. The result of resolution is a {@link
39 * java.lang.module.Configuration Configuration} that encapsulates the
40 * readability graph. </p>
41 *
42 * <p> As an example, suppose we have the following observable modules: </p>
43 * <pre> {@code
44 * module m1 { requires m2; }
45 * module m2 { requires transitive m3; }
46 * module m3 { }
47 * module m4 { }
48 * } </pre>
49 *
50 * <p> If the module {@code m1} is resolved then the resulting configuration
80 * where module {@code java.xml} is in the parent configuration. For
81 * simplicity, this example omits the implicitly declared dependence on the
82 * {@code java.base} module.
83 *
84 * <p> Requires clauses that are "{@code requires static}" express an optional
85 * dependence (except at compile-time). If a module declares that it
86 * "{@code requires static M}" then resolution does not search the observable
87 * modules for "{@code M}". However, if "{@code M}" is resolved (because resolution
88 * resolves a module that requires "{@code M}" without the {@link
89 * java.lang.module.ModuleDescriptor.Requires.Modifier#STATIC static} modifier)
90 * then the readability graph will contain read edges for each module that
91 * "{@code requires static M}". </p>
92 *
93 * <p> {@link java.lang.module.ModuleDescriptor#isAutomatic() Automatic} modules
94 * receive special treatment during resolution. Each automatic module is resolved
95 * as if it "{@code requires transitive}" all observable automatic modules and
96 * all automatic modules in the parent configurations. Each automatic module is
97 * resolved so that it reads all other modules in the resulting configuration and
98 * all modules in parent configurations. </p>
99 *
100 * <h2><a name="servicebinding">Service binding</a></h2>
101 *
102 * <p> Service binding is the process of augmenting a graph of resolved modules
103 * from the set of observable modules induced by the service-use dependence
104 * ({@code uses} and {@code provides} clauses). Any module that was not
105 * previously in the graph requires resolution to compute its transitive
106 * closure. Service binding is an iterative process in that adding a module
107 * that satisfies some service-use dependence may introduce new service-use
108 * dependences. </p>
109 *
110 * <p> Suppose we have the following observable modules: </p>
111 * <pre> {@code
112 * module m1 { exports p; uses p.S; }
113 * module m2 { requires m1; provides p.S with p2.S2; }
114 * module m3 { requires m1; requires m4; provides p.S with p3.S3; }
115 * module m4 { }
116 * } </pre>
117 *
118 * <p> If the module {@code m1} is resolved then the resulting graph of modules
119 * has one module ({@code m1}). If the graph is augmented with modules induced
120 * by the service-use dependence relation then the configuration will contain
|
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /**
27 * Classes to support module descriptors and creating configurations of modules
28 * by means of resolution and service binding.
29 *
30 * <h2><a id="resolution">Resolution</a></h2>
31 *
32 * <p> Resolution is the process of computing the transitive closure of a set
33 * of root modules over a set of observable modules by resolving the
34 * dependences expressed by {@link
35 * java.lang.module.ModuleDescriptor.Requires requires} clauses.
36 * The <em>dependence graph</em> is augmented with edges that take account of
37 * implicitly declared dependences ({@code requires transitive}) to create a
38 * <em>readability graph</em>. The result of resolution is a {@link
39 * java.lang.module.Configuration Configuration} that encapsulates the
40 * readability graph. </p>
41 *
42 * <p> As an example, suppose we have the following observable modules: </p>
43 * <pre> {@code
44 * module m1 { requires m2; }
45 * module m2 { requires transitive m3; }
46 * module m3 { }
47 * module m4 { }
48 * } </pre>
49 *
50 * <p> If the module {@code m1} is resolved then the resulting configuration
80 * where module {@code java.xml} is in the parent configuration. For
81 * simplicity, this example omits the implicitly declared dependence on the
82 * {@code java.base} module.
83 *
84 * <p> Requires clauses that are "{@code requires static}" express an optional
85 * dependence (except at compile-time). If a module declares that it
86 * "{@code requires static M}" then resolution does not search the observable
87 * modules for "{@code M}". However, if "{@code M}" is resolved (because resolution
88 * resolves a module that requires "{@code M}" without the {@link
89 * java.lang.module.ModuleDescriptor.Requires.Modifier#STATIC static} modifier)
90 * then the readability graph will contain read edges for each module that
91 * "{@code requires static M}". </p>
92 *
93 * <p> {@link java.lang.module.ModuleDescriptor#isAutomatic() Automatic} modules
94 * receive special treatment during resolution. Each automatic module is resolved
95 * as if it "{@code requires transitive}" all observable automatic modules and
96 * all automatic modules in the parent configurations. Each automatic module is
97 * resolved so that it reads all other modules in the resulting configuration and
98 * all modules in parent configurations. </p>
99 *
100 * <h2><a id="servicebinding">Service binding</a></h2>
101 *
102 * <p> Service binding is the process of augmenting a graph of resolved modules
103 * from the set of observable modules induced by the service-use dependence
104 * ({@code uses} and {@code provides} clauses). Any module that was not
105 * previously in the graph requires resolution to compute its transitive
106 * closure. Service binding is an iterative process in that adding a module
107 * that satisfies some service-use dependence may introduce new service-use
108 * dependences. </p>
109 *
110 * <p> Suppose we have the following observable modules: </p>
111 * <pre> {@code
112 * module m1 { exports p; uses p.S; }
113 * module m2 { requires m1; provides p.S with p2.S2; }
114 * module m3 { requires m1; requires m4; provides p.S with p3.S3; }
115 * module m4 { }
116 * } </pre>
117 *
118 * <p> If the module {@code m1} is resolved then the resulting graph of modules
119 * has one module ({@code m1}). If the graph is augmented with modules induced
120 * by the service-use dependence relation then the configuration will contain
|