Class ModuleDescriptor

java.lang.Object
java.lang.module.ModuleDescriptor
All Implemented Interfaces:
Comparable<ModuleDescriptor>
public final classModuleDescriptorextendsObjectimplementsComparable<ModuleDescriptor>
A module descriptor.

A module descriptor describes a named module and defines methods toobtain each of its components. The module descriptor for a named modulein the Java virtual machine is obtained by invoking theModule'sgetDescriptor method. Module descriptors can also be created using theModuleDescriptor.Builder class or by reading the binary form of amodule declaration (module-info.class) using theread methods defined here.

A module descriptor describes anormal, open, or automaticmodule.Normal modules and open modules describe theirdependences,exported-packages, the servicesthat theyuse orprovide, and othercomponents.Normal modules mayopen specificpackages. The module descriptor for an open module does not declare anyopen packages (itsopens method returns an empty set) but wheninstantiated in the Java virtual machine then it is treated as if allpackages are open. The module descriptor for an automatic module does notdeclare any dependences (except for the mandatory dependency onjava.base), and does not declare any exported or open packages. Automaticmodules receive special treatment during resolution so that they read allother modules in the configuration. When an automatic module is instantiatedin the Java virtual machine then it reads every unnamed module and istreated as if all packages are exported and open.

ModuleDescriptor objects are immutable and safe for use bymultiple concurrent threads.

Since:
9
See Also:

  • Method Details

    • name

      public String name()

      Returns the module name.

      Returns:
      The module name

    • modifiers

      public Set<ModuleDescriptor.Modifier> modifiers()

      Returns the set of module modifiers.

      Returns:
      A possibly-empty unmodifiable set of modifiers

    • accessFlags

      public Set<AccessFlag> accessFlags()
      Returns the set of themodule flags.
      Returns:
      A possibly-empty unmodifiable set of module flags
      SeeJava Virtual Machine Specification:
      4.7.25 The Module Attribute
      Since:
      20
      See Also:

    • isOpen

      public boolean isOpen()

      Returnstrue if this is an open module.

      This method is equivalent to testing if the set ofmodifiers contains theOPEN modifier.

      Returns:
      true if this is an open module

    • isAutomatic

      public boolean isAutomatic()

      Returnstrue if this is an automatic module.

      This method is equivalent to testing if the set ofmodifiers contains theAUTOMATIC modifier.

      Returns:
      true if this is an automatic module

    • requires

      public Set<ModuleDescriptor.Requires> requires()

      Returns the set ofRequires objects representing the moduledependences.

      The set includes a dependency on "java.base" when thismodule is not named "java.base". If this module is an automaticmodule then it does not have a dependency on any module other than"java.base".

      Returns:
      A possibly-empty unmodifiable set ofModuleDescriptor.Requires objects

    • exports

      public Set<ModuleDescriptor.Exports> exports()

      Returns the set ofExports objects representing the exportedpackages.

      If this module is an automatic module then the set of exportsis empty.

      Returns:
      A possibly-empty unmodifiable set of exported packages

    • opens

      public Set<ModuleDescriptor.Opens> opens()

      Returns the set ofOpens objects representing the openpackages.

      If this module is an open module or an automatic module then theset of open packages is empty.

      Returns:
      A possibly-empty unmodifiable set of open packages

    • uses

      public Set<String> uses()

      Returns the set of service dependences.

      If this module is an automatic module then the set of servicedependences is empty.

      Returns:
      A possibly-empty unmodifiable set of thebinary names of the service types used

    • provides

      public Set<ModuleDescriptor.Provides> provides()

      Returns the set ofProvides objects representing theservices that the module provides.

      Returns:
      The possibly-empty unmodifiable set of the services that this module provides

    • version

      Returns the module version.

      Returns:
      This module's version, or an emptyOptional if the module does not have a version or the version isunparseable

    • rawVersion

      public Optional<String> rawVersion()

      Returns the string with the possibly-unparseable version of themodule.

      Returns:
      The string containing the version of the module or an emptyOptional if the module does not have a version
      See Also:

    • toNameAndVersion

      public String toNameAndVersion()

      Returns a string containing the module name and, if present, itsversion.

      Returns:
      A string containing the module name and, if present, its version

    • mainClass

      public Optional<String> mainClass()

      Returns the module main class.

      Returns:
      Thebinary name of the module's main class

    • packages

      public Set<String> packages()
      Returns the set of packages in the module.

      The set of packages includes all exported and open packages, as wellas the packages of any service providers, and the package for the mainclass.

      Returns:
      A possibly-empty unmodifiable set of the packages in the module

    • compareTo

      public int compareTo(ModuleDescriptor that)
      Compares this module descriptor to another.

      TwoModuleDescriptor objects are compared by comparing theirmodule names lexicographically. Where the module names are equal then themodule versions are compared. When comparing the module versions then amodule descriptor with a version is considered to succeed a moduledescriptor that does not have a version. If both versions areunparseable then theraw version strings are compared lexicographically. Where the module namesare equal and the versions are equal (or not present in both), then theset of modifiers are compared. Sets of modifiers are compared by comparingabinary value computed for each set. If a modifier is presentin the set then the bit at the position of its ordinal is1in the binary value, otherwise0. If the two set of modifiersare also equal then the other components of the module descriptors arecompared in a manner that is consistent withequals.

      Specified by:
      compareTo in interface Comparable<ModuleDescriptor>
      Parameters:
      that - The module descriptor to compare
      Returns:
      A negative integer, zero, or a positive integer if this module descriptor is less than, equal to, or greater than the given module descriptor

    • equals

      public boolean equals(Object ob)
      Tests this module descriptor for equality with the given object.

      If the given object is not aModuleDescriptor then thismethod returnsfalse. Two module descriptors are equal if eachof their corresponding components is equal.

      This method satisfies the general contract of theObject.equals method.

      Overrides:
      equals in class Object
      Parameters:
      ob - the object to which this object is to be compared
      Returns:
      true if, and only if, the given object is a module descriptor that is equal to this module descriptor
      See Also:

    • hashCode

      public int hashCode()
      Computes a hash code for this module descriptor.

      The hash code is based upon the components of the module descriptor,and satisfies the general contract of theObject.hashCode method.

      Overrides:
      hashCode in class Object
      Returns:
      The hash-code value for this module descriptor
      See Also:

    • toString

      public String toString()

      Returns a string describing the module.

      Overrides:
      toString in class Object
      Returns:
      A string describing the module

    • newModule

      public static ModuleDescriptor.Builder newModule(String name,Set<ModuleDescriptor.Modifier> ms)
      Instantiates a builder to build a module descriptor.
      Parameters:
      name - The module name
      ms - The set of module modifiers
      Returns:
      A new builder
      Throws:
      IllegalArgumentException - If the module name isnull or is not a legal module name, or the set of modifiers containsAUTOMATIC with other modifiers

    • newModule

      public static ModuleDescriptor.Builder newModule(String name)
      Instantiates a builder to build a module descriptor for anormalmodule. This method is equivalent to invokingnewModule with an empty set ofmodifiers.
      Parameters:
      name - The module name
      Returns:
      A new builder
      Throws:
      IllegalArgumentException - If the module name isnull or is not a legal module name

    • newOpenModule

      public static ModuleDescriptor.Builder newOpenModule(String name)
      Instantiates a builder to build a module descriptor for an open module.This method is equivalent to invokingnewModule with theOPEN modifier.

      The builder for an open module cannot be used to declare any openpackages.

      Parameters:
      name - The module name
      Returns:
      A new builder that builds an open module
      Throws:
      IllegalArgumentException - If the module name isnull or is not a legal module name

    • newAutomaticModule

      public static ModuleDescriptor.Builder newAutomaticModule(String name)
      Instantiates a builder to build a module descriptor for an automaticmodule. This method is equivalent to invokingnewModule with theAUTOMATICmodifier.

      The builder for an automatic module cannot be used to declare moduleor service dependences. It also cannot be used to declare any exportedor open packages.

      Parameters:
      name - The module name
      Returns:
      A new builder that builds an automatic module
      Throws:
      IllegalArgumentException - If the module name isnull or is not a legal module name
      See Also:

    • read

      public static ModuleDescriptor read(InputStream in,Supplier<Set<String>> packageFinder) throwsIOException
      Reads the binary form of a module declaration from an input streamas a module descriptor.

      If the descriptor encoded in the input stream does not indicate aset of packages in the module then thepackageFinder will beinvoked. The set of packages that thepackageFinder returnsmust include all the packages that the module exports, opens, as wellas the packages of the service implementations that the module provides,and the package of the main class (if the module has a main class). IfthepackageFinder throws anUncheckedIOException thenIOException cause will be re-thrown.

      If there are bytes following the module descriptor then it isimplementation specific as to whether those bytes are read, ignored,or reported as anInvalidModuleDescriptorException. If thismethod fails with anInvalidModuleDescriptorException orIOException then it may do so after some, but not all, bytes havebeen read from the input stream. It is strongly recommended that thestream be promptly closed and discarded if an exception occurs.

      API Note:
      ThepackageFinder parameter is for use when readingmodule descriptors from legacy module-artifact formats that do notrecord the set of packages in the descriptor itself.
      Parameters:
      in - The input stream
      packageFinder - A supplier that can produce the set of packages
      Returns:
      The module descriptor
      Throws:
      InvalidModuleDescriptorException - If an invalid module descriptor is detected or the set of packages returned by thepackageFinder does not include all of the packages obtained from the module descriptor
      IOException - If an I/O error occurs reading from the input stream or UncheckedIOException is thrown by the package finder

    • read

      public static ModuleDescriptor read(InputStream in) throwsIOException
      Reads the binary form of a module declaration from an input stream as amodule descriptor. This method works exactly as specified by the 2-argread method with the exception thata package finder is not used to find additional packages when themodule descriptor read from the stream does not indicate the set ofpackages.
      Parameters:
      in - The input stream
      Returns:
      The module descriptor
      Throws:
      InvalidModuleDescriptorException - If an invalid module descriptor is detected
      IOException - If an I/O error occurs reading from the input stream

    • read

      public static ModuleDescriptor read(ByteBuffer bb,Supplier<Set<String>> packageFinder)
      Reads the binary form of a module declaration from a byte bufferas a module descriptor.

      If the descriptor encoded in the byte buffer does not indicate aset of packages in the module then thepackageFinder will beinvoked. The set of packages that thepackageFinder returnsmust include all the packages that the module exports, opens, as wellas the packages of the service implementations that the module provides,and the package of the main class (if the module has a main class). IfthepackageFinder throws anUncheckedIOException thenIOException cause will be re-thrown.

      The module descriptor is read from the buffer starting at indexp, wherep is the buffer'sposition when this method is invoked. Upon return the buffer's positionwill be equal top + n wheren is the number of bytesread from the buffer.

      If there are bytes following the module descriptor then it isimplementation specific as to whether those bytes are read, ignored,or reported as anInvalidModuleDescriptorException. If thismethod fails with anInvalidModuleDescriptorException then itmay do so after some, but not all, bytes have been read.

      API Note:
      ThepackageFinder parameter is for use when readingmodule descriptors from legacy module-artifact formats that do notrecord the set of packages in the descriptor itself.
      Parameters:
      bb - The byte buffer
      packageFinder - A supplier that can produce the set of packages
      Returns:
      The module descriptor
      Throws:
      InvalidModuleDescriptorException - If an invalid module descriptor is detected or the set of packages returned by thepackageFinder does not include all of the packages obtained from the module descriptor

    • read

      public static ModuleDescriptor read(ByteBuffer bb)
      Reads the binary form of a module declaration from a byte buffer as amodule descriptor. This method works exactly as specified by the 2-argread method with the exception that apackage finder is not used to find additional packages when the moduledescriptor encoded in the buffer does not indicate the set of packages.
      Parameters:
      bb - The byte buffer
      Returns:
      The module descriptor
      Throws:
      InvalidModuleDescriptorException - If an invalid module descriptor is detected