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