1 /* 2 * Copyright (c) 2009, 2020, 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.InputStream; 29 import java.io.IOException; 30 import java.io.PrintStream; 31 import java.io.UncheckedIOException; 32 import java.nio.ByteBuffer; 33 import java.nio.file.Path; 34 import java.util.ArrayList; 35 import java.util.Arrays; 36 import java.util.Collection; 37 import java.util.Collections; 38 import java.util.EnumSet; 39 import java.util.HashMap; 40 import java.util.HashSet; 41 import java.util.List; 42 import java.util.Locale; 43 import java.util.Map; 44 import java.util.Objects; 45 import java.util.Optional; 46 import java.util.Set; 47 import java.util.function.Supplier; 48 import java.util.stream.Collectors; 49 import java.util.stream.Stream; 50 51 import static jdk.internal.module.Checks.*; 52 import static java.util.Objects.*; 53 54 import jdk.internal.module.Checks; 55 import jdk.internal.module.ModuleInfo; 56 57 58 /** 59 * A module descriptor. 60 * 61 * <p> A module descriptor describes a named module and defines methods to 62 * obtain each of its components. The module descriptor for a named module 63 * in the Java virtual machine is obtained by invoking the {@link 64 * java.lang.Module Module}'s {@link java.lang.Module#getDescriptor 65 * getDescriptor} method. Module descriptors can also be created using the 66 * {@link ModuleDescriptor.Builder} class or by reading the binary form of a 67 * module declaration ({@code module-info.class}) using the {@link 68 * #read(InputStream,Supplier) read} methods defined here. </p> 69 * 70 * <p> A module descriptor describes a <em>normal</em>, open, or automatic 71 * module. <em>Normal</em> modules and open modules describe their {@linkplain 72 * #requires() dependences}, {@link #exports() exported-packages}, the services 73 * that they {@linkplain #uses() use} or {@linkplain #provides() provide}, and other 74 * components. <em>Normal</em> modules may {@linkplain #opens() open} specific 75 * packages. The module descriptor for an open module does not declare any 76 * open packages (its {@code opens} method returns an empty set) but when 77 * instantiated in the Java virtual machine then it is treated as if all 78 * packages are open. The module descriptor for an automatic module does not 79 * declare any dependences (except for the mandatory dependency on {@code 80 * java.base}), and does not declare any exported or open packages. Automatic 81 * modules receive special treatment during resolution so that they read all 82 * other modules in the configuration. When an automatic module is instantiated 83 * in the Java virtual machine then it reads every unnamed module and is 84 * treated as if all packages are exported and open. </p> 85 * 86 * <p> {@code ModuleDescriptor} objects are immutable and safe for use by 87 * multiple concurrent threads.</p> 88 * 89 * @see java.lang.Module 90 * @since 9 91 * @spec JPMS 92 */ 93 94 public class ModuleDescriptor 95 implements Comparable<ModuleDescriptor> 96 { 97 98 /** 99 * A modifier on a module. 100 * 101 * @see ModuleDescriptor#modifiers() 102 * @since 9 103 * @spec JPMS 104 */ 105 public enum Modifier { 106 /** 107 * An open module. An open module does not declare any open packages 108 * but the resulting module is treated as if all packages are open. 109 */ 110 OPEN, 111 112 /** 113 * An automatic module. An automatic module is treated as if it exports 114 * and opens all packages. 115 * 116 * @apiNote This modifier does not correspond to a module flag in the 117 * binary form of a module declaration ({@code module-info.class}). 118 */ 119 AUTOMATIC, 120 121 /** 122 * The module was not explicitly or implicitly declared. 123 */ 124 SYNTHETIC, 125 126 /** 127 * The module was implicitly declared. 128 */ 129 MANDATED; 130 } 131 132 133 /** 134 * <p> A dependence upon a module. </p> 135 * 136 * @see ModuleDescriptor#requires() 137 * @since 9 138 * @spec JPMS 139 */ 140 141 public final static class Requires 142 implements Comparable<Requires> 143 { 144 145 /** 146 * A modifier on a module dependence. 147 * 148 * @see Requires#modifiers() 149 * @since 9 150 * @spec JPMS 151 */ 152 public enum Modifier { 153 154 /** 155 * The dependence causes any module which depends on the <i>current 156 * module</i> to have an implicitly declared dependence on the module 157 * named by the {@code Requires}. 158 */ 159 TRANSITIVE, 160 161 /** 162 * The dependence is mandatory in the static phase, during compilation, 163 * but is optional in the dynamic phase, during execution. 164 */ 165 STATIC, 166 167 /** 168 * The dependence was not explicitly or implicitly declared in the 169 * source of the module declaration. 170 */ 171 SYNTHETIC, 172 173 /** 174 * The dependence was implicitly declared in the source of the module 175 * declaration. 176 */ 177 MANDATED; 178 179 } 180 181 private final Set<Modifier> mods; 182 private final String name; 183 private final Version compiledVersion; 184 private final String rawCompiledVersion; 185 186 private Requires(Set<Modifier> ms, String mn, Version v, String vs) { 187 assert v == null || vs == null; 188 this.mods = Set.copyOf(ms); 189 this.name = mn; 190 this.compiledVersion = v; 191 this.rawCompiledVersion = vs; 192 } 193 194 private Requires(Set<Modifier> ms, String mn, Version v, boolean unused) { 195 this.mods = ms; 196 this.name = mn; 197 this.compiledVersion = v; 198 this.rawCompiledVersion = null; 199 } 200 201 /** 202 * Returns the set of modifiers. 203 * 204 * @return A possibly-empty unmodifiable set of modifiers 205 */ 206 public Set<Modifier> modifiers() { 207 return mods; 208 } 209 210 /** 211 * Return the module name. 212 * 213 * @return The module name 214 */ 215 public String name() { 216 return name; 217 } 218 219 /** 220 * Returns the version of the module if recorded at compile-time. 221 * 222 * @return The version of the module if recorded at compile-time, 223 * or an empty {@code Optional} if no version was recorded or 224 * the version string recorded is {@linkplain Version#parse(String) 225 * unparseable} 226 */ 227 public Optional<Version> compiledVersion() { 228 return Optional.ofNullable(compiledVersion); 229 } 230 231 /** 232 * Returns the string with the possibly-unparseable version of the module 233 * if recorded at compile-time. 234 * 235 * @return The string containing the version of the module if recorded 236 * at compile-time, or an empty {@code Optional} if no version 237 * was recorded 238 * 239 * @see #compiledVersion() 240 */ 241 public Optional<String> rawCompiledVersion() { 242 if (compiledVersion != null) { 243 return Optional.of(compiledVersion.toString()); 244 } else { 245 return Optional.ofNullable(rawCompiledVersion); 246 } 247 } 248 249 /** 250 * Compares this module dependence to another. 251 * 252 * <p> Two {@code Requires} objects are compared by comparing their 253 * module names lexicographically. Where the module names are equal 254 * then the sets of modifiers are compared in the same way that 255 * module modifiers are compared (see {@link ModuleDescriptor#compareTo 256 * ModuleDescriptor.compareTo}). Where the module names are equal and 257 * the set of modifiers are equal then the version of the modules 258 * recorded at compile-time are compared. When comparing the versions 259 * recorded at compile-time then a dependence that has a recorded 260 * version is considered to succeed a dependence that does not have a 261 * recorded version. If both recorded versions are {@linkplain 262 * Version#parse(String) unparseable} then the {@linkplain 263 * #rawCompiledVersion() raw version strings} are compared 264 * lexicographically. </p> 265 * 266 * @param that 267 * The module dependence to compare 268 * 269 * @return A negative integer, zero, or a positive integer if this module 270 * dependence is less than, equal to, or greater than the given 271 * module dependence 272 */ 273 @Override 274 public int compareTo(Requires that) { 275 if (this == that) return 0; 276 277 int c = this.name().compareTo(that.name()); 278 if (c != 0) return c; 279 280 // modifiers 281 long v1 = modsValue(this.modifiers()); 282 long v2 = modsValue(that.modifiers()); 283 c = Long.compare(v1, v2); 284 if (c != 0) return c; 285 286 // compiledVersion 287 c = compare(this.compiledVersion, that.compiledVersion); 288 if (c != 0) return c; 289 290 // rawCompiledVersion 291 c = compare(this.rawCompiledVersion, that.rawCompiledVersion); 292 if (c != 0) return c; 293 294 return 0; 295 } 296 297 /** 298 * Tests this module dependence for equality with the given object. 299 * 300 * <p> If the given object is not a {@code Requires} then this method 301 * returns {@code false}. Two module dependence objects are equal if 302 * the module names are equal, set of modifiers are equal, and the 303 * compiled version of both modules is equal or not recorded for 304 * both modules. </p> 305 * 306 * <p> This method satisfies the general contract of the {@link 307 * java.lang.Object#equals(Object) Object.equals} method. </p> 308 * 309 * @param ob 310 * the object to which this object is to be compared 311 * 312 * @return {@code true} if, and only if, the given object is a module 313 * dependence that is equal to this module dependence 314 */ 315 @Override 316 public boolean equals(Object ob) { 317 if (!(ob instanceof Requires)) 318 return false; 319 Requires that = (Requires)ob; 320 return name.equals(that.name) && mods.equals(that.mods) 321 && Objects.equals(compiledVersion, that.compiledVersion) 322 && Objects.equals(rawCompiledVersion, that.rawCompiledVersion); 323 } 324 325 /** 326 * Computes a hash code for this module dependence. 327 * 328 * <p> The hash code is based upon the module name, modifiers, and the 329 * module version if recorded at compile time. It satisfies the general 330 * contract of the {@link Object#hashCode Object.hashCode} method. </p> 331 * 332 * @return The hash-code value for this module dependence 333 */ 334 @Override 335 public int hashCode() { 336 int hash = name.hashCode() * 43 + mods.hashCode(); 337 if (compiledVersion != null) 338 hash = hash * 43 + compiledVersion.hashCode(); 339 if (rawCompiledVersion != null) 340 hash = hash * 43 + rawCompiledVersion.hashCode(); 341 return hash; 342 } 343 344 /** 345 * Returns a string describing this module dependence. 346 * 347 * @return A string describing this module dependence 348 */ 349 @Override 350 public String toString() { 351 String what; 352 if (compiledVersion != null) { 353 what = name() + " (@" + compiledVersion + ")"; 354 } else { 355 what = name(); 356 } 357 return ModuleDescriptor.toString(mods, what); 358 } 359 } 360 361 362 363 /** 364 * <p> A package exported by a module, may be qualified or unqualified. </p> 365 * 366 * @see ModuleDescriptor#exports() 367 * @since 9 368 * @spec JPMS 369 */ 370 371 public final static class Exports 372 implements Comparable<Exports> 373 { 374 375 /** 376 * A modifier on an exported package. 377 * 378 * @see Exports#modifiers() 379 * @since 9 380 * @spec JPMS 381 */ 382 public enum Modifier { 383 384 /** 385 * The export was not explicitly or implicitly declared in the 386 * source of the module declaration. 387 */ 388 SYNTHETIC, 389 390 /** 391 * The export was implicitly declared in the source of the module 392 * declaration. 393 */ 394 MANDATED; 395 396 } 397 398 private final Set<Modifier> mods; 399 private final String source; 400 private final Set<String> targets; // empty if unqualified export 401 402 /** 403 * Constructs an export 404 */ 405 private Exports(Set<Modifier> ms, String source, Set<String> targets) { 406 this.mods = Set.copyOf(ms); 407 this.source = source; 408 this.targets = Set.copyOf(targets); 409 } 410 411 private Exports(Set<Modifier> ms, 412 String source, 413 Set<String> targets, 414 boolean unused) { 415 this.mods = ms; 416 this.source = source; 417 this.targets = targets; 418 } 419 420 /** 421 * Returns the set of modifiers. 422 * 423 * @return A possibly-empty unmodifiable set of modifiers 424 */ 425 public Set<Modifier> modifiers() { 426 return mods; 427 } 428 429 /** 430 * Returns {@code true} if this is a qualified export. 431 * 432 * @return {@code true} if this is a qualified export 433 */ 434 public boolean isQualified() { 435 return !targets.isEmpty(); 436 } 437 438 /** 439 * Returns the package name. 440 * 441 * @return The package name 442 */ 443 public String source() { 444 return source; 445 } 446 447 /** 448 * For a qualified export, returns the non-empty and immutable set 449 * of the module names to which the package is exported. For an 450 * unqualified export, returns an empty set. 451 * 452 * @return The set of target module names or for an unqualified 453 * export, an empty set 454 */ 455 public Set<String> targets() { 456 return targets; 457 } 458 459 /** 460 * Compares this module export to another. 461 * 462 * <p> Two {@code Exports} objects are compared by comparing the package 463 * names lexicographically. Where the packages names are equal then the 464 * sets of modifiers are compared in the same way that module modifiers 465 * are compared (see {@link ModuleDescriptor#compareTo 466 * ModuleDescriptor.compareTo}). Where the package names are equal and 467 * the set of modifiers are equal then the set of target modules are 468 * compared. This is done by sorting the names of the target modules 469 * in ascending order, and according to their natural ordering, and then 470 * comparing the corresponding elements lexicographically. Where the 471 * sets differ in size, and the larger set contains all elements of the 472 * smaller set, then the larger set is considered to succeed the smaller 473 * set. </p> 474 * 475 * @param that 476 * The module export to compare 477 * 478 * @return A negative integer, zero, or a positive integer if this module 479 * export is less than, equal to, or greater than the given 480 * export dependence 481 */ 482 @Override 483 public int compareTo(Exports that) { 484 if (this == that) return 0; 485 486 int c = source.compareTo(that.source); 487 if (c != 0) 488 return c; 489 490 // modifiers 491 long v1 = modsValue(this.modifiers()); 492 long v2 = modsValue(that.modifiers()); 493 c = Long.compare(v1, v2); 494 if (c != 0) 495 return c; 496 497 // targets 498 c = compare(targets, that.targets); 499 if (c != 0) 500 return c; 501 502 return 0; 503 } 504 505 /** 506 * Computes a hash code for this module export. 507 * 508 * <p> The hash code is based upon the modifiers, the package name, 509 * and for a qualified export, the set of modules names to which the 510 * package is exported. It satisfies the general contract of the 511 * {@link Object#hashCode Object.hashCode} method. 512 * 513 * @return The hash-code value for this module export 514 */ 515 @Override 516 public int hashCode() { 517 int hash = mods.hashCode(); 518 hash = hash * 43 + source.hashCode(); 519 return hash * 43 + targets.hashCode(); 520 } 521 522 /** 523 * Tests this module export for equality with the given object. 524 * 525 * <p> If the given object is not an {@code Exports} then this method 526 * returns {@code false}. Two module exports objects are equal if their 527 * set of modifiers is equal, the package names are equal and the set 528 * of target module names is equal. </p> 529 * 530 * <p> This method satisfies the general contract of the {@link 531 * java.lang.Object#equals(Object) Object.equals} method. </p> 532 * 533 * @param ob 534 * the object to which this object is to be compared 535 * 536 * @return {@code true} if, and only if, the given object is a module 537 * dependence that is equal to this module dependence 538 */ 539 @Override 540 public boolean equals(Object ob) { 541 if (!(ob instanceof Exports)) 542 return false; 543 Exports other = (Exports)ob; 544 return Objects.equals(this.mods, other.mods) 545 && Objects.equals(this.source, other.source) 546 && Objects.equals(this.targets, other.targets); 547 } 548 549 /** 550 * Returns a string describing the exported package. 551 * 552 * @return A string describing the exported package 553 */ 554 @Override 555 public String toString() { 556 String s = ModuleDescriptor.toString(mods, source); 557 if (targets.isEmpty()) 558 return s; 559 else 560 return s + " to " + targets; 561 } 562 } 563 564 565 /** 566 * <p> A package opened by a module, may be qualified or unqualified. </p> 567 * 568 * <p> The <em>opens</em> directive in a module declaration declares a 569 * package to be open to allow all types in the package, and all their 570 * members, not just public types and their public members to be reflected 571 * on by APIs that support private access or a way to bypass or suppress 572 * default Java language access control checks. </p> 573 * 574 * @see ModuleDescriptor#opens() 575 * @since 9 576 * @spec JPMS 577 */ 578 579 public final static class Opens 580 implements Comparable<Opens> 581 { 582 /** 583 * A modifier on an open package. 584 * 585 * @see Opens#modifiers() 586 * @since 9 587 * @spec JPMS 588 */ 589 public enum Modifier { 590 591 /** 592 * The open package was not explicitly or implicitly declared in 593 * the source of the module declaration. 594 */ 595 SYNTHETIC, 596 597 /** 598 * The open package was implicitly declared in the source of the 599 * module declaration. 600 */ 601 MANDATED; 602 603 } 604 605 private final Set<Modifier> mods; 606 private final String source; 607 private final Set<String> targets; // empty if unqualified export 608 609 /** 610 * Constructs an {@code Opens}. 611 */ 612 private Opens(Set<Modifier> ms, String source, Set<String> targets) { 613 this.mods = Set.copyOf(ms); 614 this.source = source; 615 this.targets = Set.copyOf(targets); 616 } 617 618 private Opens(Set<Modifier> ms, 619 String source, 620 Set<String> targets, 621 boolean unused) { 622 this.mods = ms; 623 this.source = source; 624 this.targets = targets; 625 } 626 627 /** 628 * Returns the set of modifiers. 629 * 630 * @return A possibly-empty unmodifiable set of modifiers 631 */ 632 public Set<Modifier> modifiers() { 633 return mods; 634 } 635 636 /** 637 * Returns {@code true} if this is a qualified {@code Opens}. 638 * 639 * @return {@code true} if this is a qualified {@code Opens} 640 */ 641 public boolean isQualified() { 642 return !targets.isEmpty(); 643 } 644 645 /** 646 * Returns the package name. 647 * 648 * @return The package name 649 */ 650 public String source() { 651 return source; 652 } 653 654 /** 655 * For a qualified {@code Opens}, returns the non-empty and immutable set 656 * of the module names to which the package is open. For an 657 * unqualified {@code Opens}, returns an empty set. 658 * 659 * @return The set of target module names or for an unqualified 660 * {@code Opens}, an empty set 661 */ 662 public Set<String> targets() { 663 return targets; 664 } 665 666 /** 667 * Compares this module {@code Opens} to another. 668 * 669 * <p> Two {@code Opens} objects are compared by comparing the package 670 * names lexicographically. Where the packages names are equal then the 671 * sets of modifiers are compared in the same way that module modifiers 672 * are compared (see {@link ModuleDescriptor#compareTo 673 * ModuleDescriptor.compareTo}). Where the package names are equal and 674 * the set of modifiers are equal then the set of target modules are 675 * compared. This is done by sorting the names of the target modules 676 * in ascending order, and according to their natural ordering, and then 677 * comparing the corresponding elements lexicographically. Where the 678 * sets differ in size, and the larger set contains all elements of the 679 * smaller set, then the larger set is considered to succeed the smaller 680 * set. </p> 681 * 682 * @param that 683 * The module {@code Opens} to compare 684 * 685 * @return A negative integer, zero, or a positive integer if this module 686 * {@code Opens} is less than, equal to, or greater than the given 687 * module {@code Opens} 688 */ 689 @Override 690 public int compareTo(Opens that) { 691 if (this == that) return 0; 692 693 int c = source.compareTo(that.source); 694 if (c != 0) 695 return c; 696 697 // modifiers 698 long v1 = modsValue(this.modifiers()); 699 long v2 = modsValue(that.modifiers()); 700 c = Long.compare(v1, v2); 701 if (c != 0) 702 return c; 703 704 // targets 705 c = compare(targets, that.targets); 706 if (c != 0) 707 return c; 708 709 return 0; 710 } 711 712 /** 713 * Computes a hash code for this module {@code Opens}. 714 * 715 * <p> The hash code is based upon the modifiers, the package name, 716 * and for a qualified {@code Opens}, the set of modules names to which the 717 * package is opened. It satisfies the general contract of the 718 * {@link Object#hashCode Object.hashCode} method. 719 * 720 * @return The hash-code value for this module {@code Opens} 721 */ 722 @Override 723 public int hashCode() { 724 int hash = mods.hashCode(); 725 hash = hash * 43 + source.hashCode(); 726 return hash * 43 + targets.hashCode(); 727 } 728 729 /** 730 * Tests this module {@code Opens} for equality with the given object. 731 * 732 * <p> If the given object is not an {@code Opens} then this method 733 * returns {@code false}. Two {@code Opens} objects are equal if their 734 * set of modifiers is equal, the package names are equal and the set 735 * of target module names is equal. </p> 736 * 737 * <p> This method satisfies the general contract of the {@link 738 * java.lang.Object#equals(Object) Object.equals} method. </p> 739 * 740 * @param ob 741 * the object to which this object is to be compared 742 * 743 * @return {@code true} if, and only if, the given object is a module 744 * dependence that is equal to this module dependence 745 */ 746 @Override 747 public boolean equals(Object ob) { 748 if (!(ob instanceof Opens)) 749 return false; 750 Opens other = (Opens)ob; 751 return Objects.equals(this.mods, other.mods) 752 && Objects.equals(this.source, other.source) 753 && Objects.equals(this.targets, other.targets); 754 } 755 756 /** 757 * Returns a string describing the open package. 758 * 759 * @return A string describing the open package 760 */ 761 @Override 762 public String toString() { 763 String s = ModuleDescriptor.toString(mods, source); 764 if (targets.isEmpty()) 765 return s; 766 else 767 return s + " to " + targets; 768 } 769 } 770 771 772 /** 773 * <p> A service that a module provides one or more implementations of. </p> 774 * 775 * @see ModuleDescriptor#provides() 776 * @since 9 777 * @spec JPMS 778 */ 779 780 public final static class Provides 781 implements Comparable<Provides> 782 { 783 private final String service; 784 private final List<String> providers; 785 786 private Provides(String service, List<String> providers) { 787 this.service = service; 788 this.providers = List.copyOf(providers); 789 } 790 791 private Provides(String service, List<String> providers, boolean unused) { 792 this.service = service; 793 this.providers = providers; 794 } 795 796 /** 797 * Returns the fully qualified class name of the service type. 798 * 799 * @return The fully qualified class name of the service type 800 */ 801 public String service() { return service; } 802 803 /** 804 * Returns the list of the fully qualified class names of the providers 805 * or provider factories. 806 * 807 * @return A non-empty and unmodifiable list of the fully qualified class 808 * names of the providers or provider factories 809 */ 810 public List<String> providers() { return providers; } 811 812 /** 813 * Compares this {@code Provides} to another. 814 * 815 * <p> Two {@code Provides} objects are compared by comparing the fully 816 * qualified class name of the service type lexicographically. Where the 817 * class names are equal then the list of the provider class names are 818 * compared by comparing the corresponding elements of both lists 819 * lexicographically and in sequence. Where the lists differ in size, 820 * {@code N} is the size of the shorter list, and the first {@code N} 821 * corresponding elements are equal, then the longer list is considered 822 * to succeed the shorter list. </p> 823 * 824 * @param that 825 * The {@code Provides} to compare 826 * 827 * @return A negative integer, zero, or a positive integer if this 828 * {@code Provides} is less than, equal to, or greater than 829 * the given {@code Provides} 830 */ 831 public int compareTo(Provides that) { 832 if (this == that) return 0; 833 834 int c = service.compareTo(that.service); 835 if (c != 0) return c; 836 837 // compare provider class names in sequence 838 int size1 = this.providers.size(); 839 int size2 = that.providers.size(); 840 for (int index=0; index<Math.min(size1, size2); index++) { 841 String e1 = this.providers.get(index); 842 String e2 = that.providers.get(index); 843 c = e1.compareTo(e2); 844 if (c != 0) return c; 845 } 846 if (size1 == size2) { 847 return 0; 848 } else { 849 return (size1 > size2) ? 1 : -1; 850 } 851 } 852 853 /** 854 * Computes a hash code for this {@code Provides}. 855 * 856 * <p> The hash code is based upon the service type and the set of 857 * providers. It satisfies the general contract of the {@link 858 * Object#hashCode Object.hashCode} method. </p> 859 * 860 * @return The hash-code value for this module provides 861 */ 862 @Override 863 public int hashCode() { 864 return service.hashCode() * 43 + providers.hashCode(); 865 } 866 867 /** 868 * Tests this {@code Provides} for equality with the given object. 869 * 870 * <p> If the given object is not a {@code Provides} then this method 871 * returns {@code false}. Two {@code Provides} objects are equal if the 872 * service type is equal and the list of providers is equal. </p> 873 * 874 * <p> This method satisfies the general contract of the {@link 875 * java.lang.Object#equals(Object) Object.equals} method. </p> 876 * 877 * @param ob 878 * the object to which this object is to be compared 879 * 880 * @return {@code true} if, and only if, the given object is a 881 * {@code Provides} that is equal to this {@code Provides} 882 */ 883 @Override 884 public boolean equals(Object ob) { 885 if (!(ob instanceof Provides)) 886 return false; 887 Provides other = (Provides)ob; 888 return Objects.equals(this.service, other.service) && 889 Objects.equals(this.providers, other.providers); 890 } 891 892 /** 893 * Returns a string describing this {@code Provides}. 894 * 895 * @return A string describing this {@code Provides} 896 */ 897 @Override 898 public String toString() { 899 return service + " with " + providers; 900 } 901 902 } 903 904 905 906 /** 907 * A module's version string. 908 * 909 * <p> A version string has three components: The version number itself, an 910 * optional pre-release version, and an optional build version. Each 911 * component is a sequence of tokens; each token is either a non-negative 912 * integer or a string. Tokens are separated by the punctuation characters 913 * {@code '.'}, {@code '-'}, or {@code '+'}, or by transitions from a 914 * sequence of digits to a sequence of characters that are neither digits 915 * nor punctuation characters, or vice versa. 916 * 917 * <ul> 918 * 919 * <li> The <i>version number</i> is a sequence of tokens separated by 920 * {@code '.'} characters, terminated by the first {@code '-'} or {@code 921 * '+'} character. </li> 922 * 923 * <li> The <i>pre-release version</i> is a sequence of tokens separated 924 * by {@code '.'} or {@code '-'} characters, terminated by the first 925 * {@code '+'} character. </li> 926 * 927 * <li> The <i>build version</i> is a sequence of tokens separated by 928 * {@code '.'}, {@code '-'}, or {@code '+'} characters. 929 * 930 * </ul> 931 * 932 * <p> When comparing two version strings, the elements of their 933 * corresponding components are compared in pointwise fashion. If one 934 * component is longer than the other, but otherwise equal to it, then the 935 * first component is considered the greater of the two; otherwise, if two 936 * corresponding elements are integers then they are compared as such; 937 * otherwise, at least one of the elements is a string, so the other is 938 * converted into a string if it is an integer and the two are compared 939 * lexicographically. Trailing integer elements with the value zero are 940 * ignored. 941 * 942 * <p> Given two version strings, if their version numbers differ then the 943 * result of comparing them is the result of comparing their version 944 * numbers; otherwise, if one of them has a pre-release version but the 945 * other does not then the first is considered to precede the second, 946 * otherwise the result of comparing them is the result of comparing their 947 * pre-release versions; otherwise, the result of comparing them is the 948 * result of comparing their build versions. 949 * 950 * @see ModuleDescriptor#version() 951 * @since 9 952 * @spec JPMS 953 */ 954 955 public final static class Version 956 implements Comparable<Version> 957 { 958 959 private final String version; 960 961 // If Java had disjunctive types then we'd write List<Integer|String> here 962 // 963 private final List<Object> sequence; 964 private final List<Object> pre; 965 private final List<Object> build; 966 967 // Take a numeric token starting at position i 968 // Append it to the given list 969 // Return the index of the first character not taken 970 // Requires: s.charAt(i) is (decimal) numeric 971 // 972 private static int takeNumber(String s, int i, List<Object> acc) { 973 char c = s.charAt(i); 974 int d = (c - '0'); 975 int n = s.length(); 976 while (++i < n) { 977 c = s.charAt(i); 978 if (c >= '0' && c <= '9') { 979 d = d * 10 + (c - '0'); 980 continue; 981 } 982 break; 983 } 984 acc.add(d); 985 return i; 986 } 987 988 // Take a string token starting at position i 989 // Append it to the given list 990 // Return the index of the first character not taken 991 // Requires: s.charAt(i) is not '.' 992 // 993 private static int takeString(String s, int i, List<Object> acc) { 994 int b = i; 995 int n = s.length(); 996 while (++i < n) { 997 char c = s.charAt(i); 998 if (c != '.' && c != '-' && c != '+' && !(c >= '0' && c <= '9')) 999 continue; 1000 break; 1001 } 1002 acc.add(s.substring(b, i)); 1003 return i; 1004 } 1005 1006 // Syntax: tok+ ( '-' tok+)? ( '+' tok+)? 1007 // First token string is sequence, second is pre, third is build 1008 // Tokens are separated by '.' or '-', or by changes between alpha & numeric 1009 // Numeric tokens are compared as decimal integers 1010 // Non-numeric tokens are compared lexicographically 1011 // A version with a non-empty pre is less than a version with same seq but no pre 1012 // Tokens in build may contain '-' and '+' 1013 // 1014 private Version(String v) { 1015 1016 if (v == null) 1017 throw new IllegalArgumentException("Null version string"); 1018 int n = v.length(); 1019 if (n == 0) 1020 throw new IllegalArgumentException("Empty version string"); 1021 1022 int i = 0; 1023 char c = v.charAt(i); 1024 if (!(c >= '0' && c <= '9')) 1025 throw new IllegalArgumentException(v 1026 + ": Version string does not start" 1027 + " with a number"); 1028 1029 List<Object> sequence = new ArrayList<>(4); 1030 List<Object> pre = new ArrayList<>(2); 1031 List<Object> build = new ArrayList<>(2); 1032 1033 i = takeNumber(v, i, sequence); 1034 1035 while (i < n) { 1036 c = v.charAt(i); 1037 if (c == '.') { 1038 i++; 1039 continue; 1040 } 1041 if (c == '-' || c == '+') { 1042 i++; 1043 break; 1044 } 1045 if (c >= '0' && c <= '9') 1046 i = takeNumber(v, i, sequence); 1047 else 1048 i = takeString(v, i, sequence); 1049 } 1050 1051 if (c == '-' && i >= n) 1052 throw new IllegalArgumentException(v + ": Empty pre-release"); 1053 1054 while (i < n) { 1055 c = v.charAt(i); 1056 if (c >= '0' && c <= '9') 1057 i = takeNumber(v, i, pre); 1058 else 1059 i = takeString(v, i, pre); 1060 if (i >= n) 1061 break; 1062 c = v.charAt(i); 1063 if (c == '.' || c == '-') { 1064 i++; 1065 continue; 1066 } 1067 if (c == '+') { 1068 i++; 1069 break; 1070 } 1071 } 1072 1073 if (c == '+' && i >= n) 1074 throw new IllegalArgumentException(v + ": Empty pre-release"); 1075 1076 while (i < n) { 1077 c = v.charAt(i); 1078 if (c >= '0' && c <= '9') 1079 i = takeNumber(v, i, build); 1080 else 1081 i = takeString(v, i, build); 1082 if (i >= n) 1083 break; 1084 c = v.charAt(i); 1085 if (c == '.' || c == '-' || c == '+') { 1086 i++; 1087 continue; 1088 } 1089 } 1090 1091 this.version = v; 1092 this.sequence = sequence; 1093 this.pre = pre; 1094 this.build = build; 1095 } 1096 1097 /** 1098 * Parses the given string as a version string. 1099 * 1100 * @param v 1101 * The string to parse 1102 * 1103 * @return The resulting {@code Version} 1104 * 1105 * @throws IllegalArgumentException 1106 * If {@code v} is {@code null}, an empty string, or cannot be 1107 * parsed as a version string 1108 */ 1109 public static Version parse(String v) { 1110 return new Version(v); 1111 } 1112 1113 @SuppressWarnings("unchecked") 1114 private int cmp(Object o1, Object o2) { 1115 return ((Comparable)o1).compareTo(o2); 1116 } 1117 1118 private int compareTokens(List<Object> ts1, List<Object> ts2) { 1119 int n = Math.min(ts1.size(), ts2.size()); 1120 for (int i = 0; i < n; i++) { 1121 Object o1 = ts1.get(i); 1122 Object o2 = ts2.get(i); 1123 if ((o1 instanceof Integer && o2 instanceof Integer) 1124 || (o1 instanceof String && o2 instanceof String)) 1125 { 1126 int c = cmp(o1, o2); 1127 if (c == 0) 1128 continue; 1129 return c; 1130 } 1131 // Types differ, so convert number to string form 1132 int c = o1.toString().compareTo(o2.toString()); 1133 if (c == 0) 1134 continue; 1135 return c; 1136 } 1137 List<Object> rest = ts1.size() > ts2.size() ? ts1 : ts2; 1138 int e = rest.size(); 1139 for (int i = n; i < e; i++) { 1140 Object o = rest.get(i); 1141 if (o instanceof Integer && ((Integer)o) == 0) 1142 continue; 1143 return ts1.size() - ts2.size(); 1144 } 1145 return 0; 1146 } 1147 1148 /** 1149 * Compares this module version to another module version. Module 1150 * versions are compared as described in the class description. 1151 * 1152 * @param that 1153 * The module version to compare 1154 * 1155 * @return A negative integer, zero, or a positive integer as this 1156 * module version is less than, equal to, or greater than the 1157 * given module version 1158 */ 1159 @Override 1160 public int compareTo(Version that) { 1161 int c = compareTokens(this.sequence, that.sequence); 1162 if (c != 0) return c; 1163 if (this.pre.isEmpty()) { 1164 if (!that.pre.isEmpty()) return +1; 1165 } else { 1166 if (that.pre.isEmpty()) return -1; 1167 } 1168 c = compareTokens(this.pre, that.pre); 1169 if (c != 0) return c; 1170 return compareTokens(this.build, that.build); 1171 } 1172 1173 /** 1174 * Tests this module version for equality with the given object. 1175 * 1176 * <p> If the given object is not a {@code Version} then this method 1177 * returns {@code false}. Two module version are equal if their 1178 * corresponding components are equal. </p> 1179 * 1180 * <p> This method satisfies the general contract of the {@link 1181 * java.lang.Object#equals(Object) Object.equals} method. </p> 1182 * 1183 * @param ob 1184 * the object to which this object is to be compared 1185 * 1186 * @return {@code true} if, and only if, the given object is a module 1187 * reference that is equal to this module reference 1188 */ 1189 @Override 1190 public boolean equals(Object ob) { 1191 if (!(ob instanceof Version)) 1192 return false; 1193 return compareTo((Version)ob) == 0; 1194 } 1195 1196 /** 1197 * Computes a hash code for this module version. 1198 * 1199 * <p> The hash code is based upon the components of the version and 1200 * satisfies the general contract of the {@link Object#hashCode 1201 * Object.hashCode} method. </p> 1202 * 1203 * @return The hash-code value for this module version 1204 */ 1205 @Override 1206 public int hashCode() { 1207 return version.hashCode(); 1208 } 1209 1210 /** 1211 * Returns the string from which this version was parsed. 1212 * 1213 * @return The string from which this version was parsed. 1214 */ 1215 @Override 1216 public String toString() { 1217 return version; 1218 } 1219 1220 } 1221 1222 1223 private final String name; 1224 private final Version version; 1225 private final String rawVersionString; 1226 private final Set<Modifier> modifiers; 1227 private final boolean open; // true if modifiers contains OPEN 1228 private final boolean automatic; // true if modifiers contains AUTOMATIC 1229 private final Set<Requires> requires; 1230 private final Set<Exports> exports; 1231 private final Set<Opens> opens; 1232 private final Set<String> uses; 1233 private final Set<Provides> provides; 1234 private final Set<String> packages; 1235 private final String mainClass; 1236 1237 private ModuleDescriptor(String name, 1238 Version version, 1239 String rawVersionString, 1240 Set<Modifier> modifiers, 1241 Set<Requires> requires, 1242 Set<Exports> exports, 1243 Set<Opens> opens, 1244 Set<String> uses, 1245 Set<Provides> provides, 1246 Set<String> packages, 1247 String mainClass) 1248 { 1249 assert version == null || rawVersionString == null; 1250 this.name = name; 1251 this.version = version; 1252 this.rawVersionString = rawVersionString; 1253 this.modifiers = Set.copyOf(modifiers); 1254 this.open = modifiers.contains(Modifier.OPEN); 1255 this.automatic = modifiers.contains(Modifier.AUTOMATIC); 1256 assert (requires.stream().map(Requires::name).distinct().count() 1257 == requires.size()); 1258 this.requires = Set.copyOf(requires); 1259 this.exports = Set.copyOf(exports); 1260 this.opens = Set.copyOf(opens); 1261 this.uses = Set.copyOf(uses); 1262 this.provides = Set.copyOf(provides); 1263 1264 this.packages = Set.copyOf(packages); 1265 this.mainClass = mainClass; 1266 } 1267 1268 /** 1269 * Creates a module descriptor from its components. 1270 * The arguments are pre-validated and sets are unmodifiable sets. 1271 */ 1272 ModuleDescriptor(String name, 1273 Version version, 1274 Set<Modifier> modifiers, 1275 Set<Requires> requires, 1276 Set<Exports> exports, 1277 Set<Opens> opens, 1278 Set<String> uses, 1279 Set<Provides> provides, 1280 Set<String> packages, 1281 String mainClass, 1282 int hashCode, 1283 boolean unused) { 1284 this.name = name; 1285 this.version = version; 1286 this.rawVersionString = null; 1287 this.modifiers = modifiers; 1288 this.open = modifiers.contains(Modifier.OPEN); 1289 this.automatic = modifiers.contains(Modifier.AUTOMATIC); 1290 this.requires = requires; 1291 this.exports = exports; 1292 this.opens = opens; 1293 this.uses = uses; 1294 this.provides = provides; 1295 this.packages = packages; 1296 this.mainClass = mainClass; 1297 this.hash = hashCode; 1298 } 1299 1300 /** 1301 * <p> Returns the module name. </p> 1302 * 1303 * @return The module name 1304 */ 1305 public String name() { 1306 return name; 1307 } 1308 1309 /** 1310 * <p> Returns the set of module modifiers. </p> 1311 * 1312 * @return A possibly-empty unmodifiable set of modifiers 1313 */ 1314 public Set<Modifier> modifiers() { 1315 return modifiers; 1316 } 1317 1318 /** 1319 * <p> Returns {@code true} if this is an open module. </p> 1320 * 1321 * <p> This method is equivalent to testing if the set of {@link #modifiers() 1322 * modifiers} contains the {@link Modifier#OPEN OPEN} modifier. </p> 1323 * 1324 * @return {@code true} if this is an open module 1325 */ 1326 public boolean isOpen() { 1327 return open; 1328 } 1329 1330 /** 1331 * <p> Returns {@code true} if this is an automatic module. </p> 1332 * 1333 * <p> This method is equivalent to testing if the set of {@link #modifiers() 1334 * modifiers} contains the {@link Modifier#OPEN AUTOMATIC} modifier. </p> 1335 * 1336 * @return {@code true} if this is an automatic module 1337 */ 1338 public boolean isAutomatic() { 1339 return automatic; 1340 } 1341 1342 /** 1343 * <p> Returns the set of {@code Requires} objects representing the module 1344 * dependences. </p> 1345 * 1346 * <p> The set includes a dependency on "{@code java.base}" when this 1347 * module is not named "{@code java.base}". If this module is an automatic 1348 * module then it does not have a dependency on any module other than 1349 * "{@code java.base}". </p> 1350 * 1351 * @return A possibly-empty unmodifiable set of {@link Requires} objects 1352 */ 1353 public Set<Requires> requires() { 1354 return requires; 1355 } 1356 1357 /** 1358 * <p> Returns the set of {@code Exports} objects representing the exported 1359 * packages. </p> 1360 * 1361 * <p> If this module is an automatic module then the set of exports 1362 * is empty. </p> 1363 * 1364 * @return A possibly-empty unmodifiable set of exported packages 1365 */ 1366 public Set<Exports> exports() { 1367 return exports; 1368 } 1369 1370 /** 1371 * <p> Returns the set of {@code Opens} objects representing the open 1372 * packages. </p> 1373 * 1374 * <p> If this module is an open module or an automatic module then the 1375 * set of open packages is empty. </p> 1376 * 1377 * @return A possibly-empty unmodifiable set of open packages 1378 */ 1379 public Set<Opens> opens() { 1380 return opens; 1381 } 1382 1383 /** 1384 * <p> Returns the set of service dependences. </p> 1385 * 1386 * <p> If this module is an automatic module then the set of service 1387 * dependences is empty. </p> 1388 * 1389 * @return A possibly-empty unmodifiable set of the fully qualified class 1390 * names of the service types used 1391 */ 1392 public Set<String> uses() { 1393 return uses; 1394 } 1395 1396 /** 1397 * <p> Returns the set of {@code Provides} objects representing the 1398 * services that the module provides. </p> 1399 * 1400 * @return The possibly-empty unmodifiable set of the services that this 1401 * module provides 1402 */ 1403 public Set<Provides> provides() { 1404 return provides; 1405 } 1406 1407 /** 1408 * <p> Returns the module version. </p> 1409 * 1410 * @return This module's version, or an empty {@code Optional} if the 1411 * module does not have a version or the version is 1412 * {@linkplain Version#parse(String) unparseable} 1413 */ 1414 public Optional<Version> version() { 1415 return Optional.ofNullable(version); 1416 } 1417 1418 /** 1419 * <p> Returns the string with the possibly-unparseable version of the 1420 * module. </p> 1421 * 1422 * @return The string containing the version of the module or an empty 1423 * {@code Optional} if the module does not have a version 1424 * 1425 * @see #version() 1426 */ 1427 public Optional<String> rawVersion() { 1428 if (version != null) { 1429 return Optional.of(version.toString()); 1430 } else { 1431 return Optional.ofNullable(rawVersionString); 1432 } 1433 } 1434 1435 /** 1436 * <p> Returns a string containing the module name and, if present, its 1437 * version. </p> 1438 * 1439 * @return A string containing the module name and, if present, its 1440 * version 1441 */ 1442 public String toNameAndVersion() { 1443 if (version != null) { 1444 return name() + "@" + version; 1445 } else { 1446 return name(); 1447 } 1448 } 1449 1450 /** 1451 * <p> Returns the module main class. </p> 1452 * 1453 * @return The fully qualified class name of the module's main class 1454 */ 1455 public Optional<String> mainClass() { 1456 return Optional.ofNullable(mainClass); 1457 } 1458 1459 /** 1460 * Returns the set of packages in the module. 1461 * 1462 * <p> The set of packages includes all exported and open packages, as well 1463 * as the packages of any service providers, and the package for the main 1464 * class. </p> 1465 * 1466 * @return A possibly-empty unmodifiable set of the packages in the module 1467 */ 1468 public Set<String> packages() { 1469 return packages; 1470 } 1471 1472 1473 /** 1474 * A builder for building {@link ModuleDescriptor} objects. 1475 * 1476 * <p> {@code ModuleDescriptor} defines the {@link #newModule newModule}, 1477 * {@link #newOpenModule newOpenModule}, and {@link #newAutomaticModule 1478 * newAutomaticModule} methods to create builders for building 1479 * <em>normal</em>, open, and automatic modules. </p> 1480 * 1481 * <p> The set of packages in the module are accumulated by the {@code 1482 * Builder} as the {@link ModuleDescriptor.Builder#exports(String) exports}, 1483 * {@link ModuleDescriptor.Builder#opens(String) opens}, 1484 * {@link ModuleDescriptor.Builder#packages(Set) packages}, 1485 * {@link ModuleDescriptor.Builder#provides(String,List) provides}, and 1486 * {@link ModuleDescriptor.Builder#mainClass(String) mainClass} methods are 1487 * invoked. </p> 1488 * 1489 * <p> The module names, package names, and class names that are parameters 1490 * specified to the builder methods are the module names, package names, 1491 * and qualified names of classes (in named packages) as defined in the 1492 * <cite>The Java™ Language Specification</cite>. </p> 1493 * 1494 * <p> Example usage: </p> 1495 * <pre>{@code ModuleDescriptor descriptor = ModuleDescriptor.newModule("stats.core") 1496 * .requires("java.base") 1497 * .exports("org.acme.stats.core.clustering") 1498 * .exports("org.acme.stats.core.regression") 1499 * .packages(Set.of("org.acme.stats.core.internal")) 1500 * .build(); 1501 * }</pre> 1502 * 1503 * @apiNote A {@code Builder} checks the components and invariants as 1504 * components are added to the builder. The rationale for this is to detect 1505 * errors as early as possible and not defer all validation to the 1506 * {@link #build build} method. 1507 * 1508 * @since 9 1509 * @spec JPMS 1510 */ 1511 public static final class Builder { 1512 final String name; 1513 final boolean strict; 1514 final Set<Modifier> modifiers; 1515 final boolean open; 1516 final boolean automatic; 1517 final Set<String> packages = new HashSet<>(); 1518 final Map<String, Requires> requires = new HashMap<>(); 1519 final Map<String, Exports> exports = new HashMap<>(); 1520 final Map<String, Opens> opens = new HashMap<>(); 1521 final Set<String> uses = new HashSet<>(); 1522 final Map<String, Provides> provides = new HashMap<>(); 1523 Version version; 1524 String rawVersionString; 1525 String mainClass; 1526 1527 /** 1528 * Initializes a new builder with the given module name. 1529 * 1530 * If {@code strict} is {@code true} then module, package, and class 1531 * names are checked to ensure they are legal names. In addition, the 1532 * {@link #build buid} method will add "{@code requires java.base}" if 1533 * the dependency is not declared. 1534 */ 1535 Builder(String name, boolean strict, Set<Modifier> modifiers) { 1536 this.name = (strict) ? requireModuleName(name) : name; 1537 this.strict = strict; 1538 this.modifiers = modifiers; 1539 this.open = modifiers.contains(Modifier.OPEN); 1540 this.automatic = modifiers.contains(Modifier.AUTOMATIC); 1541 assert !open || !automatic; 1542 } 1543 1544 /** 1545 * Returns a snapshot of the packages in the module. 1546 */ 1547 /* package */ Set<String> packages() { 1548 return Collections.unmodifiableSet(packages); 1549 } 1550 1551 /** 1552 * Adds a dependence on a module. 1553 * 1554 * @param req 1555 * The dependence 1556 * 1557 * @return This builder 1558 * 1559 * @throws IllegalArgumentException 1560 * If the dependence is on the module that this builder was 1561 * initialized to build 1562 * @throws IllegalStateException 1563 * If the dependence on the module has already been declared 1564 * or this builder is for an automatic module 1565 */ 1566 public Builder requires(Requires req) { 1567 if (automatic) 1568 throw new IllegalStateException("Automatic modules cannot declare" 1569 + " dependences"); 1570 String mn = req.name(); 1571 if (name.equals(mn)) 1572 throw new IllegalArgumentException("Dependence on self"); 1573 if (requires.containsKey(mn)) 1574 throw new IllegalStateException("Dependence upon " + mn 1575 + " already declared"); 1576 requires.put(mn, req); 1577 return this; 1578 } 1579 1580 /** 1581 * Adds a dependence on a module with the given (and possibly empty) 1582 * set of modifiers. The dependence includes the version of the 1583 * module that was recorded at compile-time. 1584 * 1585 * @param ms 1586 * The set of modifiers 1587 * @param mn 1588 * The module name 1589 * @param compiledVersion 1590 * The version of the module recorded at compile-time 1591 * 1592 * @return This builder 1593 * 1594 * @throws IllegalArgumentException 1595 * If the module name is {@code null}, is not a legal module 1596 * name, or is equal to the module name that this builder 1597 * was initialized to build 1598 * @throws IllegalStateException 1599 * If the dependence on the module has already been declared 1600 * or this builder is for an automatic module 1601 */ 1602 public Builder requires(Set<Requires.Modifier> ms, 1603 String mn, 1604 Version compiledVersion) { 1605 Objects.requireNonNull(compiledVersion); 1606 if (strict) 1607 mn = requireModuleName(mn); 1608 return requires(new Requires(ms, mn, compiledVersion, null)); 1609 } 1610 1611 /* package */Builder requires(Set<Requires.Modifier> ms, 1612 String mn, 1613 String rawCompiledVersion) { 1614 Requires r; 1615 try { 1616 Version v = Version.parse(rawCompiledVersion); 1617 r = new Requires(ms, mn, v, null); 1618 } catch (IllegalArgumentException e) { 1619 if (strict) throw e; 1620 r = new Requires(ms, mn, null, rawCompiledVersion); 1621 } 1622 return requires(r); 1623 } 1624 1625 /** 1626 * Adds a dependence on a module with the given (and possibly empty) 1627 * set of modifiers. 1628 * 1629 * @param ms 1630 * The set of modifiers 1631 * @param mn 1632 * The module name 1633 * 1634 * @return This builder 1635 * 1636 * @throws IllegalArgumentException 1637 * If the module name is {@code null}, is not a legal module 1638 * name, or is equal to the module name that this builder 1639 * was initialized to build 1640 * @throws IllegalStateException 1641 * If the dependence on the module has already been declared 1642 * or this builder is for an automatic module 1643 */ 1644 public Builder requires(Set<Requires.Modifier> ms, String mn) { 1645 if (strict) 1646 mn = requireModuleName(mn); 1647 return requires(new Requires(ms, mn, null, null)); 1648 } 1649 1650 /** 1651 * Adds a dependence on a module with an empty set of modifiers. 1652 * 1653 * @param mn 1654 * The module name 1655 * 1656 * @return This builder 1657 * 1658 * @throws IllegalArgumentException 1659 * If the module name is {@code null}, is not a legal module 1660 * name, or is equal to the module name that this builder 1661 * was initialized to build 1662 * @throws IllegalStateException 1663 * If the dependence on the module has already been declared 1664 * or this builder is for an automatic module 1665 */ 1666 public Builder requires(String mn) { 1667 return requires(EnumSet.noneOf(Requires.Modifier.class), mn); 1668 } 1669 1670 /** 1671 * Adds an exported package. 1672 * 1673 * @param e 1674 * The export 1675 * 1676 * @return This builder 1677 * 1678 * @throws IllegalStateException 1679 * If the {@link Exports#source() package} is already declared as 1680 * exported or this builder is for an automatic module 1681 */ 1682 public Builder exports(Exports e) { 1683 if (automatic) { 1684 throw new IllegalStateException("Automatic modules cannot declare" 1685 + " exported packages"); 1686 } 1687 String source = e.source(); 1688 if (exports.containsKey(source)) { 1689 throw new IllegalStateException("Exported package " + source 1690 + " already declared"); 1691 } 1692 exports.put(source, e); 1693 packages.add(source); 1694 return this; 1695 } 1696 1697 /** 1698 * Adds an exported package with the given (and possibly empty) set of 1699 * modifiers. The package is exported to a set of target modules. 1700 * 1701 * @param ms 1702 * The set of modifiers 1703 * @param pn 1704 * The package name 1705 * @param targets 1706 * The set of target modules names 1707 * 1708 * @return This builder 1709 * 1710 * @throws IllegalArgumentException 1711 * If the package name is {@code null} or is not a legal 1712 * package name, the set of target modules is empty, or the set 1713 * of target modules contains a name that is not a legal module 1714 * name 1715 * @throws IllegalStateException 1716 * If the package is already declared as exported 1717 * or this builder is for an automatic module 1718 */ 1719 public Builder exports(Set<Exports.Modifier> ms, 1720 String pn, 1721 Set<String> targets) 1722 { 1723 targets = new HashSet<>(targets); 1724 if (targets.isEmpty()) 1725 throw new IllegalArgumentException("Empty target set"); 1726 if (strict) { 1727 requirePackageName(pn); 1728 targets.forEach(Checks::requireModuleName); 1729 } 1730 Exports e = new Exports(ms, pn, targets); 1731 return exports(e); 1732 } 1733 1734 /** 1735 * Adds an exported package with the given (and possibly empty) set of 1736 * modifiers. The package is exported to all modules. 1737 * 1738 * @param ms 1739 * The set of modifiers 1740 * @param pn 1741 * The package name 1742 * 1743 * @return This builder 1744 * 1745 * @throws IllegalArgumentException 1746 * If the package name is {@code null} or is not a legal 1747 * package name 1748 * @throws IllegalStateException 1749 * If the package is already declared as exported 1750 * or this builder is for an automatic module 1751 */ 1752 public Builder exports(Set<Exports.Modifier> ms, String pn) { 1753 if (strict) { 1754 requirePackageName(pn); 1755 } 1756 Exports e = new Exports(ms, pn, Set.of()); 1757 return exports(e); 1758 } 1759 1760 /** 1761 * Adds an exported package. The package is exported to a set of target 1762 * modules. 1763 * 1764 * @param pn 1765 * The package name 1766 * @param targets 1767 * The set of target modules names 1768 * 1769 * @return This builder 1770 * 1771 * @throws IllegalArgumentException 1772 * If the package name is {@code null} or is not a legal 1773 * package name, the set of target modules is empty, or the set 1774 * of target modules contains a name that is not a legal module 1775 * name 1776 * @throws IllegalStateException 1777 * If the package is already declared as exported 1778 * or this builder is for an automatic module 1779 */ 1780 public Builder exports(String pn, Set<String> targets) { 1781 return exports(Set.of(), pn, targets); 1782 } 1783 1784 /** 1785 * Adds an exported package. The package is exported to all modules. 1786 * 1787 * @param pn 1788 * The package name 1789 * 1790 * @return This builder 1791 * 1792 * @throws IllegalArgumentException 1793 * If the package name is {@code null} or is not a legal 1794 * package name 1795 * @throws IllegalStateException 1796 * If the package is already declared as exported 1797 * or this builder is for an automatic module 1798 */ 1799 public Builder exports(String pn) { 1800 return exports(Set.of(), pn); 1801 } 1802 1803 /** 1804 * Adds an open package. 1805 * 1806 * @param obj 1807 * The {@code Opens} object 1808 * 1809 * @return This builder 1810 * 1811 * @throws IllegalStateException 1812 * If the package is already declared as open, or this is a 1813 * builder for an open module or automatic module 1814 */ 1815 public Builder opens(Opens obj) { 1816 if (open || automatic) { 1817 throw new IllegalStateException("Open or automatic modules cannot" 1818 + " declare open packages"); 1819 } 1820 String source = obj.source(); 1821 if (opens.containsKey(source)) { 1822 throw new IllegalStateException("Open package " + source 1823 + " already declared"); 1824 } 1825 opens.put(source, obj); 1826 packages.add(source); 1827 return this; 1828 } 1829 1830 1831 /** 1832 * Adds an open package with the given (and possibly empty) set of 1833 * modifiers. The package is open to a set of target modules. 1834 * 1835 * @param ms 1836 * The set of modifiers 1837 * @param pn 1838 * The package name 1839 * @param targets 1840 * The set of target modules names 1841 * 1842 * @return This builder 1843 * 1844 * @throws IllegalArgumentException 1845 * If the package name is {@code null} or is not a legal 1846 * package name, the set of target modules is empty, or the set 1847 * of target modules contains a name that is not a legal module 1848 * name 1849 * @throws IllegalStateException 1850 * If the package is already declared as open, or this is a 1851 * builder for an open module or automatic module 1852 */ 1853 public Builder opens(Set<Opens.Modifier> ms, 1854 String pn, 1855 Set<String> targets) 1856 { 1857 targets = new HashSet<>(targets); 1858 if (targets.isEmpty()) 1859 throw new IllegalArgumentException("Empty target set"); 1860 if (strict) { 1861 requirePackageName(pn); 1862 targets.forEach(Checks::requireModuleName); 1863 } 1864 Opens opens = new Opens(ms, pn, targets); 1865 return opens(opens); 1866 } 1867 1868 /** 1869 * Adds an open package with the given (and possibly empty) set of 1870 * modifiers. The package is open to all modules. 1871 * 1872 * @param ms 1873 * The set of modifiers 1874 * @param pn 1875 * The package name 1876 * 1877 * @return This builder 1878 * 1879 * @throws IllegalArgumentException 1880 * If the package name is {@code null} or is not a legal 1881 * package name 1882 * @throws IllegalStateException 1883 * If the package is already declared as open, or this is a 1884 * builder for an open module or automatic module 1885 */ 1886 public Builder opens(Set<Opens.Modifier> ms, String pn) { 1887 if (strict) { 1888 requirePackageName(pn); 1889 } 1890 Opens e = new Opens(ms, pn, Set.of()); 1891 return opens(e); 1892 } 1893 1894 /** 1895 * Adds an open package. The package is open to a set of target modules. 1896 * 1897 * @param pn 1898 * The package name 1899 * @param targets 1900 * The set of target modules names 1901 * 1902 * @return This builder 1903 * 1904 * @throws IllegalArgumentException 1905 * If the package name is {@code null} or is not a legal 1906 * package name, the set of target modules is empty, or the set 1907 * of target modules contains a name that is not a legal module 1908 * name 1909 * @throws IllegalStateException 1910 * If the package is already declared as open, or this is a 1911 * builder for an open module or automatic module 1912 */ 1913 public Builder opens(String pn, Set<String> targets) { 1914 return opens(Set.of(), pn, targets); 1915 } 1916 1917 /** 1918 * Adds an open package. The package is open to all modules. 1919 * 1920 * @param pn 1921 * The package name 1922 * 1923 * @return This builder 1924 * 1925 * @throws IllegalArgumentException 1926 * If the package name is {@code null} or is not a legal 1927 * package name 1928 * @throws IllegalStateException 1929 * If the package is already declared as open, or this is a 1930 * builder for an open module or automatic module 1931 */ 1932 public Builder opens(String pn) { 1933 return opens(Set.of(), pn); 1934 } 1935 1936 /** 1937 * Adds a service dependence. 1938 * 1939 * @param service 1940 * The service type 1941 * 1942 * @return This builder 1943 * 1944 * @throws IllegalArgumentException 1945 * If the service type is {@code null} or not a qualified name of 1946 * a class in a named package 1947 * @throws IllegalStateException 1948 * If a dependency on the service type has already been declared 1949 * or this is a builder for an automatic module 1950 */ 1951 public Builder uses(String service) { 1952 if (automatic) 1953 throw new IllegalStateException("Automatic modules can not declare" 1954 + " service dependences"); 1955 if (uses.contains(requireServiceTypeName(service))) 1956 throw new IllegalStateException("Dependence upon service " 1957 + service + " already declared"); 1958 uses.add(service); 1959 return this; 1960 } 1961 1962 /** 1963 * Provides a service with one or more implementations. The package for 1964 * each {@link Provides#providers provider} (or provider factory) is 1965 * added to the module if not already added. 1966 * 1967 * @param p 1968 * The provides 1969 * 1970 * @return This builder 1971 * 1972 * @throws IllegalStateException 1973 * If the providers for the service type have already been 1974 * declared 1975 */ 1976 public Builder provides(Provides p) { 1977 String service = p.service(); 1978 if (provides.containsKey(service)) 1979 throw new IllegalStateException("Providers of service " 1980 + service + " already declared"); 1981 provides.put(service, p); 1982 p.providers().forEach(name -> packages.add(packageName(name))); 1983 return this; 1984 } 1985 1986 /** 1987 * Provides implementations of a service. The package for each provider 1988 * (or provider factory) is added to the module if not already added. 1989 * 1990 * @param service 1991 * The service type 1992 * @param providers 1993 * The list of provider or provider factory class names 1994 * 1995 * @return This builder 1996 * 1997 * @throws IllegalArgumentException 1998 * If the service type or any of the provider class names is 1999 * {@code null} or not a qualified name of a class in a named 2000 * package, or the list of provider class names is empty 2001 * @throws IllegalStateException 2002 * If the providers for the service type have already been 2003 * declared 2004 */ 2005 public Builder provides(String service, List<String> providers) { 2006 providers = new ArrayList<>(providers); 2007 if (providers.isEmpty()) 2008 throw new IllegalArgumentException("Empty providers set"); 2009 if (strict) { 2010 requireServiceTypeName(service); 2011 providers.forEach(Checks::requireServiceProviderName); 2012 } else { 2013 // Disallow service/providers in unnamed package 2014 String pn = packageName(service); 2015 if (pn.isEmpty()) { 2016 throw new IllegalArgumentException(service 2017 + ": unnamed package"); 2018 } 2019 for (String name : providers) { 2020 pn = packageName(name); 2021 if (pn.isEmpty()) { 2022 throw new IllegalArgumentException(name 2023 + ": unnamed package"); 2024 } 2025 } 2026 } 2027 Provides p = new Provides(service, providers); 2028 return provides(p); 2029 } 2030 2031 /** 2032 * Adds packages to the module. All packages in the set of package names 2033 * that are not in the module are added to module. 2034 * 2035 * @param pns 2036 * The (possibly empty) set of package names 2037 * 2038 * @return This builder 2039 * 2040 * @throws IllegalArgumentException 2041 * If any of the package names is {@code null} or is not a 2042 * legal package name 2043 */ 2044 public Builder packages(Set<String> pns) { 2045 if (strict) { 2046 pns = new HashSet<>(pns); 2047 pns.forEach(Checks::requirePackageName); 2048 } 2049 this.packages.addAll(pns); 2050 return this; 2051 } 2052 2053 /** 2054 * Sets the module version. 2055 * 2056 * @param v 2057 * The version 2058 * 2059 * @return This builder 2060 */ 2061 public Builder version(Version v) { 2062 version = requireNonNull(v); 2063 rawVersionString = null; 2064 return this; 2065 } 2066 2067 /** 2068 * Sets the module version. 2069 * 2070 * @param vs 2071 * The version string to parse 2072 * 2073 * @return This builder 2074 * 2075 * @throws IllegalArgumentException 2076 * If {@code vs} is {@code null} or cannot be parsed as a 2077 * version string 2078 * 2079 * @see Version#parse(String) 2080 */ 2081 public Builder version(String vs) { 2082 try { 2083 version = Version.parse(vs); 2084 rawVersionString = null; 2085 } catch (IllegalArgumentException e) { 2086 if (strict) throw e; 2087 version = null; 2088 rawVersionString = vs; 2089 } 2090 return this; 2091 } 2092 2093 /** 2094 * Sets the module main class. The package for the main class is added 2095 * to the module if not already added. In other words, this method is 2096 * equivalent to first invoking this builder's {@link #packages(Set) 2097 * packages} method to add the package name of the main class. 2098 * 2099 * @param mc 2100 * The module main class 2101 * 2102 * @return This builder 2103 * 2104 * @throws IllegalArgumentException 2105 * If {@code mainClass} is {@code null} or not a qualified 2106 * name of a class in a named package 2107 */ 2108 public Builder mainClass(String mc) { 2109 String pn; 2110 if (strict) { 2111 mc = requireQualifiedClassName("main class name", mc); 2112 pn = packageName(mc); 2113 assert !pn.isEmpty(); 2114 } else { 2115 // Disallow main class in unnamed package 2116 pn = packageName(mc); 2117 if (pn.isEmpty()) { 2118 throw new IllegalArgumentException(mc + ": unnamed package"); 2119 } 2120 } 2121 packages.add(pn); 2122 mainClass = mc; 2123 return this; 2124 } 2125 2126 /** 2127 * Builds and returns a {@code ModuleDescriptor} from its components. 2128 * 2129 * <p> The module will require "{@code java.base}" even if the dependence 2130 * has not been declared (the exception is when building a module named 2131 * "{@code java.base}" as it cannot require itself). The dependence on 2132 * "{@code java.base}" will have the {@link 2133 * java.lang.module.ModuleDescriptor.Requires.Modifier#MANDATED MANDATED} 2134 * modifier if the dependence was not declared. </p> 2135 * 2136 * @return The module descriptor 2137 */ 2138 public ModuleDescriptor build() { 2139 Set<Requires> requires = new HashSet<>(this.requires.values()); 2140 Set<Exports> exports = new HashSet<>(this.exports.values()); 2141 Set<Opens> opens = new HashSet<>(this.opens.values()); 2142 2143 // add dependency on java.base 2144 if (strict 2145 && !name.equals("java.base") 2146 && !this.requires.containsKey("java.base")) { 2147 requires.add(new Requires(Set.of(Requires.Modifier.MANDATED), 2148 "java.base", 2149 null, 2150 null)); 2151 } 2152 2153 Set<Provides> provides = new HashSet<>(this.provides.values()); 2154 2155 return new ModuleDescriptor(name, 2156 version, 2157 rawVersionString, 2158 modifiers, 2159 requires, 2160 exports, 2161 opens, 2162 uses, 2163 provides, 2164 packages, 2165 mainClass); 2166 } 2167 2168 } 2169 2170 /** 2171 * Compares this module descriptor to another. 2172 * 2173 * <p> Two {@code ModuleDescriptor} objects are compared by comparing their 2174 * module names lexicographically. Where the module names are equal then the 2175 * module versions are compared. When comparing the module versions then a 2176 * module descriptor with a version is considered to succeed a module 2177 * descriptor that does not have a version. If both versions are {@linkplain 2178 * Version#parse(String) unparseable} then the {@linkplain #rawVersion() 2179 * raw version strings} are compared lexicographically. Where the module names 2180 * are equal and the versions are equal (or not present in both), then the 2181 * set of modifiers are compared. Sets of modifiers are compared by comparing 2182 * a <em>binary value</em> computed for each set. If a modifier is present 2183 * in the set then the bit at the position of its ordinal is {@code 1} 2184 * in the binary value, otherwise {@code 0}. If the two set of modifiers 2185 * are also equal then the other components of the module descriptors are 2186 * compared in a manner that is consistent with {@code equals}. </p> 2187 * 2188 * @param that 2189 * The module descriptor to compare 2190 * 2191 * @return A negative integer, zero, or a positive integer if this module 2192 * descriptor is less than, equal to, or greater than the given 2193 * module descriptor 2194 */ 2195 @Override 2196 public int compareTo(ModuleDescriptor that) { 2197 if (this == that) return 0; 2198 2199 int c = this.name().compareTo(that.name()); 2200 if (c != 0) return c; 2201 2202 c = compare(this.version, that.version); 2203 if (c != 0) return c; 2204 2205 c = compare(this.rawVersionString, that.rawVersionString); 2206 if (c != 0) return c; 2207 2208 long v1 = modsValue(this.modifiers()); 2209 long v2 = modsValue(that.modifiers()); 2210 c = Long.compare(v1, v2); 2211 if (c != 0) return c; 2212 2213 c = compare(this.requires, that.requires); 2214 if (c != 0) return c; 2215 2216 c = compare(this.packages, that.packages); 2217 if (c != 0) return c; 2218 2219 c = compare(this.exports, that.exports); 2220 if (c != 0) return c; 2221 2222 c = compare(this.opens, that.opens); 2223 if (c != 0) return c; 2224 2225 c = compare(this.uses, that.uses); 2226 if (c != 0) return c; 2227 2228 c = compare(this.provides, that.provides); 2229 if (c != 0) return c; 2230 2231 c = compare(this.mainClass, that.mainClass); 2232 if (c != 0) return c; 2233 2234 return 0; 2235 } 2236 2237 /** 2238 * Tests this module descriptor for equality with the given object. 2239 * 2240 * <p> If the given object is not a {@code ModuleDescriptor} then this 2241 * method returns {@code false}. Two module descriptors are equal if each 2242 * of their corresponding components is equal. </p> 2243 * 2244 * <p> This method satisfies the general contract of the {@link 2245 * java.lang.Object#equals(Object) Object.equals} method. </p> 2246 * 2247 * @param ob 2248 * the object to which this object is to be compared 2249 * 2250 * @return {@code true} if, and only if, the given object is a module 2251 * descriptor that is equal to this module descriptor 2252 */ 2253 @Override 2254 public boolean equals(Object ob) { 2255 if (ob == this) 2256 return true; 2257 if (!(ob instanceof ModuleDescriptor)) 2258 return false; 2259 ModuleDescriptor that = (ModuleDescriptor)ob; 2260 return (name.equals(that.name) 2261 && modifiers.equals(that.modifiers) 2262 && requires.equals(that.requires) 2263 && Objects.equals(packages, that.packages) 2264 && exports.equals(that.exports) 2265 && opens.equals(that.opens) 2266 && uses.equals(that.uses) 2267 && provides.equals(that.provides) 2268 && Objects.equals(version, that.version) 2269 && Objects.equals(rawVersionString, that.rawVersionString) 2270 && Objects.equals(mainClass, that.mainClass)); 2271 } 2272 2273 /** 2274 * Computes a hash code for this module descriptor. 2275 * 2276 * <p> The hash code is based upon the components of the module descriptor, 2277 * and satisfies the general contract of the {@link Object#hashCode 2278 * Object.hashCode} method. </p> 2279 * 2280 * @return The hash-code value for this module descriptor 2281 */ 2282 @Override 2283 public int hashCode() { 2284 int hc = hash; 2285 if (hc == 0) { 2286 hc = name.hashCode(); 2287 hc = hc * 43 + Objects.hashCode(modifiers); 2288 hc = hc * 43 + requires.hashCode(); 2289 hc = hc * 43 + Objects.hashCode(packages); 2290 hc = hc * 43 + exports.hashCode(); 2291 hc = hc * 43 + opens.hashCode(); 2292 hc = hc * 43 + uses.hashCode(); 2293 hc = hc * 43 + provides.hashCode(); 2294 hc = hc * 43 + Objects.hashCode(version); 2295 hc = hc * 43 + Objects.hashCode(rawVersionString); 2296 hc = hc * 43 + Objects.hashCode(mainClass); 2297 if (hc == 0) 2298 hc = -1; 2299 hash = hc; 2300 } 2301 return hc; 2302 } 2303 private transient int hash; // cached hash code 2304 2305 /** 2306 * <p> Returns a string describing the module. </p> 2307 * 2308 * @return A string describing the module 2309 */ 2310 @Override 2311 public String toString() { 2312 StringBuilder sb = new StringBuilder(); 2313 2314 if (isOpen()) 2315 sb.append("open "); 2316 sb.append("module { name: ").append(toNameAndVersion()); 2317 if (!requires.isEmpty()) 2318 sb.append(", ").append(requires); 2319 if (!uses.isEmpty()) 2320 sb.append(", uses: ").append(uses); 2321 if (!exports.isEmpty()) 2322 sb.append(", exports: ").append(exports); 2323 if (!opens.isEmpty()) 2324 sb.append(", opens: ").append(opens); 2325 if (!provides.isEmpty()) { 2326 sb.append(", provides: ").append(provides); 2327 } 2328 sb.append(" }"); 2329 return sb.toString(); 2330 } 2331 2332 2333 /** 2334 * Instantiates a builder to build a module descriptor. 2335 * 2336 * @param name 2337 * The module name 2338 * @param ms 2339 * The set of module modifiers 2340 * 2341 * @return A new builder 2342 * 2343 * @throws IllegalArgumentException 2344 * If the module name is {@code null} or is not a legal module 2345 * name, or the set of modifiers contains {@link 2346 * Modifier#AUTOMATIC AUTOMATIC} with other modifiers 2347 */ 2348 public static Builder newModule(String name, Set<Modifier> ms) { 2349 Set<Modifier> mods = new HashSet<>(ms); 2350 if (mods.contains(Modifier.AUTOMATIC) && mods.size() > 1) 2351 throw new IllegalArgumentException("AUTOMATIC cannot be used with" 2352 + " other modifiers"); 2353 2354 return new Builder(name, true, mods); 2355 } 2356 2357 /** 2358 * Instantiates a builder to build a module descriptor for a <em>normal</em> 2359 * module. This method is equivalent to invoking {@link #newModule(String,Set) 2360 * newModule} with an empty set of {@link ModuleDescriptor.Modifier modifiers}. 2361 * 2362 * @param name 2363 * The module name 2364 * 2365 * @return A new builder 2366 * 2367 * @throws IllegalArgumentException 2368 * If the module name is {@code null} or is not a legal module 2369 * name 2370 */ 2371 public static Builder newModule(String name) { 2372 return new Builder(name, true, Set.of()); 2373 } 2374 2375 /** 2376 * Instantiates a builder to build a module descriptor for an open module. 2377 * This method is equivalent to invoking {@link #newModule(String,Set) 2378 * newModule} with the {@link ModuleDescriptor.Modifier#OPEN OPEN} modifier. 2379 * 2380 * <p> The builder for an open module cannot be used to declare any open 2381 * packages. </p> 2382 * 2383 * @param name 2384 * The module name 2385 * 2386 * @return A new builder that builds an open module 2387 * 2388 * @throws IllegalArgumentException 2389 * If the module name is {@code null} or is not a legal module 2390 * name 2391 */ 2392 public static Builder newOpenModule(String name) { 2393 return new Builder(name, true, Set.of(Modifier.OPEN)); 2394 } 2395 2396 /** 2397 * Instantiates a builder to build a module descriptor for an automatic 2398 * module. This method is equivalent to invoking {@link #newModule(String,Set) 2399 * newModule} with the {@link ModuleDescriptor.Modifier#AUTOMATIC AUTOMATIC} 2400 * modifier. 2401 * 2402 * <p> The builder for an automatic module cannot be used to declare module 2403 * or service dependences. It also cannot be used to declare any exported 2404 * or open packages. </p> 2405 * 2406 * @param name 2407 * The module name 2408 * 2409 * @return A new builder that builds an automatic module 2410 * 2411 * @throws IllegalArgumentException 2412 * If the module name is {@code null} or is not a legal module 2413 * name 2414 * 2415 * @see ModuleFinder#of(Path[]) 2416 */ 2417 public static Builder newAutomaticModule(String name) { 2418 return new Builder(name, true, Set.of(Modifier.AUTOMATIC)); 2419 } 2420 2421 2422 /** 2423 * Reads the binary form of a module declaration from an input stream 2424 * as a module descriptor. 2425 * 2426 * <p> If the descriptor encoded in the input stream does not indicate a 2427 * set of packages in the module then the {@code packageFinder} will be 2428 * invoked. The set of packages that the {@code packageFinder} returns 2429 * must include all the packages that the module exports, opens, as well 2430 * as the packages of the service implementations that the module provides, 2431 * and the package of the main class (if the module has a main class). If 2432 * the {@code packageFinder} throws an {@link UncheckedIOException} then 2433 * {@link IOException} cause will be re-thrown. </p> 2434 * 2435 * <p> If there are bytes following the module descriptor then it is 2436 * implementation specific as to whether those bytes are read, ignored, 2437 * or reported as an {@code InvalidModuleDescriptorException}. If this 2438 * method fails with an {@code InvalidModuleDescriptorException} or {@code 2439 * IOException} then it may do so after some, but not all, bytes have 2440 * been read from the input stream. It is strongly recommended that the 2441 * stream be promptly closed and discarded if an exception occurs. </p> 2442 * 2443 * @apiNote The {@code packageFinder} parameter is for use when reading 2444 * module descriptors from legacy module-artifact formats that do not 2445 * record the set of packages in the descriptor itself. 2446 * 2447 * @param in 2448 * The input stream 2449 * @param packageFinder 2450 * A supplier that can produce the set of packages 2451 * 2452 * @return The module descriptor 2453 * 2454 * @throws InvalidModuleDescriptorException 2455 * If an invalid module descriptor is detected or the set of 2456 * packages returned by the {@code packageFinder} does not include 2457 * all of the packages obtained from the module descriptor 2458 * @throws IOException 2459 * If an I/O error occurs reading from the input stream or {@code 2460 * UncheckedIOException} is thrown by the package finder 2461 */ 2462 public static ModuleDescriptor read(InputStream in, 2463 Supplier<Set<String>> packageFinder) 2464 throws IOException 2465 { 2466 return ModuleInfo.read(in, requireNonNull(packageFinder)).descriptor(); 2467 } 2468 2469 /** 2470 * Reads the binary form of a module declaration from an input stream as a 2471 * module descriptor. This method works exactly as specified by the 2-arg 2472 * {@link #read(InputStream,Supplier) read} method with the exception that 2473 * a packager finder is not used to find additional packages when the 2474 * module descriptor read from the stream does not indicate the set of 2475 * packages. 2476 * 2477 * @param in 2478 * The input stream 2479 * 2480 * @return The module descriptor 2481 * 2482 * @throws InvalidModuleDescriptorException 2483 * If an invalid module descriptor is detected 2484 * @throws IOException 2485 * If an I/O error occurs reading from the input stream 2486 */ 2487 public static ModuleDescriptor read(InputStream in) throws IOException { 2488 return ModuleInfo.read(in, null).descriptor(); 2489 } 2490 2491 /** 2492 * Reads the binary form of a module declaration from a byte buffer 2493 * as a module descriptor. 2494 * 2495 * <p> If the descriptor encoded in the byte buffer does not indicate a 2496 * set of packages in the module then the {@code packageFinder} will be 2497 * invoked. The set of packages that the {@code packageFinder} returns 2498 * must include all the packages that the module exports, opens, as well 2499 * as the packages of the service implementations that the module provides, 2500 * and the package of the main class (if the module has a main class). If 2501 * the {@code packageFinder} throws an {@link UncheckedIOException} then 2502 * {@link IOException} cause will be re-thrown. </p> 2503 * 2504 * <p> The module descriptor is read from the buffer starting at index 2505 * {@code p}, where {@code p} is the buffer's {@link ByteBuffer#position() 2506 * position} when this method is invoked. Upon return the buffer's position 2507 * will be equal to {@code p + n} where {@code n} is the number of bytes 2508 * read from the buffer. </p> 2509 * 2510 * <p> If there are bytes following the module descriptor then it is 2511 * implementation specific as to whether those bytes are read, ignored, 2512 * or reported as an {@code InvalidModuleDescriptorException}. If this 2513 * method fails with an {@code InvalidModuleDescriptorException} then it 2514 * may do so after some, but not all, bytes have been read. </p> 2515 * 2516 * @apiNote The {@code packageFinder} parameter is for use when reading 2517 * module descriptors from legacy module-artifact formats that do not 2518 * record the set of packages in the descriptor itself. 2519 * 2520 * @param bb 2521 * The byte buffer 2522 * @param packageFinder 2523 * A supplier that can produce the set of packages 2524 * 2525 * @return The module descriptor 2526 * 2527 * @throws InvalidModuleDescriptorException 2528 * If an invalid module descriptor is detected or the set of 2529 * packages returned by the {@code packageFinder} does not include 2530 * all of the packages obtained from the module descriptor 2531 */ 2532 public static ModuleDescriptor read(ByteBuffer bb, 2533 Supplier<Set<String>> packageFinder) 2534 { 2535 return ModuleInfo.read(bb, requireNonNull(packageFinder)).descriptor(); 2536 } 2537 2538 /** 2539 * Reads the binary form of a module declaration from a byte buffer as a 2540 * module descriptor. This method works exactly as specified by the 2-arg 2541 * {@link #read(ByteBuffer,Supplier) read} method with the exception that a 2542 * packager finder is not used to find additional packages when the module 2543 * descriptor encoded in the buffer does not indicate the set of packages. 2544 * 2545 * @param bb 2546 * The byte buffer 2547 * 2548 * @return The module descriptor 2549 * 2550 * @throws InvalidModuleDescriptorException 2551 * If an invalid module descriptor is detected 2552 */ 2553 public static ModuleDescriptor read(ByteBuffer bb) { 2554 return ModuleInfo.read(bb, null).descriptor(); 2555 } 2556 2557 private static String packageName(String cn) { 2558 int index = cn.lastIndexOf('.'); 2559 return (index == -1) ? "" : cn.substring(0, index); 2560 } 2561 2562 /** 2563 * Returns a string containing the given set of modifiers and label. 2564 */ 2565 private static <M> String toString(Set<M> mods, String what) { 2566 return (Stream.concat(mods.stream().map(e -> e.toString() 2567 .toLowerCase(Locale.ROOT)), 2568 Stream.of(what))) 2569 .collect(Collectors.joining(" ")); 2570 } 2571 2572 private static <T extends Object & Comparable<? super T>> 2573 int compare(T obj1, T obj2) { 2574 if (obj1 != null) { 2575 return (obj2 != null) ? obj1.compareTo(obj2) : 1; 2576 } else { 2577 return (obj2 == null) ? 0 : -1; 2578 } 2579 } 2580 2581 /** 2582 * Compares two sets of {@code Comparable} objects. 2583 */ 2584 @SuppressWarnings("unchecked") 2585 private static <T extends Object & Comparable<? super T>> 2586 int compare(Set<T> s1, Set<T> s2) { 2587 T[] a1 = (T[]) s1.toArray(); 2588 T[] a2 = (T[]) s2.toArray(); 2589 Arrays.sort(a1); 2590 Arrays.sort(a2); 2591 return Arrays.compare(a1, a2); 2592 } 2593 2594 private static <E extends Enum<E>> long modsValue(Set<E> set) { 2595 long value = 0; 2596 for (Enum<E> e : set) { 2597 value += 1 << e.ordinal(); 2598 } 2599 return value; 2600 } 2601 2602 static { 2603 /** 2604 * Setup the shared secret to allow code in other packages access 2605 * private package methods in java.lang.module. 2606 */ 2607 jdk.internal.access.SharedSecrets 2608 .setJavaLangModuleAccess(new jdk.internal.access.JavaLangModuleAccess() { 2609 @Override 2610 public Builder newModuleBuilder(String mn, 2611 boolean strict, 2612 Set<ModuleDescriptor.Modifier> modifiers) { 2613 return new Builder(mn, strict, modifiers); 2614 } 2615 2616 @Override 2617 public Set<String> packages(ModuleDescriptor.Builder builder) { 2618 return builder.packages(); 2619 } 2620 2621 @Override 2622 public void requires(ModuleDescriptor.Builder builder, 2623 Set<Requires.Modifier> ms, 2624 String mn, 2625 String rawCompiledVersion) { 2626 builder.requires(ms, mn, rawCompiledVersion); 2627 } 2628 2629 @Override 2630 public Requires newRequires(Set<Requires.Modifier> ms, String mn, Version v) { 2631 return new Requires(ms, mn, v, true); 2632 } 2633 2634 @Override 2635 public Exports newExports(Set<Exports.Modifier> ms, String source) { 2636 return new Exports(ms, source, Set.of(), true); 2637 } 2638 2639 @Override 2640 public Exports newExports(Set<Exports.Modifier> ms, 2641 String source, 2642 Set<String> targets) { 2643 return new Exports(ms, source, targets, true); 2644 } 2645 2646 @Override 2647 public Opens newOpens(Set<Opens.Modifier> ms, 2648 String source, 2649 Set<String> targets) { 2650 return new Opens(ms, source, targets, true); 2651 } 2652 2653 @Override 2654 public Opens newOpens(Set<Opens.Modifier> ms, String source) { 2655 return new Opens(ms, source, Set.of(), true); 2656 } 2657 2658 @Override 2659 public Provides newProvides(String service, List<String> providers) { 2660 return new Provides(service, providers, true); 2661 } 2662 2663 @Override 2664 public ModuleDescriptor newModuleDescriptor(String name, 2665 Version version, 2666 Set<ModuleDescriptor.Modifier> modifiers, 2667 Set<Requires> requires, 2668 Set<Exports> exports, 2669 Set<Opens> opens, 2670 Set<String> uses, 2671 Set<Provides> provides, 2672 Set<String> packages, 2673 String mainClass, 2674 int hashCode) { 2675 return new ModuleDescriptor(name, 2676 version, 2677 modifiers, 2678 requires, 2679 exports, 2680 opens, 2681 uses, 2682 provides, 2683 packages, 2684 mainClass, 2685 hashCode, 2686 false); 2687 } 2688 2689 @Override 2690 public Configuration resolveAndBind(ModuleFinder finder, 2691 Collection<String> roots, 2692 PrintStream traceOutput) 2693 { 2694 return Configuration.resolveAndBind(finder, roots, traceOutput); 2695 } 2696 2697 @Override 2698 public Configuration newConfiguration(ModuleFinder finder, 2699 Map<String, Set<String>> graph) { 2700 return new Configuration(finder, graph); 2701 } 2702 }); 2703 } 2704 2705 }