class:ModuleFinder [CHANGED]

```
public interface ModuleFinder
```
A finder of modules. A ModuleFinder is used to find modules during resolution or service binding .
A ModuleFinder can only find one module with a given name. A ModuleFinder that finds modules in a sequence of directories, for example, will locate the first occurrence of a module of a given name and will ignore other modules of that name that appear in directories later in the sequence.

Example usage:
```
     Path dir1, dir2, dir3;

     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Optional<ModuleReference> omref = finder.find("jdk.foo");
     if(omref.isPresentifPresent())mref {-> ... });

 
```
The find and findAll methods defined here can fail for several reasons. These includeinclude I/O errors, errors detected parsing a module descriptor (module-info.class), or in the case of ModuleFinder returned by ModuleFinder.of, that two or more modules with the same name are found in a directory. When an error is detected then these methods throw FindException with an appropriate cause. The behavior of a ModuleFinder after a FindException is thrown is undefined. For example, invoking find after an exception is thrown may or may not scan the same modules that lead to the exception. It is recommended that a module finder be discarded after an exception is thrown.

A ModuleFinder is not required to be thread safe.
Since:

9

```
public interface ModuleFinder
```
A finder of modules. A ModuleFinder is used to find modules during resolution or service binding .
A ModuleFinder can only find one module with a given name. A ModuleFinder that finds modules in a sequence of directories, for example, will locate the first occurrence of a module of a given name and will ignore other modules of that name that appear in directories later in the sequence.

Example usage:
```
     Path dir1, dir2, dir3;

     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Optional<ModuleReference> omref = finder.find("jdk.foo");
     if (omref.isPresent()) { ... }

 
```
The find and findAll methods defined here can fail for several reasons. These include include I/O errors, errors detected parsing a module descriptor (module-info.class), or in the case of ModuleFinder returned by ModuleFinder.of, that two or more modules with the same name are found in a directory. When an error is detected then these methods throw FindException with an appropriate cause. The behavior of a ModuleFinder after a FindException is thrown is undefined. For example, invoking find after an exception is thrown may or may not scan the same modules that lead to the exception. It is recommended that a module finder be discarded after an exception is thrown.

A ModuleFinder is not required to be thread safe.
Since:

9

```
public interface ModuleFinder
```
A finder of modules. A ModuleFinder is used to find modules during resolution or service binding .
A ModuleFinder can only find one module with a given name. A ModuleFinder that finds modules in a sequence of directories, for example, will locate the first occurrence of a module of a given name and will ignore other modules of that name that appear in directories later in the sequence.

Example usage:
```
     Path dir1, dir2, dir3;

     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Optional<ModuleReference> omref = finder.find("jdk.foo");
     omref.ifPresent(mref -> ... );

 
```
The find and findAll methods defined here can fail for several reasons. These include I/O errors, errors detected parsing a module descriptor (module-info.class), or in the case of ModuleFinder returned by ModuleFinder.of, that two or more modules with the same name are found in a directory. When an error is detected then these methods throw FindException with an appropriate cause. The behavior of a ModuleFinder after a FindException is thrown is undefined. For example, invoking find after an exception is thrown may or may not scan the same modules that lead to the exception. It is recommended that a module finder be discarded after an exception is thrown.

A ModuleFinder is not required to be thread safe.
Since:

9

method:find(java.lang.String) [NONE]

find
```
Optional<ModuleReference> find(String name)
```
Finds a reference to a module of a given name.
A ModuleFinder provides a consistent view of the modules that it locates. If find is invoked several times to locate the same module (by name) then it will return the same result each time. If a module is located then it is guaranteed to be a member of the set of modules returned by the findAll method.

Parameters:

name - The name of the module to find

Returns:

A reference to a module with the given name or an empty Optional if not found

Throws:

FindException - If an error occurs finding the module

SecurityException - If denied by the security manager

method:findAll() [NONE]

findAll
```
Set<ModuleReference> findAll()
```
Returns the set of all module references that this finder can locate.
A ModuleFinder provides a consistent view of the modules that it locates. If findAll is invoked several times then it will return the same (equals) result each time. For each ModuleReference element in the returned set then it is guaranteed that find will locate the ModuleReference if invoked to find that module.

API Note:

This is important to have for methods such as resolveRequiresAndUses that need to scan the module path to find modules that provide a specific service.

Returns:

The set of all module references that this finder locates

Throws:

FindException - If an error occurs finding all modules

SecurityException - If denied by the security manager

method:ofSystem() [NONE]

ofSystem
```
static ModuleFinder ofSystem()
```
Returns a module finder that locates the system modules . The system modules are typically linked into the Java run-time image. The module finder will always find java.base.
If there is a security manager set then its checkPermission method is invoked to check that the caller has been granted FilePermission to recursively read the directory that is the value of the system property java.home.

Returns:

A ModuleFinder that locates the system modules

Throws:

SecurityException - If denied by the security manager

method:of(java.nio.file.Path...) [CHANGED]

of
```
static ModuleFinder of(Path... entries)
```
Returns a module finder that locates modules on the file system by searching a sequence of directories and/or packaged modules. Each element in the given array is one of:
1. A path to a directory of modules.
2. A path to the top-level directory of an exploded module .
3. A path to a packaged module .
The module finder locates modules by searching each directory, exploded module, or packaged module in array index order. It finds the first occurrence of a module with a given name and ignores other modules of that name that appear later in the sequence.
If an element is a path to a directory of modules then each entry in the directory is a packaged module or the top-level directory of an exploded module. The module finder's find or findAll methods throw FindException if a directory containing more than one module with the same name is encountered.

If an element in the array is a path to a directory, and that directory contains a file named module-info.class, then the directory is treated as an exploded module rather than a directory of modules.

The module finder returned by this method supports modules that are packaged as JAR files. A JAR file with a module-info.class in the top-level directory of the JAR file (or overridden by a versioned entry in a multi-release JAR file) is a modular JAR and is an explicit module . A JAR file that does not have a module-info.class in the top-level directory is an automatic module. The ModuleDescriptor for an automatic module is created as follows:
- The module name, and version if applicable, is derived from the file name of the JAR file as follows:
  - The .jar suffix is removed.
  - If the name matches the regular expression "-(\\d+(\\.|$))" then the module name will be derived from the subsequence proceeding the hyphen of the first occurrence. The subsequence after the hyphen is parsed as a ModuleDescriptor.Version and ignored if it cannot be parsed as a Version.
  - For the module name, then all non-alphanumeric characters ([^A-Za-z0-9]) are replaced with a dot ("."), all repeating dots are replaced with one dot, and all leading and trailing dots are removed.
  - As an example, a JAR file named foo-bar.jar will derive a module name foo.bar and no version. A JAR file named foo-1.2.3-SNAPSHOT.jar will derive a module name foo and 1.2.3-SNAPSHOT as the version.
- It requires java.base .
- All entries in the JAR file with names ending with .class are assumed to be class files where the name corresponds to the fully qualified name of the class. The packages of all classes are exported.
- The contents of all entries starting with META-INF/services/ are assumed to be service configuration files (see ServiceLoader). The name of the file (that follows META-INF/services/) is assumed to be the fully-qualified binary name of a service type. The entries in the file are assumed to be the fully-qualified binary names of provider classes.
- If the JAR file has a Main-Class attribute in its main manifest then its value is the main class .
In addition to JAR files, an implementation may also support modules that are packaged in other implementation specific module formats. When a file is encountered that is not recognized as a packaged module then FindException is thrown. An implementation may choose to ignore some files, hidden files for example. Paths to files that do not exist are always ignored.

As with automatic modules, the contents of a packaged or exploded module may need to be scanned in order to determine the packages in the module. If a .class file that corresponds to a class in an unnamed package is encountered then FindException is thrown.

Finders created by this method are lazy and do not eagerly check that the given file paths are directories or packaged modules. Consequently, the find or findAll methods will only fail if invoking these methods results in searching a directory or packaged module and an error is encountered. Paths to files that do not exist are ignored.
Parameters:

entries - A possibly-empty array of paths to directories of modules or paths to packaged or exploded modules

Returns:

A ModuleFinder that locates modules on the file system

of
```
static ModuleFinder of(Path... entries)
```
Returns a module finder that locates modules on the file system by searching a sequence of directories and/or packaged modules. Each element in the given array is one of:
1. A path to a directory of modules.
2. A path to the top-level directory of an exploded module .
3. A path to a packaged module .
The module finder locates modules by searching each directory, exploded module, or packaged module in array index order. It finds the first occurrence of a module with a given name and ignores other modules of that name that appear later in the sequence.
If an element is a path to a directory of modules then each entry in the directory is a packaged module or the top-level directory of an exploded module. The module finder's find or findAll methods throw FindException if a directory containing more than one module with the same name is encountered.

If an element in the array is a path to a directory, and that directory contains a file named module-info.class, then the directory is treated as an exploded module rather than a directory of modules.

The module finder returned by this method supports modules that are packaged as JAR files. A JAR file with a module-info.class in the top-level directory of the JAR file is a modular JAR and is an explicit module . A JAR file that does not have a module-info.class in the top-level directory is an automatic module. The ModuleDescriptor for an automatic module is created as follows:
- The module name, and version if applicable, is derived from the file name of the JAR file as follows:
  - The .jar suffix is removed.
  - If the name matches the regular expression "-(\\d+(\\.|$))" then the module name will be derived from the subsequence proceeding the hyphen of the first occurrence. The subsequence after the hyphen is parsed as a ModuleDescriptor.Version and ignored if it cannot be parsed as a Version.
  - For the module name, then all non-alphanumeric characters ([^A-Za-z0-9]) are replaced with a dot ("."), all repeating dots are replaced with one dot, and all leading and trailing dots are removed.
  - As an example, a JAR file named foo-bar.jar will derive a module name foo.bar and no version. A JAR file named foo-1.2.3-SNAPSHOT.jar will derive a module name foo and 1.2.3-SNAPSHOT as the version.
- It requires java.base .
- All entries in the JAR file with names ending with .class are assumed to be class files where the name corresponds to the fully qualified name of the class. The packages of all classes are exported.
- The contents of all entries starting with META-INF/services/ are assumed to be service configuration files (see ServiceLoader). The name of the file (that follows META-INF/services/) is assumed to be the fully-qualified binary name of a service type. The entries in the file are assumed to be the fully-qualified binary names of provider classes.
- If the JAR file has a Main-Class attribute in its main manifest then its value is the main class .
In addition to JAR files, an implementation may also support modules that are packaged in other implementation specific module formats. As with automatic modules, the contents of a packaged or exploded module may need to be scanned in order to determine the packages in the module. If a .class file that corresponds to a class in an unnamed package is encountered then FindException is thrown.

Finders created by this method are lazy and do not eagerly check that the given file paths are directories or packaged modules. Consequently, the find or findAll methods will only fail if invoking these methods results in searching a directory or packaged module and an error is encountered. Paths to files that do not exist are ignored.
Parameters:

entries - A possibly-empty array of paths to directories of modules or paths to packaged or exploded modules

Returns:

A ModuleFinder that locates modules on the file system

of
```
static ModuleFinder of(Path... entries)
```
Returns a module finder that locates modules on the file system by searching a sequence of directories and/or packaged modules. Each element in the given array is one of:
1. A path to a directory of modules.
2. A path to the top-level directory of an exploded module .
3. A path to a packaged module .
The module finder locates modules by searching each directory, exploded module, or packaged module in array index order. It finds the first occurrence of a module with a given name and ignores other modules of that name that appear later in the sequence.
If an element is a path to a directory of modules then each entry in the directory is a packaged module or the top-level directory of an exploded module. The module finder's find or findAll methods throw FindException if a directory containing more than one module with the same name is encountered.

If an element in the array is a path to a directory, and that directory contains a file named module-info.class, then the directory is treated as an exploded module rather than a directory of modules.

The module finder returned by this method supports modules that are packaged as JAR files. A JAR file with a module-info.class in the top-level directory of the JAR file (or overridden by a versioned entry in a multi-release JAR file) is a modular JAR and is an explicit module . A JAR file that does not have a module-info.class in the top-level directory is an automatic module. The ModuleDescriptor for an automatic module is created as follows:
- The module name, and version if applicable, is derived from the file name of the JAR file as follows:
  - The .jar suffix is removed.
  - If the name matches the regular expression "-(\\d+(\\.|$))" then the module name will be derived from the subsequence proceeding the hyphen of the first occurrence. The subsequence after the hyphen is parsed as a ModuleDescriptor.Version and ignored if it cannot be parsed as a Version.
  - For the module name, then all non-alphanumeric characters ([^A-Za-z0-9]) are replaced with a dot ("."), all repeating dots are replaced with one dot, and all leading and trailing dots are removed.
  - As an example, a JAR file named foo-bar.jar will derive a module name foo.bar and no version. A JAR file named foo-1.2.3-SNAPSHOT.jar will derive a module name foo and 1.2.3-SNAPSHOT as the version.
- It requires java.base .
- All entries in the JAR file with names ending with .class are assumed to be class files where the name corresponds to the fully qualified name of the class. The packages of all classes are exported.
- The contents of all entries starting with META-INF/services/ are assumed to be service configuration files (see ServiceLoader). The name of the file (that follows META-INF/services/) is assumed to be the fully-qualified binary name of a service type. The entries in the file are assumed to be the fully-qualified binary names of provider classes.
- If the JAR file has a Main-Class attribute in its main manifest then its value is the main class .
In addition to JAR files, an implementation may also support modules that are packaged in other implementation specific module formats. When a file is encountered that is not recognized as a packaged module then FindException is thrown. An implementation may choose to ignore some files, hidden files for example. Paths to files that do not exist are always ignored.

As with automatic modules, the contents of a packaged or exploded module may need to be scanned in order to determine the packages in the module. If a .class file that corresponds to a class in an unnamed package is encountered then FindException is thrown.

Finders created by this method are lazy and do not eagerly check that the given file paths are directories or packaged modules. Consequently, the find or findAll methods will only fail if invoking these methods results in searching a directory or packaged module and an error is encountered.
Parameters:

entries - A possibly-empty array of paths to directories of modules or paths to packaged or exploded modules

Returns:

A ModuleFinder that locates modules on the file system

method:compose(java.lang.module.ModuleFinder, java.lang.module.ModuleFinder) [REMOVED]

compose
```
static ModuleFinder compose(ModuleFinder first,
                            ModuleFinder second)
```
Returns a module finder that is the equivalent to composing two module finders. The resulting finder will locate modules references using first; if not found then it will attempt to locate module references using second.
The findAll method of the resulting module finder will locate all modules located by the first module finder. It will also locate all modules located by the second module finder that are not located by the first module finder.

API Note:

This method will eventually be changed to take a sequence of module finders.

Parameters:

first - The first module finder

second - The second module finder

Returns:

A ModuleFinder that composes two module finders

method:empty() [REMOVED]

empty
```
static ModuleFinder empty()
```
Returns an empty module finder. The empty finder does not find any modules.

API Note:

This is useful when using methods such as resolveRequires where two finders are specified. An alternative is ModuleFinder.of().

Returns:

A ModuleFinder that does not find any modules

method:compose(java.lang.module.ModuleFinder...) [ADDED]

compose
```
static ModuleFinder compose(ModuleFinder... finders)
```
Returns a module finder that is composed from a sequence of zero or more module finders. The find method of the resulting module finder will locate a module by invoking the find method of each module finder, in array index order, until either the module is found or all module finders have been searched. The findAll method of the resulting module finder will return a set of modules that includes all modules located by the first module finder. The set of modules will include all modules located by the second or subsequent module finder that are not located by previous module finders in the sequence.
When locating modules then any exceptions or errors thrown by the find or findAll methods of the underlying module finders will be propogated to the caller of the resulting module finder's find or findAll methods.

Parameters:

finders - The array of module finders

Returns:

A ModuleFinder that composes a sequence of module finders