Module java.base
Package java.lang.module

## Class ModuleDescriptor

- java.lang.Object
- - java.lang.module.ModuleDescriptor

All Implemented Interfaces:
  Comparable<ModuleDescriptor>

    public class ModuleDescriptor
    extends Object
    implements Comparable<ModuleDescriptor>

A module descriptor.

A `ModuleDescriptor` is typically created from the binary form of a module declaration. The associated `ModuleDescriptor.Builder` class can also be used to create a `ModuleDescriptor` from its components.

`ModuleDescriptor` objects are immutable and safe for use by multiple concurrent threads.

Since:
  9
See Also:
  `Module`

### Nested Class Summary

Nested Classes
`static class` `ModuleDescriptor.Builder` A builder used for building `ModuleDescriptor` objects.
`static class` `ModuleDescriptor.Exports` A module export, 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
`int` `compareTo(ModuleDescriptor that)` Compares this module descriptor to another.
`Set<String>` `conceals()` Returns the names of the packages defined in, but not exported by, this module.
`boolean` `equals(Object ob)` Tests this module descriptor for equality with the given object.
`Set<ModuleDescriptor.Exports>` `exports()` The module exports.
`int` `hashCode()` Computes a hash code for this module descriptor.
`boolean` `isAutomatic()` Returns `true` if this is an automatic module.
`boolean` `isSynthetic()` Returns `true` if this module descriptor was not generated from an explicit module declaration (`module-info.java`) or an implicit module declaration (an `automatic` module).
`Optional<String>` `mainClass()` Returns the module's main class.
`String` `name()` The module name.
`Optional<String>` `osArch()` Returns the operating system architecture if this module is operating system architecture specific.
`Optional<String>` `osName()` Returns the operating system name if this module is operating system specific.
`Optional<String>` `osVersion()` Returns the operating system version if this module is operating system version specific.
`Set<String>` `packages()` Returns the names of all the packages defined in this module, whether exported or concealed.
`Map<String,ModuleDescriptor.Provides>` `provides()` The services that this module provides.
`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()` The dependences of this module.
`String` `toNameAndVersion()` Returns a string containing this module's name and, if present, its version.
`String` `toString()` Returns a string describing this descriptor.
`Set<String>` `uses()` The service dependences of this module.
`Optional<ModuleDescriptor.Version>` `version()` Returns this module's version.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Method Detail

#### name

    public String name()

The module name.

Returns:
  The module name

#### isAutomatic

    public boolean isAutomatic()

Returns `true` if this is an automatic module.

An automatic module is defined implicitly rather than explicitly and therefore does not have a module declaration. JAR files located on the application module path, or by the `ModuleFinder` returned by `ModuleFinder.of`, are treated as automatic modules if they do have not have a module declaration.

Returns:
  `true` if this is an automatic module

#### isSynthetic

    public boolean isSynthetic()

Returns `true` if this module descriptor was not generated from an explicit module declaration (`module-info.java`) or an implicit module declaration (an `automatic` module).

Returns:
  `true` if this module descriptor was not generated by an explicit or implicit module declaration
See The Java™ Virtual Machine Specification:
  4.7.8 The `Synthetic` Attribute

#### requires

    public Set<ModuleDescriptor.Requires> requires()

The dependences of this module.

Returns:
  A possibly-empty unmodifiable set of `ModuleDescriptor.Requires` objects

#### uses

    public Set<String> uses()

The service dependences of this module.

Returns:
  A possibly-empty unmodifiable set of the fully qualified class names of the service types used

#### provides

    public Map<String,ModuleDescriptor.Provides> provides()

The services that this module provides.

Returns:
  The possibly-empty unmodifiable map of the services that this module provides. The map key is fully qualified class name of the service type.

#### exports

    public Set<ModuleDescriptor.Exports> exports()

The module exports.

Returns:
  A possibly-empty unmodifiable set of exported packages

#### version

    public Optional<ModuleDescriptor.Version> version()

Returns this module's version.

Returns:
  This module's version

#### toNameAndVersion

    public String toNameAndVersion()

Returns a string containing this module's name and, if present, its version.

Returns:
  A string containing this module's name and, if present, its version.

#### mainClass

    public Optional<String> mainClass()

Returns the module's main class.

Returns:
  The fully qualified class name of this module's main class

#### osName

    public Optional<String> osName()

Returns the operating system name if this module is operating system specific.

Returns:
  The operating system name or an empty `Optional` if this module is not operating system specific

#### osArch

    public Optional<String> osArch()

Returns the operating system architecture if this module is operating system architecture specific.

Returns:
  The operating system architecture or an empty `Optional` if this module is not operating system architecture specific

#### osVersion

    public Optional<String> osVersion()

Returns the operating system version if this module is operating system version specific.

Returns:
  The operating system version or an empty `Optional` if this module is not operating system version specific

#### conceals

    public Set<String> conceals()

Returns the names of the packages defined in, but not exported by, this module.

Returns:
  A possibly-empty unmodifiable set of the concealed packages

#### packages

    public Set<String> packages()

Returns the names of all the packages defined in this module, whether exported or concealed.

Returns:
  A possibly-empty unmodifiable set of the all packages

#### compareTo

    public int compareTo(ModuleDescriptor that)

Compares this module descriptor to another.

Two `ModuleDescriptor` objects are compared by comparing their module name lexicographically. Where the module names are equal then the versions, if present, are compared.

Specified by:
  `compareTo` in interface `Comparable<ModuleDescriptor>`
API Note:
  For now, the natural ordering is not consistent with equals. If two module descriptors have equal module names, equal versions if present, but their corresponding components are not equal, then they will be considered equal by this method.
Parameters:
  `that` - The object to which this module descriptor is to be compared
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 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` 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:
  `Object.hashCode()`, `HashMap`

#### 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.

Overrides:
  `hashCode` in class `Object`
Returns:
  The hash-code value for this module descriptor
See Also:
  `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

#### toString

    public String toString()

Returns a string describing this descriptor.

Overrides:
  `toString` in class `Object`
Returns:
  A string describing this descriptor

#### 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 concealed packages then the `packageFinder` will be invoked. The packages it returns, except for those indicated as exported in the encoded descriptor, will be considered to be concealed. If the `packageFinder` throws an `UncheckedIOException` then `IOException` 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 concealed packages in the descriptor itself.
Parameters:
  `in` - The input stream
  `packageFinder` - A supplier that can produce a set of package names
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 or `UncheckedIOException` is thrown by the package finder

#### read

    public static ModuleDescriptor read(InputStream in)
                                 throws IOException

Reads the binary form of a module declaration from an input stream as a module descriptor.

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 buffer as a module descriptor.

If the descriptor encoded in the byte buffer does not indicate a set of concealed packages then the `packageFinder` will be invoked. The packages it returns, except for those indicated as exported in the encoded descriptor, will be considered to be concealed.

The module descriptor is read from the buffer stating at index `p`, where `p` is the buffer's `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 concealed packages in the descriptor itself.
Parameters:
  `bb` - The byte buffer
  `packageFinder` - A supplier that can produce a set of package names
Returns:
  The module descriptor
Throws:
  `InvalidModuleDescriptorException` - If an invalid module descriptor is detected

#### read

    public static ModuleDescriptor read(ByteBuffer bb)

Reads the binary form of a module declaration from a byte buffer as a module descriptor.

Parameters:
  `bb` - The byte buffer
Returns:
  The module descriptor
Throws:
  `InvalidModuleDescriptorException` - If an invalid module descriptor is detected