- All Implemented Interfaces:
Comparable<ModuleDescriptor>
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 the
ModuleDescriptor.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 module 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
modules 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:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
A builder for buildingModuleDescriptor
objects.static final class
A package exported by a module, may be qualified or unqualified.static enum
A modifier on a module.static final class
A package opened by a module, may be qualified or unqualified.static final class
A service that a module provides one or more implementations of.static final class
A dependence upon a module.static final class
A module's version string. -
Method Summary
Modifier and TypeMethodDescriptionReturns the set of the module flags.int
compareTo
(ModuleDescriptor that) Compares this module descriptor to another.boolean
Tests this module descriptor for equality with the given object.exports()
Returns the set ofExports
objects representing the exported packages.int
hashCode()
Computes a hash code for this module descriptor.boolean
Returnstrue
if this is an automatic module.boolean
isOpen()
Returnstrue
if this is an open module.Returns the module main class.Returns the set of module modifiers.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
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.opens()
Returns the set ofOpens
objects representing the open packages.packages()
Returns the set of packages in the module.provides()
Returns the set ofProvides
objects representing the services that the module provides.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.requires()
Returns the set ofRequires
objects representing the module dependences.Returns a string containing the module name and, if present, its version.toString()
Returns a string describing the module.uses()
Returns the set of service dependences.version()
Returns the module version.
-
Method Details
-
name
-
modifiers
Returns the set of module modifiers.
- Returns:
- A possibly-empty unmodifiable set of modifiers
-
accessFlags
Returns the set of the module flags.- Returns:
- A possibly-empty unmodifiable set of module flags
- See Java Virtual Machine Specification:
-
4.7.25 The Module Attribute
- Since:
- 20
- See Also:
-
isOpen
-
isAutomatic
-
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
objects
-
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
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
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 binary names of the service types used
-
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
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
-
rawVersion
-
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
Returns the module main class.
- Returns:
- The binary name of the module's main class
-
packages
-
compareTo
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 then the raw version strings 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 is1
in the binary value, otherwise0
. 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 withequals
.- Specified by:
compareTo
in interfaceComparable<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
Tests this module descriptor for equality with the given object.If the given object is not a
ModuleDescriptor
then this method returnsfalse
. Two module descriptors are equal if each of their corresponding components is equal.This method satisfies the general contract of the
Object.equals
method. -
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
method. -
toString
-
newModule
Instantiates a builder to build a module descriptor.- Parameters:
name
- The module namems
- 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
Instantiates a builder to build a module descriptor for a normal module. 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
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 open packages.
- 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
Instantiates a builder to build a module descriptor for an automatic module. This method is equivalent to invokingnewModule
with theAUTOMATIC
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
- 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) throws IOException 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 thepackageFinder
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 thepackageFinder
throws anUncheckedIOException
thenIOException
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 anInvalidModuleDescriptorException
orIOException
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 streampackageFinder
- 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 descriptorIOException
- If an I/O error occurs reading from the input stream orUncheckedIOException
is thrown by the package finder
-
read
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-argread
method with the exception that a package 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
- If an invalid module descriptor is detectedIOException
- If an I/O error occurs reading from the input stream
-
read
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 thepackageFinder
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 thepackageFinder
throws anUncheckedIOException
thenIOException
cause will be re-thrown.The module descriptor is read from the buffer starting at index
p
, wherep
is the buffer'sposition
when this method is invoked. Upon return the buffer's position will be equal top + n
wheren
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 anInvalidModuleDescriptorException
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 bufferpackageFinder
- 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
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-argread
method with the exception that a package 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
- If an invalid module descriptor is detected
-