/*
* Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.lang.module;
import java.io.PrintStream;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Deque;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/**
* The configuration that is the result of resolution or resolution with
* service binding.
*
* <h2><a name="resolution">Resolution</a></h2>
*
* <p> Resolution is the process of computing the transitive closure of a set
* of root modules over a set of observable modules by resolving the
* dependences expressed by {@code requires} clauses.
*
* The <em>dependence graph</em> is augmented with edges that take account of
* implicitly declared dependences ({@code requires transitive}) to create a
* <em>readability graph</em>. A {@code Configuration} encapsulates the
* resulting graph of {@link ResolvedModule resolved modules}.
*
* <p> Suppose we have the following observable modules: </p>
* <pre> {@code
* module m1 { requires m2; }
* module m2 { requires transitive m3; }
* module m3 { }
* module m4 { }
* } </pre>
*
* <p> If the module {@code m1} is resolved then the resulting configuration
* contains three modules ({@code m1}, {@code m2}, {@code m3}). The edges in
* its readability graph are: </p>
* <pre> {@code
* m1 --> m2 (meaning m1 reads m2)
* m1 --> m3
* m2 --> m3
* } </pre>
*
* <p> Resolution is an additive process. When computing the transitive closure
* then the dependence relation may include dependences on modules in parent
* configurations. The result is a <em>relative configuration</em> that is
* relative to one or more parent configurations and where the readability graph
* may have edges from modules in the configuration to modules in parent
* configurations.
*
* </p>
*
* <p> Suppose we have the following observable modules: </p>
* <pre> {@code
* module m1 { requires m2; requires java.xml; }
* module m2 { }
* } </pre>
*
* <p> If module {@code m1} is resolved with the configuration for the {@link
* java.lang.reflect.Layer#boot() boot} layer as the parent then the resulting
* configuration contains two modules ({@code m1}, {@code m2}). The edges in
* its readability graph are:
* <pre> {@code
* m1 --> m2
* m1 --> java.xml
* } </pre>
* where module {@code java.xml} is in the parent configuration. For
* simplicity, this example omits the implicitly declared dependence on the
* {@code java.base} module.
*
* <a name="automaticmoduleresolution"></a>
* <p> {@link ModuleDescriptor#isAutomatic() Automatic} modules receive special
* treatment during resolution. Each automatic module is resolved so that it
* reads all other modules in the configuration and all parent configurations.
* Each automatic module is also resolved as if it {@code requires transitive}
* all other automatic modules in the configuration (and all automatic modules
* in parent configurations). </p>
* <h2><a name="servicebinding">Service binding</a></h2>
*
* <p> Service binding is the process of augmenting a graph of resolved modules
* from the set of observable modules induced by the service-use dependence
* ({@code uses} and {@code provides} clauses). Any module that was not
* previously in the graph requires resolution to compute its transitive
* closure. Service binding is an iterative process in that adding a module
* that satisfies some service-use dependence may introduce new service-use
* dependences. </p>
*
* <p> Suppose we have the following observable modules: </p>
* <pre> {@code
* module m1 { exports p; uses p.S; }
* module m2 { requires m1; provides p.S with p2.S2; }
* module m3 { requires m1; requires m4; provides p.S with p3.S3; }
* module m4 { }
* } </pre>
*
* <p> If the module {@code m1} is resolved then the resulting graph of modules
* has one module ({@code m1}). If the graph is augmented with modules induced
* by the service-use dependence relation then the configuration will contain
* four modules ({@code m1}, {@code m2}, {@code m3}, {@code m4}). The edges in
* its readability graph are: </p>
* <pre> {@code
* m2 --> m1
* m3 --> m1
* m3 --> m4
* } </pre>
* <p> The edges in the conceptual service-use graph are: </p>
* <pre> {@code
* m1 --> m2 (meaning m1 uses a service that is provided by m2)
* m1 --> m3
* } </pre>
*
* <p> If this configuration is instantiated as a {@code Layer}, and if code in
* module {@code m1} uses {@link java.util.ServiceLoader ServiceLoader} to
* iterate over implementations of {@code p.S.class}, then it will iterate over
* an instance of {@code p2.S2} and {@code p3.S3}. </p>
*
* <h3> Example </h3>
*
* <p> The following example uses the {@code resolveRequires} method to resolve
* a module named <em>myapp</em> with the configuration for the boot layer as
* the parent configuration. It prints the name of each resolved module and
* the names of the modules that each module reads. </p>
*
* <pre>{@code
* ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
*
* Configuration parent = Layer.boot().configuration();
*
* Configuration cf = parent.resolveRequires(finder,
* ModuleFinder.of(),
* Set.of("myapp"));
* cf.modules().forEach(m -> {
* System.out.format("%s -> %s%n",
* m.name(),
* m.reads().stream()
* .map(ResolvedModule::name)
* .collect(Collectors.joining(", ")));
* });
* }</pre>
*
* @since 9
* @see java.lang.reflect.Layer
*/
public final class Configuration {
// @see Configuration#empty()
private static final Configuration EMPTY_CONFIGURATION = new Configuration();
// parent configurations, in search order
private final List<Configuration> parents;
private final Map<ResolvedModule, Set<ResolvedModule>> graph;
private final Set<ResolvedModule> modules;
private final Map<String, ResolvedModule> nameToModule;
private Configuration() {
this.parents = Collections.emptyList();
this.graph = Collections.emptyMap();
this.modules = Collections.emptySet();
this.nameToModule = Collections.emptyMap();
}
private Configuration(List<Configuration> parents,
Resolver resolver,
boolean check)
{
Map<ResolvedModule, Set<ResolvedModule>> g = resolver.finish(this, check);
@SuppressWarnings(value = {"rawtypes", "unchecked"})
Entry<String, ResolvedModule>[] nameEntries
= (Entry<String, ResolvedModule>[])new Entry[g.size()];
ResolvedModule[] moduleArray = new ResolvedModule[g.size()];
int i = 0;
for (ResolvedModule resolvedModule : g.keySet()) {
moduleArray[i] = resolvedModule;
nameEntries[i] = Map.entry(resolvedModule.name(), resolvedModule);
i++;
}
this.parents = Collections.unmodifiableList(parents);
this.graph = g;
this.modules = Set.of(moduleArray);
this.nameToModule = Map.ofEntries(nameEntries);
}
/**
* Resolves a collection of root modules, with this configuration as its
* parent, to create a new configuration. This method works exactly as
* specified by the static {@link
* #resolveRequires(ModuleFinder,List,ModuleFinder,Collection) resolveRequires}
* method when invoked with this configuration as the parent. In other words,
* if this configuration is {@code cf} then this method is equivalent to
* invoking:
* <pre> {@code
* Configuration.resolveRequires(before, List.of(cf), after, roots);
* }</pre>
*
* @param before
* The <em>before</em> module finder to find modules
* @param after
* The <em>after</em> module finder to locate modules when a
* module cannot be located by the {@code before} module finder
* and the module is not in this configuration
* @param roots
* The possibly-empty collection of module names of the modules
* to resolve
*
* @return The configuration that is the result of resolving the given
* root modules
*
* @throws ResolutionException
* If resolution or the post-resolution checks fail
* @throws SecurityException
* If locating a module is denied by the security manager
*/
public Configuration resolveRequires(ModuleFinder before,
ModuleFinder after,
Collection<String> roots)
{
return resolveRequires(before, List.of(this), after, roots);
}
/**
* Resolves a collection of root modules, with service binding, and with
* this configuration as its parent, to create a new configuration.
* This method works exactly as specified by the static {@link
* #resolveRequiresAndUses(ModuleFinder,List,ModuleFinder,Collection)
* resolveRequiresAndUses} method when invoked with this configuration
* as the parent. In other words, if this configuration is {@code cf} then
* this method is equivalent to invoking:
* <pre> {@code
* Configuration.resolveRequiresAndUses(before, List.of(cf), after, roots);
* }</pre>
*
*
* @param before
* The <em>before</em> module finder to find modules
* @param after
* The <em>after</em> module finder to locate modules when not
* located by the {@code before} module finder and this
* configuration
* @param roots
* The possibly-empty collection of module names of the modules
* to resolve
*
* @return The configuration that is the result of resolving the given
* root modules
*
* @throws ResolutionException
* If resolution or the post-resolution checks fail
* @throws SecurityException
* If locating a module is denied by the security manager
*/
public Configuration resolveRequiresAndUses(ModuleFinder before,
ModuleFinder after,
Collection<String> roots)
{
return resolveRequiresAndUses(before, List.of(this), after, roots);
}
/**
* Resolves a collection of root modules, with service binding, and with
* the empty configuration as its parent. The post resolution checks
* are optionally run.
*
* This method is used to create the configuration for the boot layer.
*/
static Configuration resolveRequiresAndUses(ModuleFinder finder,
Collection<String> roots,
boolean check,
PrintStream traceOutput)
{
List<Configuration> parents = List.of(empty());
Resolver resolver = new Resolver(finder, parents, ModuleFinder.of(), traceOutput);
resolver.resolveRequires(roots).resolveUses();
return new Configuration(parents, resolver, check);
}
/**
* Resolves a collection of root modules to create a configuration.
*
* <p> Each root module is located using the given {@code before} module
* finder. If a module is not found then it is located in the parent
* configuration as if by invoking the {@link #findModule(String)
* findModule} method on each parent in iteration order. If not found then
* the module is located using the given {@code after} module finder. The
* same search order is used to locate transitive dependences. Root modules
* or dependences that are located in a parent configuration are resolved
* no further and are not included in the resulting configuration. </p>
*
* <p> When all modules have been resolved then the resulting dependency
* graph is checked to ensure that it does not contain cycles. A
* readability graph is constructed and in conjunction with the module
* exports and service use, checked for consistency. </p>
*
* <p> Resolution and the (post-resolution) consistency checks may fail for
* following reasons: </p>
*
* <ul>
* <li><p> A root module, or a direct or transitive dependency, is not
* found. </p></li>
*
* <li><p> An error occurs when attempting to find a module.
* Possible errors include I/O errors, errors detected parsing a module
* descriptor ({@code module-info.class}) or two versions of the same
* module are found in the same directory. </p></li>
*
* <li><p> A cycle is detected, say where module {@code m1} requires
* module {@code m2} and {@code m2} requires {@code m1}. </p></li>
*
* <li><p> Two or more modules in the configuration export the same
* package to a module that reads both. This includes the case where a
* module {@code M} containing package {@code p} reads another module
* that exports {@code p} to {@code M}. </p></li>
*
* <li><p> A module {@code M} declares that it "{@code uses p.S}" or
* "{@code provides p.S with ...}" but package {@code p} is neither in
* module {@code M} nor exported to {@code M} by any module that
* {@code M} reads. </p></li>
*
* <li><p> A module {@code M} declares that it
* "{@code provides ... with q.T}" but package {@code q} is not in
* module {@code M}. </p></li>
*
* <li><p> Two or more modules in the configuration are specific to
* different {@link ModuleDescriptor#osName() operating systems},
* {@link ModuleDescriptor#osArch() architectures}, or {@link
* ModuleDescriptor#osVersion() versions}. </p></li>
*
* <li><p> Other implementation specific checks, for example referential
* integrity checks to ensure that different versions of tighly coupled
* modules cannot be combined in the same configuration. </p></li>
*
* </ul>
*
* @param before
* The <em>before</em> module finder to find modules
* @param parents
* The list parent configurations in search order
* @param after
* The <em>after</em> module finder to locate modules when not
* located by the {@code before} module finder or in parent
* configurations
* @param roots
* The possibly-empty collection of module names of the modules
* to resolve
*
* @return The configuration that is the result of resolving the given
* root modules
*
* @throws ResolutionException
* If resolution or the post-resolution checks fail
* @throws IllegalArgumentException
* If the list of parents is empty
* @throws SecurityException
* If locating a module is denied by the security manager
*/
public static Configuration resolveRequires(ModuleFinder before,
List<Configuration> parents,
ModuleFinder after,
Collection<String> roots)
{
Objects.requireNonNull(before);
Objects.requireNonNull(after);
Objects.requireNonNull(roots);
List<Configuration> parentList = new ArrayList<>(parents);
if (parentList.isEmpty())
throw new IllegalArgumentException("'parents' is empty");
Resolver resolver = new Resolver(before, parentList, after, null);
resolver.resolveRequires(roots);
return new Configuration(parentList, resolver, true);
}
/**
* Resolves a collection of root modules, with service binding, to create
* configuration.
*
* <p> This method works exactly as specified by {@link
* #resolveRequires(ModuleFinder,List,ModuleFinder,Collection)
* resolveRequires} except that the graph of resolved modules is augmented
* with modules induced by the service-use dependence relation. </p>
*
* <p> More specifically, the root modules are resolved as if by calling
* {@code resolveRequires}. The resolved modules, and all modules in the
* parent configurations, with {@link ModuleDescriptor#uses() service
* dependences} are then examined. All modules found by the given module
* finders that {@link ModuleDescriptor#provides() provide} an
* implementation of one or more of the service types are added to the
* module graph and then resolved as if by calling the {@code
* resolveRequires} method. Adding modules to the module graph may
* introduce new service-use dependences and so the process works
* iteratively until no more modules are added. </p>
*
* <p> As service binding involves resolution then it may fail with {@link
* ResolutionException} for exactly the same reasons specified in
* {@code resolveRequires}. </p>
*
* @param before
* The <em>before</em> module finder to find modules
* @param parents
* The list parent configurations in search order
* @param after
* The <em>after</em> module finder to locate modules when not
* located by the {@code before} module finder or in parent
* configurations
* @param roots
* The possibly-empty collection of module names of the modules
* to resolve
*
* @return The configuration that is the result of resolving the given
* root modules
*
* @throws ResolutionException
* If resolution or the post-resolution checks fail
* @throws IllegalArgumentException
* If the list of parents is empty
* @throws SecurityException
* If locating a module is denied by the security manager
*/
public static Configuration resolveRequiresAndUses(ModuleFinder before,
List<Configuration> parents,
ModuleFinder after,
Collection<String> roots)
{
Objects.requireNonNull(before);
Objects.requireNonNull(after);
Objects.requireNonNull(roots);
List<Configuration> parentList = new ArrayList<>(parents);
if (parentList.isEmpty())
throw new IllegalArgumentException("'parents' is empty");
Resolver resolver = new Resolver(before, parentList, after, null);
resolver.resolveRequires(roots).resolveUses();
return new Configuration(parentList, resolver, true);
}
/**
* Returns the <em>empty</em> configuration. There are no modules in the
* empty configuration. It has no parents.
*
* @return The empty configuration
*/
public static Configuration empty() {
return EMPTY_CONFIGURATION;
}
/**
* Returns an unmodifiable list of this configuration's parents, in search
* order. If this is the {@linkplain #empty empty configuration} then an
* empty list is returned.
*
* @return A possibly-empty unmodifiable list of this parent configurations
*/
public List<Configuration> parents() {
return parents;
}
/**
* Returns an immutable set of the resolved modules in this configuration.
*
* @return A possibly-empty unmodifiable set of the resolved modules
* in this configuration
*/
public Set<ResolvedModule> modules() {
return modules;
}
/**
* Finds a resolved module in this configuration, or if not in this
* configuration, the {@linkplain #parents parent} configurations.
* Finding a module in parent configurations is equivalent to invoking
* {@code findModule} on each parent, in search order, until the module
* is found or all parents have been searched. In a <em>tree of
* configurations</em> then this is equivalent to a depth-first search.
*
* @param name
* The module name of the resolved module to find
*
* @return The resolved module with the given name or an empty {@code
* Optional} if there isn't a module with this name in this
* configuration or any parent configurations
*/
public Optional<ResolvedModule> findModule(String name) {
Objects.requireNonNull(name);
ResolvedModule m = nameToModule.get(name);
if (m != null)
return Optional.of(m);
if (!parents.isEmpty()) {
return configurations()
.skip(1) // skip this configuration
.map(cf -> cf.nameToModule)
.filter(map -> map.containsKey(name))
.map(map -> map.get(name))
.findFirst();
}
return Optional.empty();
}
Set<ModuleDescriptor> descriptors() {
if (modules.isEmpty()) {
return Collections.emptySet();
} else {
return modules.stream()
.map(ResolvedModule::reference)
.map(ModuleReference::descriptor)
.collect(Collectors.toSet());
}
}
Set<ResolvedModule> reads(ResolvedModule m) {
return Collections.unmodifiableSet(graph.get(m));
}
/**
* Returns an ordered stream of configurations. The first element is this
* configuration, the remaining elements are the parent configurations
* in DFS order.
*
* @implNote For now, the assumption is that the number of elements will
* be very low and so this method does not use a specialized spliterator.
*/
Stream<Configuration> configurations() {
List<Configuration> allConfigurations = this.allConfigurations;
if (allConfigurations == null) {
allConfigurations = new ArrayList<>();
Set<Configuration> visited = new HashSet<>();
Deque<Configuration> stack = new ArrayDeque<>();
visited.add(this);
stack.push(this);
while (!stack.isEmpty()) {
Configuration layer = stack.pop();
allConfigurations.add(layer);
// push in reverse order
for (int i = layer.parents.size() - 1; i >= 0; i--) {
Configuration parent = layer.parents.get(i);
if (!visited.contains(parent)) {
visited.add(parent);
stack.push(parent);
}
}
}
this.allConfigurations = Collections.unmodifiableList(allConfigurations);
}
return allConfigurations.stream();
}
private volatile List<Configuration> allConfigurations;
/**
* Returns a string describing this configuration.
*
* @return A possibly empty string describing this configuration
*/
@Override
public String toString() {
return modules().stream()
.map(ResolvedModule::name)
.collect(Collectors.joining(", "));
}
}