ModuleDescriptor (Java SE 9 & JDK 9 ) (original) (raw)

java.lang.Object
- java.lang.module.ModuleDescriptor
All Implemented Interfaces:
[Comparable](../../../java/lang/Comparable.html "interface in java.lang")<[ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module")>

public class ModuleDescriptor
extends Object
implements Comparable<ModuleDescriptor>
A module descriptor.
A module descriptor describes a named module and defines methods to obtain each of its components. The module descriptor for a named module in the Java virtual machine is obtained by invoking the Module's getDescriptor method. Module descriptors can also be created using theModuleDescriptor.Builder class or by reading the binary form of a module declaration (module-info.class) using the read methods defined here.
A module descriptor describes a normal, open, or automatic module. Normal modules and open modules describe their dependences, exported-packages, the services that they use or provide, and other components. Normal modules may open specific packages. The module descriptor for an open modules does not declare any open packages (its opens method returns an empty set) but when instantiated in the Java virtual machine then it is treated as if all packages are open. The module descriptor for an automatic module does not declare any dependences (except for the mandatory dependency on java.base), and does not declare any exported or open packages. Automatic module receive special treatment during resolution so that they read all other modules in the configuration. When an automatic module is instantiated in the Java virtual machine then it reads every unnamed module and is treated as if all packages are exported and open.
ModuleDescriptor objects are immutable and safe for use by multiple concurrent threads.
Since:
9
See Also:
Module

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ModuleDescriptor.Builder	A builder for building ModuleDescriptor objects.
static class	ModuleDescriptor.Exports	A package exported by a module, may be qualified or unqualified.
static class	ModuleDescriptor.Modifier	A modifier on a module.
static class	ModuleDescriptor.Opens	A package opened by a module, may be qualified or unqualified.
static class	ModuleDescriptor.Provides	A service that a module provides one or more implementations of.
static class	ModuleDescriptor.Requires	A dependence upon a module
static class	ModuleDescriptor.Version	A module's version string.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods

Modifier and Type	Method	Description
int	compareTo(ModuleDescriptor that)	Compares this module descriptor to another.
boolean	equals(Object ob)	Tests this module descriptor for equality with the given object.
Set<ModuleDescriptor.Exports>	exports()	Returns the set of Exports objects representing the exported packages.
int	hashCode()	Computes a hash code for this module descriptor.
boolean	isAutomatic()	Returns true if this is an automatic module.
boolean	isOpen()	Returns true if this is an open module.
Optional<String>	mainClass()	Returns the module main class.
Set<ModuleDescriptor.Modifier>	modifiers()	Returns the set of module modifiers.
String	name()	Returns the module name.
static ModuleDescriptor.Builder	newAutomaticModule(String name)	Instantiates a builder to build a module descriptor for an automatic module.
static ModuleDescriptor.Builder	newModule(String name)	Instantiates a builder to build a module descriptor for a normal module.
static ModuleDescriptor.Builder	newModule(String name,Set<ModuleDescriptor.Modifier> ms)	Instantiates a builder to build a module descriptor.
static ModuleDescriptor.Builder	newOpenModule(String name)	Instantiates a builder to build a module descriptor for an open module.
Set<ModuleDescriptor.Opens>	opens()	Returns the set of Opens objects representing the open packages.
Set<String>	packages()	Returns the set of packages in the module.
Set<ModuleDescriptor.Provides>	provides()	Returns the set of Provides objects representing the services that the module provides.
Optional<String>	rawVersion()	Returns the string with the possibly-unparseable version of the module
static ModuleDescriptor	read(InputStream in)	Reads the binary form of a module declaration from an input stream as a module descriptor.
static ModuleDescriptor	read(InputStream in,Supplier<Set<String>> packageFinder)	Reads the binary form of a module declaration from an input stream as a module descriptor.
static ModuleDescriptor	read(ByteBuffer bb)	Reads the binary form of a module declaration from a byte buffer as a module descriptor.
static ModuleDescriptor	read(ByteBuffer bb,Supplier<Set<String>> packageFinder)	Reads the binary form of a module declaration from a byte buffer as a module descriptor.
Set<ModuleDescriptor.Requires>	requires()	Returns the set of Requires objects representing the module dependences.
String	toNameAndVersion()	Returns a string containing the module name and, if present, its version.
String	toString()	Returns a string describing the module.
Set<String>	uses()	Returns the set of service dependences.
Optional<ModuleDescriptor.Version>	version()	Returns the module version.

   * ### Methods inherited from class java.lang.[Object](../../../java/lang/Object.html "class in java.lang")  
   `[clone](../../../java/lang/Object.html#clone--), [finalize](../../../java/lang/Object.html#finalize--), [getClass](../../../java/lang/Object.html#getClass--), [notify](../../../java/lang/Object.html#notify--), [notifyAll](../../../java/lang/Object.html#notifyAll--), [wait](../../../java/lang/Object.html#wait--), [wait](../../../java/lang/Object.html#wait-long-), [wait](../../../java/lang/Object.html#wait-long-int-)`

Method Detail

 * #### name  
 public [String](../../../java/lang/String.html "class in java.lang") name()  
  Returns the module name.  
 Returns:  
 The module name  
 * #### modifiers  
 public [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Modifier](../../../java/lang/module/ModuleDescriptor.Modifier.html "enum in java.lang.module")> modifiers()  
  Returns the set of module modifiers.  
 Returns:  
 A possibly-empty unmodifiable set of modifiers  
 * #### isOpen  
 public boolean isOpen()  
  Returns `true` if this is an open module.  
  This method is equivalent to testing if the set of [modifiers](../../../java/lang/module/ModuleDescriptor.html#modifiers) contains the [OPEN](../../../java/lang/module/ModuleDescriptor.Modifier.html#OPEN) modifier.  
 Returns:  
 `true` if this is an open module  
 * #### isAutomatic  
 public boolean isAutomatic()  
  Returns `true` if this is an automatic module.  
  This method is equivalent to testing if the set of [modifiers](../../../java/lang/module/ModuleDescriptor.html#modifiers) contains the [AUTOMATIC](../../../java/lang/module/ModuleDescriptor.Modifier.html#OPEN) modifier.  
 Returns:  
 `true` if this is an automatic module  
 * #### requires  
 public [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Requires](../../../java/lang/module/ModuleDescriptor.Requires.html "class in java.lang.module")> requires()  
  Returns the set of `Requires` objects representing the module dependences.  
  The set includes a dependency on "`java.base`" when this module is not named "`java.base`". If this module is an automatic module then it does not have a dependency on any module other than "`java.base`".  
 Returns:  
 A possibly-empty unmodifiable set of [ModuleDescriptor.Requires](../../../java/lang/module/ModuleDescriptor.Requires.html "class in java.lang.module") objects  
 * #### exports  
 public [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Exports](../../../java/lang/module/ModuleDescriptor.Exports.html "class in java.lang.module")> exports()  
  Returns the set of `Exports` objects representing the exported packages.  
  If this module is an automatic module then the set of exports is empty.  
 Returns:  
 A possibly-empty unmodifiable set of exported packages  
 * #### opens  
 public [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Opens](../../../java/lang/module/ModuleDescriptor.Opens.html "class in java.lang.module")> opens()  
  Returns the set of `Opens` objects representing the open packages.  
  If this module is an open module or an automatic module then the set of open packages is empty.  
 Returns:  
 A possibly-empty unmodifiable set of open packages  
 * #### uses  
 public [Set](../../../java/util/Set.html "interface in java.util")<[String](../../../java/lang/String.html "class in java.lang")> uses()  
  Returns the set of service dependences.  
  If this module is an automatic module then the set of service dependences is empty.  
 Returns:  
 A possibly-empty unmodifiable set of the fully qualified class names of the service types used  
 * #### provides  
 public [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Provides](../../../java/lang/module/ModuleDescriptor.Provides.html "class in java.lang.module")> provides()  
  Returns the set of `Provides` objects representing the services that the module provides.  
 Returns:  
 The possibly-empty unmodifiable set of the services that this module provides  
 * #### version  
 public [Optional](../../../java/util/Optional.html "class in java.util")<[ModuleDescriptor.Version](../../../java/lang/module/ModuleDescriptor.Version.html "class in java.lang.module")> version()  
  Returns the module version.  
 Returns:  
 This module's version, or an empty `Optional` if the module does not have a version or the version is[unparseable](../../../java/lang/module/ModuleDescriptor.Version.html#parse-java.lang.String-)  
 * #### rawVersion  
 public [Optional](../../../java/util/Optional.html "class in java.util")<[String](../../../java/lang/String.html "class in java.lang")> rawVersion()  
  Returns the string with the possibly-unparseable version of the module  
 Returns:  
 The string containing the version of the module or an empty`Optional` if the module does not have a version  
 See Also:  
 [version()](../../../java/lang/module/ModuleDescriptor.html#version--)  
 * #### toNameAndVersion  
 public [String](../../../java/lang/String.html "class in java.lang") toNameAndVersion()  
  Returns a string containing the module name and, if present, its version.  
 Returns:  
 A string containing the module name and, if present, its version  
 * #### mainClass  
 public [Optional](../../../java/util/Optional.html "class in java.util")<[String](../../../java/lang/String.html "class in java.lang")> mainClass()  
  Returns the module main class.  
 Returns:  
 The fully qualified class name of the module's main class  
 * #### packages  
 public [Set](../../../java/util/Set.html "interface in java.util")<[String](../../../java/lang/String.html "class in java.lang")> packages()  
 Returns the set of packages in the module.  
  The set of packages includes all exported and open packages, as well as the packages of any service providers, and the package for the main class.  
 Returns:  
 A possibly-empty unmodifiable set of the packages in the module  
 * #### compareTo  
 public int compareTo([ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module") that)  
 Compares this module descriptor to another.  
  Two `ModuleDescriptor` objects are compared by comparing their module names lexicographically. Where the module names are equal then the module versions are compared. When comparing the module versions then a module descriptor with a version is considered to succeed a module descriptor that does not have a version. If both versions are [unparseable](../../../java/lang/module/ModuleDescriptor.Version.html#parse-java.lang.String-) then the [raw version strings](../../../java/lang/module/ModuleDescriptor.html#rawVersion--) are compared lexicographically. Where the module names are equal and the versions are equal (or not present in both), then the set of modifiers are compared. Sets of modifiers are compared by comparing a _binary value_ computed for each set. If a modifier is present in the set then the bit at the position of its ordinal is `1` in the binary value, otherwise `0`. If the two set of modifiers are also equal then the other components of the module descriptors are compared in a manner that is consistent with `equals`.  
 Specified by:  
 `[compareTo](../../../java/lang/Comparable.html#compareTo-T-)` in interface `[Comparable](../../../java/lang/Comparable.html "interface in java.lang")<[ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module")>`  
 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](../../../java/lang/Object.html "class in java.lang") ob)  
 Tests this module descriptor for equality with the given object.  
  If the given object is not a `ModuleDescriptor` then this method returns `false`. Two module descriptors are equal if each of their corresponding components is equal.  
  This method satisfies the general contract of the [Object.equals](../../../java/lang/Object.html#equals-java.lang.Object-) method.  
 Overrides:  
 `[equals](../../../java/lang/Object.html#equals-java.lang.Object-)` in class `[Object](../../../java/lang/Object.html "class in java.lang")`  
 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:  
 [Object.hashCode()](../../../java/lang/Object.html#hashCode--), [HashMap](../../../java/util/HashMap.html "class in java.util")  
 * #### 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 the [Object.hashCode](../../../java/lang/Object.html#hashCode--) method.  
 Overrides:  
 `[hashCode](../../../java/lang/Object.html#hashCode--)` in class `[Object](../../../java/lang/Object.html "class in java.lang")`  
 Returns:  
 The hash-code value for this module descriptor  
 See Also:  
 [Object.equals(java.lang.Object)](../../../java/lang/Object.html#equals-java.lang.Object-), [System.identityHashCode(java.lang.Object)](../../../java/lang/System.html#identityHashCode-java.lang.Object-)  
 * #### toString  
 public [String](../../../java/lang/String.html "class in java.lang") toString()  
  Returns a string describing the module.  
 Overrides:  
 `[toString](../../../java/lang/Object.html#toString--)` in class `[Object](../../../java/lang/Object.html "class in java.lang")`  
 Returns:  
 A string describing the module  
 * #### newModule  
 public static [ModuleDescriptor.Builder](../../../java/lang/module/ModuleDescriptor.Builder.html "class in java.lang.module") newModule([String](../../../java/lang/String.html "class in java.lang") name,  
                                                  [Set](../../../java/util/Set.html "interface in java.util")<[ModuleDescriptor.Modifier](../../../java/lang/module/ModuleDescriptor.Modifier.html "enum in java.lang.module")> 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](../../../java/lang/IllegalArgumentException.html "class in java.lang")` \- If the module name is `null` or is not a legal module name, or the set of modifiers contains [AUTOMATIC](../../../java/lang/module/ModuleDescriptor.Modifier.html#AUTOMATIC) with other modifiers  
 * #### newModule  
 public static [ModuleDescriptor.Builder](../../../java/lang/module/ModuleDescriptor.Builder.html "class in java.lang.module") newModule([String](../../../java/lang/String.html "class in java.lang") name)  
 Instantiates a builder to build a module descriptor for a _normal_ module. This method is equivalent to invoking [newModule](../../../java/lang/module/ModuleDescriptor.html#newModule-java.lang.String-java.util.Set-) with an empty set of [modifiers](../../../java/lang/module/ModuleDescriptor.Modifier.html "enum in java.lang.module").  
 Parameters:  
 `name` \- The module name  
 Returns:  
 A new builder  
 Throws:  
 `[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang")` \- If the module name is `null` or is not a legal module name  
 * #### newOpenModule  
 public static [ModuleDescriptor.Builder](../../../java/lang/module/ModuleDescriptor.Builder.html "class in java.lang.module") newOpenModule([String](../../../java/lang/String.html "class in java.lang") name)  
 Instantiates a builder to build a module descriptor for an open module. This method is equivalent to invoking [newModule](../../../java/lang/module/ModuleDescriptor.html#newModule-java.lang.String-java.util.Set-) with the [OPEN](../../../java/lang/module/ModuleDescriptor.Modifier.html#OPEN) modifier.  
  The builder for an open module cannot be used to declare any open packages.  
 Parameters:  
 `name` \- The module name  
 Returns:  
 A new builder that builds an open module  
 Throws:  
 `[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang")` \- If the module name is `null` or is not a legal module name  
 * #### newAutomaticModule  
 public static [ModuleDescriptor.Builder](../../../java/lang/module/ModuleDescriptor.Builder.html "class in java.lang.module") newAutomaticModule([String](../../../java/lang/String.html "class in java.lang") name)  
 Instantiates a builder to build a module descriptor for an automatic module. This method is equivalent to invoking [newModule](../../../java/lang/module/ModuleDescriptor.html#newModule-java.lang.String-java.util.Set-) with the [AUTOMATIC](../../../java/lang/module/ModuleDescriptor.Modifier.html#AUTOMATIC) modifier.  
  The builder for an automatic module cannot be used to declare module or service dependences. It also cannot be used to declare any exported or open packages.  
 Parameters:  
 `name` \- The module name  
 Returns:  
 A new builder that builds an automatic module  
 Throws:  
 `[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang")` \- If the module name is `null` or is not a legal module name  
 See Also:  
 [ModuleFinder.of(Path\[\])](../../../java/lang/module/ModuleFinder.html#of-java.nio.file.Path...-)  
 * #### read  
 public static [ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module") read([InputStream](../../../java/io/InputStream.html "class in java.io") in,  
                                     [Supplier](../../../java/util/function/Supplier.html "interface in java.util.function")<[Set](../../../java/util/Set.html "interface in java.util")<[String](../../../java/lang/String.html "class in java.lang")>> packageFinder)  
                              throws [IOException](../../../java/io/IOException.html "class in java.io")  
 Reads the binary form of a module declaration from an input stream as a module descriptor.  
  If the descriptor encoded in the input stream does not indicate a set of packages in the module then the `packageFinder` will be invoked. The set of packages that the `packageFinder` returns must include all the packages that the module exports, opens, as well as the packages of the service implementations that the module provides, and the package of the main class (if the module has a main class). If the `packageFinder` throws an [UncheckedIOException](../../../java/io/UncheckedIOException.html "class in java.io") then[IOException](../../../java/io/IOException.html "class in java.io") cause will be re-thrown.  
  If there are bytes following the module descriptor then it is implementation specific as to whether those bytes are read, ignored, or reported as an `InvalidModuleDescriptorException`. If this method fails with an `InvalidModuleDescriptorException` or ` IOException` then it may do so after some, but not all, bytes have been read from the input stream. It is strongly recommended that the stream be promptly closed and discarded if an exception occurs.  
 API Note:  
 The `packageFinder` parameter is for use when reading module descriptors from legacy module-artifact formats that do not record 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](../../../java/lang/module/InvalidModuleDescriptorException.html "class in java.lang.module")` \- If an invalid module descriptor is detected or the set of packages returned by the `packageFinder` does not include all of the packages obtained from the module descriptor  
 `[IOException](../../../java/io/IOException.html "class in java.io")` \- If an I/O error occurs reading from the input stream or ` UncheckedIOException` is thrown by the package finder  
 * #### read  
 public static [ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module") read([InputStream](../../../java/io/InputStream.html "class in java.io") in)  
                              throws [IOException](../../../java/io/IOException.html "class in java.io")  
 Reads the binary form of a module declaration from an input stream as a module descriptor. This method works exactly as specified by the 2-arg[read](../../../java/lang/module/ModuleDescriptor.html#read-java.io.InputStream-java.util.function.Supplier-) method with the exception that a packager finder is not used to find additional packages when the module descriptor read from the stream does not indicate the set of packages.  
 Parameters:  
 `in` \- The input stream  
 Returns:  
 The module descriptor  
 Throws:  
 `[InvalidModuleDescriptorException](../../../java/lang/module/InvalidModuleDescriptorException.html "class in java.lang.module")` \- If an invalid module descriptor is detected  
 `[IOException](../../../java/io/IOException.html "class in java.io")` \- If an I/O error occurs reading from the input stream  
 * #### read  
 public static [ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module") read([ByteBuffer](../../../java/nio/ByteBuffer.html "class in java.nio") bb,  
                                     [Supplier](../../../java/util/function/Supplier.html "interface in java.util.function")<[Set](../../../java/util/Set.html "interface in java.util")<[String](../../../java/lang/String.html "class in java.lang")>> packageFinder)  
 Reads the binary form of a module declaration from a byte buffer as a module descriptor.  
  If the descriptor encoded in the byte buffer does not indicate a set of packages in the module then the `packageFinder` will be invoked. The set of packages that the `packageFinder` returns must include all the packages that the module exports, opens, as well as the packages of the service implementations that the module provides, and the package of the main class (if the module has a main class). If the `packageFinder` throws an [UncheckedIOException](../../../java/io/UncheckedIOException.html "class in java.io") then[IOException](../../../java/io/IOException.html "class in java.io") cause will be re-thrown.  
  The module descriptor is read from the buffer stating at index`p`, where `p` is the buffer's [position](../../../java/nio/Buffer.html#position--) when this method is invoked. Upon return the buffer's position will be equal to `p + n` where `n` is the number of bytes read from the buffer.  
  If there are bytes following the module descriptor then it is implementation specific as to whether those bytes are read, ignored, or reported as an `InvalidModuleDescriptorException`. If this method fails with an `InvalidModuleDescriptorException` then it may do so after some, but not all, bytes have been read.  
 API Note:  
 The `packageFinder` parameter is for use when reading module descriptors from legacy module-artifact formats that do not record 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](../../../java/lang/module/InvalidModuleDescriptorException.html "class in java.lang.module")` \- If an invalid module descriptor is detected or the set of packages returned by the `packageFinder` does not include all of the packages obtained from the module descriptor  
 * #### read  
 public static [ModuleDescriptor](../../../java/lang/module/ModuleDescriptor.html "class in java.lang.module") read([ByteBuffer](../../../java/nio/ByteBuffer.html "class in java.nio") bb)  
 Reads the binary form of a module declaration from a byte buffer as a module descriptor. This method works exactly as specified by the 2-arg[read](../../../java/lang/module/ModuleDescriptor.html#read-java.nio.ByteBuffer-java.util.function.Supplier-) method with the exception that a packager finder is not used to find additional packages when the module descriptor encoded in the buffer does not indicate the set of packages.  
 Parameters:  
 `bb` \- The byte buffer  
 Returns:  
 The module descriptor  
 Throws:  
 `[InvalidModuleDescriptorException](../../../java/lang/module/InvalidModuleDescriptorException.html "class in java.lang.module")` \- If an invalid module descriptor is detected

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2017, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

ModuleDescriptor (Java SE 9 & JDK 9 ) (original) (raw)

Nested Class Summary

Method Summary

Method Detail