1 /* 2 * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 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 51 * contains three modules ({@code m1}, {@code m2}, {@code m3}). The edges in 52 * its readability graph are: </p> 53 * <pre> {@code 54 * m1 --> m2 (meaning m1 reads m2) 55 * m1 --> m3 56 * m2 --> m3 57 * } </pre> 58 * 59 * <p> Resolution is an additive process. When computing the transitive closure 60 * then the dependence relation may include dependences on modules in {@link 61 * java.lang.module.Configuration#parents() parent} configurations. The result 62 * is a <em>relative configuration</em> that is relative to one or more parent 63 * configurations and where the readability graph may have edges from modules 64 * in the configuration to modules in parent configurations. </p> 65 * 66 * <p> As an example, suppose we have the following observable modules: </p> 67 * <pre> {@code 68 * module m1 { requires m2; requires java.xml; } 69 * module m2 { } 70 * } </pre> 71 * 72 * <p> If module {@code m1} is resolved with the configuration for the {@link 73 * java.lang.ModuleLayer#boot() boot} layer as the parent then the resulting 74 * configuration contains two modules ({@code m1}, {@code m2}). The edges in 75 * its readability graph are: 76 * <pre> {@code 77 * m1 --> m2 78 * m1 --> java.xml 79 * } </pre> 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 121 * four modules ({@code m1}, {@code m2}, {@code m3}, {@code m4}). The edges in 122 * its readability graph are: </p> 123 * <pre> {@code 124 * m2 --> m1 125 * m3 --> m1 126 * m3 --> m4 127 * } </pre> 128 * <p> The edges in the conceptual service-use graph are: </p> 129 * <pre> {@code 130 * m1 --> m2 (meaning m1 uses a service that is provided by m2) 131 * m1 --> m3 132 * } </pre> 133 * 134 * <h2>General Exceptions</h2> 135 * 136 * <p> Unless otherwise noted, passing a {@code null} argument to a constructor 137 * or method of any class or interface in this package will cause a {@link 138 * java.lang.NullPointerException NullPointerException} to be thrown. Additionally, 139 * invoking a method with an array or collection containing a {@code null} element 140 * will cause a {@code NullPointerException}, unless otherwise specified. </p> 141 * 142 * @since 9 143 * @spec JPMS 144 */ 145 146 package java.lang.module;