1 /* 2 * Copyright (c) 2014, 2018, 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 package java.lang.module; 27 28 import java.io.PrintStream; 29 import java.util.ArrayDeque; 30 import java.util.ArrayList; 31 import java.util.Collection; 32 import java.util.Collections; 33 import java.util.Deque; 34 import java.util.HashMap; 35 import java.util.HashSet; 36 import java.util.List; 37 import java.util.Map; 38 import java.util.Map.Entry; 39 import java.util.Objects; 40 import java.util.Optional; 41 import java.util.Set; 42 import java.util.stream.Collectors; 43 import java.util.stream.Stream; 44 45 import jdk.internal.misc.VM; 46 import jdk.internal.module.ModuleReferenceImpl; 47 import jdk.internal.module.ModuleTarget; 48 import jdk.internal.vm.annotation.Stable; 49 50 /** 51 * A configuration that is the result of <a href="package-summary.html#resolution"> 52 * resolution</a> or resolution with 53 * <a href="{@docRoot}/java.base/java/lang/module/Configuration.html#service-binding">service binding</a>. 54 * 55 * <p> A configuration encapsulates the <em>readability graph</em> that is the 56 * output of resolution. A readability graph is a directed graph whose vertices 57 * are of type {@link ResolvedModule} and the edges represent the readability 58 * amongst the modules. {@code Configuration} defines the {@link #modules() 59 * modules()} method to get the set of resolved modules in the graph. {@code 60 * ResolvedModule} defines the {@link ResolvedModule#reads() reads()} method to 61 * get the set of modules that a resolved module reads. The modules that are 62 * read may be in the same configuration or may be in {@link #parents() parent} 63 * configurations. </p> 64 * 65 * <p> Configuration defines the {@link #resolve(ModuleFinder,List,ModuleFinder,Collection) 66 * resolve} method to resolve a collection of root modules, and the {@link 67 * #resolveAndBind(ModuleFinder,List,ModuleFinder,Collection) resolveAndBind} 68 * method to do resolution with service binding. There are instance and 69 * static variants of both methods. The instance methods create a configuration 70 * with the receiver as the parent configuration. The static methods are for 71 * more advanced cases where there can be more than one parent configuration. </p> 72 * 73 * <p> Each {@link java.lang.ModuleLayer layer} of modules in the Java virtual 74 * machine is created from a configuration. The configuration for the {@link 75 * java.lang.ModuleLayer#boot() boot} layer is obtained by invoking {@code 76 * ModuleLayer.boot().configuration()}. The configuration for the boot layer 77 * will often be the parent when creating new configurations. </p> 78 * 79 * <h3> Example </h3> 80 * 81 * <p> The following example uses the {@link 82 * #resolve(ModuleFinder,ModuleFinder,Collection) resolve} method to resolve a 83 * module named <em>myapp</em> with the configuration for the boot layer as the 84 * parent configuration. It prints the name of each resolved module and the 85 * names of the modules that each module reads. </p> 86 * 87 * <pre>{@code 88 * ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3); 89 * 90 * Configuration parent = ModuleLayer.boot().configuration(); 91 * 92 * Configuration cf = parent.resolve(finder, ModuleFinder.of(), Set.of("myapp")); 93 * cf.modules().forEach(m -> { 94 * System.out.format("%s -> %s%n", 95 * m.name(), 96 * m.reads().stream() 97 * .map(ResolvedModule::name) 98 * .collect(Collectors.joining(", "))); 99 * }); 100 * }</pre> 101 * 102 * @since 9 103 * @spec JPMS 104 * @see java.lang.ModuleLayer 105 */ 106 public final class Configuration { 107 108 // @see Configuration#empty() 109 // EMPTY_CONFIGURATION may be initialized from the CDS archive. 110 private static @Stable Configuration EMPTY_CONFIGURATION; 111 112 static { 113 // Initialize EMPTY_CONFIGURATION from the archive. 114 VM.initializeFromArchive(Configuration.class); 115 // Create a new empty Configuration if there is no archived version. 116 if (EMPTY_CONFIGURATION == null) { 117 EMPTY_CONFIGURATION = new Configuration(); 118 } 119 } 120 121 // parent configurations, in search order 122 private final List<Configuration> parents; 123 124 private final Map<ResolvedModule, Set<ResolvedModule>> graph; 125 private final Set<ResolvedModule> modules; 126 private final Map<String, ResolvedModule> nameToModule; 127 128 // constraint on target platform 129 private final String targetPlatform; 130 131 String targetPlatform() { return targetPlatform; } 132 133 private Configuration() { 134 this.parents = Collections.emptyList(); 135 this.graph = Collections.emptyMap(); 136 this.modules = Collections.emptySet(); 137 this.nameToModule = Collections.emptyMap(); 138 this.targetPlatform = null; 139 } 140 141 private Configuration(List<Configuration> parents, Resolver resolver) { 142 Map<ResolvedModule, Set<ResolvedModule>> g = resolver.finish(this); 143 144 @SuppressWarnings(value = {"rawtypes", "unchecked"}) 145 Entry<String, ResolvedModule>[] nameEntries 146 = (Entry<String, ResolvedModule>[])new Entry[g.size()]; 147 ResolvedModule[] moduleArray = new ResolvedModule[g.size()]; 148 int i = 0; 149 for (ResolvedModule resolvedModule : g.keySet()) { 150 moduleArray[i] = resolvedModule; 151 nameEntries[i] = Map.entry(resolvedModule.name(), resolvedModule); 152 i++; 153 } 154 155 this.parents = Collections.unmodifiableList(parents); 156 this.graph = g; 157 this.modules = Set.of(moduleArray); 158 this.nameToModule = Map.ofEntries(nameEntries); 159 160 this.targetPlatform = resolver.targetPlatform(); 161 } 162 163 /** 164 * Creates the Configuration for the boot layer from a pre-generated 165 * readability graph. 166 * 167 * @apiNote This method is coded for startup performance. 168 */ 169 Configuration(ModuleFinder finder, Map<String, Set<String>> map) { 170 int moduleCount = map.size(); 171 172 // create map of name -> ResolvedModule 173 @SuppressWarnings(value = {"rawtypes", "unchecked"}) 174 Entry<String, ResolvedModule>[] nameEntries 175 = (Entry<String, ResolvedModule>[])new Entry[moduleCount]; 176 ResolvedModule[] moduleArray = new ResolvedModule[moduleCount]; 177 String targetPlatform = null; 178 int i = 0; 179 for (String name : map.keySet()) { 180 ModuleReference mref = finder.find(name).orElse(null); 181 assert mref != null; 182 183 if (targetPlatform == null && mref instanceof ModuleReferenceImpl) { 184 ModuleTarget target = ((ModuleReferenceImpl)mref).moduleTarget(); 185 if (target != null) { 186 targetPlatform = target.targetPlatform(); 187 } 188 } 189 190 ResolvedModule resolvedModule = new ResolvedModule(this, mref); 191 moduleArray[i] = resolvedModule; 192 nameEntries[i] = Map.entry(name, resolvedModule); 193 i++; 194 } 195 Map<String, ResolvedModule> nameToModule = Map.ofEntries(nameEntries); 196 197 // create entries for readability graph 198 @SuppressWarnings(value = {"rawtypes", "unchecked"}) 199 Entry<ResolvedModule, Set<ResolvedModule>>[] moduleEntries 200 = (Entry<ResolvedModule, Set<ResolvedModule>>[])new Entry[moduleCount]; 201 i = 0; 202 for (ResolvedModule resolvedModule : moduleArray) { 203 Set<String> names = map.get(resolvedModule.name()); 204 ResolvedModule[] readsArray = new ResolvedModule[names.size()]; 205 int j = 0; 206 for (String name : names) { 207 readsArray[j++] = nameToModule.get(name); 208 } 209 moduleEntries[i++] = Map.entry(resolvedModule, Set.of(readsArray)); 210 } 211 212 this.parents = List.of(empty()); 213 this.graph = Map.ofEntries(moduleEntries); 214 this.modules = Set.of(moduleArray); 215 this.nameToModule = nameToModule; 216 this.targetPlatform = targetPlatform; 217 } 218 219 /** 220 * Resolves a collection of root modules, with this configuration as its 221 * parent, to create a new configuration. This method works exactly as 222 * specified by the static {@link 223 * #resolve(ModuleFinder,List,ModuleFinder,Collection) resolve} 224 * method when invoked with this configuration as the parent. In other words, 225 * if this configuration is {@code cf} then this method is equivalent to 226 * invoking: 227 * <pre> {@code 228 * Configuration.resolve(before, List.of(cf), after, roots); 229 * }</pre> 230 * 231 * @param before 232 * The <em>before</em> module finder to find modules 233 * @param after 234 * The <em>after</em> module finder to locate modules when not 235 * located by the {@code before} module finder or in parent 236 * configurations 237 * @param roots 238 * The possibly-empty collection of module names of the modules 239 * to resolve 240 * 241 * @return The configuration that is the result of resolving the given 242 * root modules 243 * 244 * @throws FindException 245 * If resolution fails for any of the observability-related reasons 246 * specified by the static {@code resolve} method 247 * @throws ResolutionException 248 * If resolution fails any of the consistency checks specified by 249 * the static {@code resolve} method 250 * @throws SecurityException 251 * If locating a module is denied by the security manager 252 */ 253 public Configuration resolve(ModuleFinder before, 254 ModuleFinder after, 255 Collection<String> roots) 256 { 257 return resolve(before, List.of(this), after, roots); 258 } 259 260 261 /** 262 * Resolves a collection of root modules, with service binding, and with 263 * this configuration as its parent, to create a new configuration. 264 * This method works exactly as specified by the static {@link 265 * #resolveAndBind(ModuleFinder,List,ModuleFinder,Collection) 266 * resolveAndBind} method when invoked with this configuration 267 * as the parent. In other words, if this configuration is {@code cf} then 268 * this method is equivalent to invoking: 269 * <pre> {@code 270 * Configuration.resolveAndBind(before, List.of(cf), after, roots); 271 * }</pre> 272 * 273 * 274 * @param before 275 * The <em>before</em> module finder to find modules 276 * @param after 277 * The <em>after</em> module finder to locate modules when not 278 * located by the {@code before} module finder or in parent 279 * configurations 280 * @param roots 281 * The possibly-empty collection of module names of the modules 282 * to resolve 283 * 284 * @return The configuration that is the result of resolving, with service 285 * binding, the given root modules 286 * 287 * @throws FindException 288 * If resolution fails for any of the observability-related reasons 289 * specified by the static {@code resolve} method 290 * @throws ResolutionException 291 * If resolution fails any of the consistency checks specified by 292 * the static {@code resolve} method 293 * @throws SecurityException 294 * If locating a module is denied by the security manager 295 */ 296 public Configuration resolveAndBind(ModuleFinder before, 297 ModuleFinder after, 298 Collection<String> roots) 299 { 300 return resolveAndBind(before, List.of(this), after, roots); 301 } 302 303 304 /** 305 * Resolves a collection of root modules, with service binding, and with 306 * the empty configuration as its parent. 307 * 308 * This method is used to create the configuration for the boot layer. 309 */ 310 static Configuration resolveAndBind(ModuleFinder finder, 311 Collection<String> roots, 312 PrintStream traceOutput) 313 { 314 List<Configuration> parents = List.of(empty()); 315 Resolver resolver = new Resolver(finder, parents, ModuleFinder.of(), traceOutput); 316 resolver.resolve(roots).bind(); 317 return new Configuration(parents, resolver); 318 } 319 320 /** 321 * Resolves a collection of root modules to create a configuration. 322 * 323 * <p> Each root module is located using the given {@code before} module 324 * finder. If a module is not found then it is located in the parent 325 * configuration as if by invoking the {@link #findModule(String) 326 * findModule} method on each parent in iteration order. If not found then 327 * the module is located using the given {@code after} module finder. The 328 * same search order is used to locate transitive dependences. Root modules 329 * or dependences that are located in a parent configuration are resolved 330 * no further and are not included in the resulting configuration. </p> 331 * 332 * <p> When all modules have been enumerated then a readability graph 333 * is computed, and in conjunction with the module exports and service use, 334 * checked for consistency. </p> 335 * 336 * <p> Resolution may fail with {@code FindException} for the following 337 * <em>observability-related</em> reasons: </p> 338 * 339 * <ul> 340 * 341 * <li><p> A root module, or a direct or transitive dependency, is not 342 * found. </p></li> 343 * 344 * <li><p> An error occurs when attempting to find a module. 345 * Possible errors include I/O errors, errors detected parsing a module 346 * descriptor ({@code module-info.class}) or two versions of the same 347 * module are found in the same directory. </p></li> 348 * 349 * </ul> 350 * 351 * <p> Resolution may fail with {@code ResolutionException} if any of the 352 * following consistency checks fail: </p> 353 * 354 * <ul> 355 * 356 * <li><p> A cycle is detected, say where module {@code m1} requires 357 * module {@code m2} and {@code m2} requires {@code m1}. </p></li> 358 * 359 * <li><p> A module reads two or more modules with the same name. This 360 * includes the case where a module reads another with the same name as 361 * itself. </p></li> 362 * 363 * <li><p> Two or more modules in the configuration export the same 364 * package to a module that reads both. This includes the case where a 365 * module {@code M} containing package {@code p} reads another module 366 * that exports {@code p} to {@code M}. </p></li> 367 * 368 * <li><p> A module {@code M} declares that it "{@code uses p.S}" or 369 * "{@code provides p.S with ...}" but package {@code p} is neither in 370 * module {@code M} nor exported to {@code M} by any module that 371 * {@code M} reads. </p></li> 372 * 373 * </ul> 374 * 375 * @implNote In the implementation then observability of modules may depend 376 * on referential integrity or other checks that ensure different builds of 377 * tightly coupled modules or modules for specific operating systems or 378 * architectures are not combined in the same configuration. 379 * 380 * @param before 381 * The <em>before</em> module finder to find modules 382 * @param parents 383 * The list parent configurations in search order 384 * @param after 385 * The <em>after</em> module finder to locate modules when not 386 * located by the {@code before} module finder or in parent 387 * configurations 388 * @param roots 389 * The possibly-empty collection of module names of the modules 390 * to resolve 391 * 392 * @return The configuration that is the result of resolving the given 393 * root modules 394 * 395 * @throws FindException 396 * If resolution fails for any of observability-related reasons 397 * specified above 398 * @throws ResolutionException 399 * If resolution fails for any of the consistency checks specified 400 * above 401 * @throws IllegalArgumentException 402 * If the list of parents is empty, or the list has two or more 403 * parents with modules for different target operating systems, 404 * architectures, or versions 405 * 406 * @throws SecurityException 407 * If locating a module is denied by the security manager 408 */ 409 public static Configuration resolve(ModuleFinder before, 410 List<Configuration> parents, 411 ModuleFinder after, 412 Collection<String> roots) 413 { 414 Objects.requireNonNull(before); 415 Objects.requireNonNull(after); 416 Objects.requireNonNull(roots); 417 418 List<Configuration> parentList = new ArrayList<>(parents); 419 if (parentList.isEmpty()) 420 throw new IllegalArgumentException("'parents' is empty"); 421 422 Resolver resolver = new Resolver(before, parentList, after, null); 423 resolver.resolve(roots); 424 425 return new Configuration(parentList, resolver); 426 } 427 428 /** 429 * Resolves a collection of root modules, with service binding, to create 430 * configuration. 431 * 432 * <p> This method works exactly as specified by {@link 433 * #resolve(ModuleFinder,List,ModuleFinder,Collection) 434 * resolve} except that the graph of resolved modules is augmented 435 * with modules induced by the service-use dependence relation. </p> 436 * 437 * <p><a id="service-binding"></a>More specifically, the root modules are 438 * resolved as if by calling {@code resolve}. The resolved modules, and 439 * all modules in the parent configurations, with {@link ModuleDescriptor#uses() 440 * service dependences} are then examined. All modules found by the given 441 * module finders that {@link ModuleDescriptor#provides() provide} an 442 * implementation of one or more of the service types are added to the 443 * module graph and then resolved as if by calling the {@code 444 * resolve} method. Adding modules to the module graph may introduce new 445 * service-use dependences and so the process works iteratively until no 446 * more modules are added. </p> 447 * 448 * <p> As service binding involves resolution then it may fail with {@code 449 * FindException} or {@code ResolutionException} for exactly the same 450 * reasons specified in {@code resolve}. </p> 451 * 452 * @param before 453 * The <em>before</em> module finder to find modules 454 * @param parents 455 * The list parent configurations in search order 456 * @param after 457 * The <em>after</em> module finder to locate modules when not 458 * located by the {@code before} module finder or in parent 459 * configurations 460 * @param roots 461 * The possibly-empty collection of module names of the modules 462 * to resolve 463 * 464 * @return The configuration that is the result of resolving, with service 465 * binding, the given root modules 466 * 467 * @throws FindException 468 * If resolution fails for any of the observability-related reasons 469 * specified by the static {@code resolve} method 470 * @throws ResolutionException 471 * If resolution fails any of the consistency checks specified by 472 * the static {@code resolve} method 473 * @throws IllegalArgumentException 474 * If the list of parents is empty, or the list has two or more 475 * parents with modules for different target operating systems, 476 * architectures, or versions 477 * @throws SecurityException 478 * If locating a module is denied by the security manager 479 */ 480 public static Configuration resolveAndBind(ModuleFinder before, 481 List<Configuration> parents, 482 ModuleFinder after, 483 Collection<String> roots) 484 { 485 Objects.requireNonNull(before); 486 Objects.requireNonNull(after); 487 Objects.requireNonNull(roots); 488 489 List<Configuration> parentList = new ArrayList<>(parents); 490 if (parentList.isEmpty()) 491 throw new IllegalArgumentException("'parents' is empty"); 492 493 Resolver resolver = new Resolver(before, parentList, after, null); 494 resolver.resolve(roots).bind(); 495 496 return new Configuration(parentList, resolver); 497 } 498 499 500 /** 501 * Returns the <em>empty</em> configuration. There are no modules in the 502 * empty configuration. It has no parents. 503 * 504 * @return The empty configuration 505 */ 506 public static Configuration empty() { 507 return EMPTY_CONFIGURATION; 508 } 509 510 511 /** 512 * Returns an unmodifiable list of this configuration's parents, in search 513 * order. If this is the {@linkplain #empty empty configuration} then an 514 * empty list is returned. 515 * 516 * @return A possibly-empty unmodifiable list of this parent configurations 517 */ 518 public List<Configuration> parents() { 519 return parents; 520 } 521 522 523 /** 524 * Returns an immutable set of the resolved modules in this configuration. 525 * 526 * @return A possibly-empty unmodifiable set of the resolved modules 527 * in this configuration 528 */ 529 public Set<ResolvedModule> modules() { 530 return modules; 531 } 532 533 534 /** 535 * Finds a resolved module in this configuration, or if not in this 536 * configuration, the {@linkplain #parents() parent} configurations. 537 * Finding a module in parent configurations is equivalent to invoking 538 * {@code findModule} on each parent, in search order, until the module 539 * is found or all parents have been searched. In a <em>tree of 540 * configurations</em> then this is equivalent to a depth-first search. 541 * 542 * @param name 543 * The module name of the resolved module to find 544 * 545 * @return The resolved module with the given name or an empty {@code 546 * Optional} if there isn't a module with this name in this 547 * configuration or any parent configurations 548 */ 549 public Optional<ResolvedModule> findModule(String name) { 550 Objects.requireNonNull(name); 551 ResolvedModule m = nameToModule.get(name); 552 if (m != null) 553 return Optional.of(m); 554 555 if (!parents.isEmpty()) { 556 return configurations() 557 .skip(1) // skip this configuration 558 .map(cf -> cf.nameToModule.get(name)) 559 .filter(Objects::nonNull) 560 .findFirst(); 561 } 562 563 return Optional.empty(); 564 } 565 566 567 Set<ModuleDescriptor> descriptors() { 568 if (modules.isEmpty()) { 569 return Collections.emptySet(); 570 } else { 571 return modules.stream() 572 .map(ResolvedModule::reference) 573 .map(ModuleReference::descriptor) 574 .collect(Collectors.toSet()); 575 } 576 } 577 578 Set<ResolvedModule> reads(ResolvedModule m) { 579 return Collections.unmodifiableSet(graph.get(m)); 580 } 581 582 /** 583 * Returns an ordered stream of configurations. The first element is this 584 * configuration, the remaining elements are the parent configurations 585 * in DFS order. 586 * 587 * @implNote For now, the assumption is that the number of elements will 588 * be very low and so this method does not use a specialized spliterator. 589 */ 590 Stream<Configuration> configurations() { 591 List<Configuration> allConfigurations = this.allConfigurations; 592 if (allConfigurations == null) { 593 allConfigurations = new ArrayList<>(); 594 Set<Configuration> visited = new HashSet<>(); 595 Deque<Configuration> stack = new ArrayDeque<>(); 596 visited.add(this); 597 stack.push(this); 598 while (!stack.isEmpty()) { 599 Configuration layer = stack.pop(); 600 allConfigurations.add(layer); 601 602 // push in reverse order 603 for (int i = layer.parents.size() - 1; i >= 0; i--) { 604 Configuration parent = layer.parents.get(i); 605 if (!visited.contains(parent)) { 606 visited.add(parent); 607 stack.push(parent); 608 } 609 } 610 } 611 this.allConfigurations = Collections.unmodifiableList(allConfigurations); 612 } 613 return allConfigurations.stream(); 614 } 615 616 private volatile List<Configuration> allConfigurations; 617 618 619 /** 620 * Returns a string describing this configuration. 621 * 622 * @return A possibly empty string describing this configuration 623 */ 624 @Override 625 public String toString() { 626 return modules().stream() 627 .map(ResolvedModule::name) 628 .collect(Collectors.joining(", ")); 629 } 630 }