public interface ModuleFinder
ModuleFinder is used to find modules during
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
Path dir1, dir2, dir3;
ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
Optional<ModuleReference> omref = finder.find("jdk.foo");
omref.ifPresent(mref -> ... );
defined here can fail for several reasons. These include I/O errors, errors
detected parsing a module descriptor (
module-info.class), or in the
ModuleFinder returned by
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
The behavior of a
ModuleFinder after a
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
ModuleFinder is not required to be thread safe.
|Modifier and Type
Returns a module finder that is composed from a sequence of zero or more module finders.
Finds a reference to a module of a given name.
Returns the set of all module references that this finder can locate.
Returns a module finder that locates modules on the file system by searching a sequence of directories and/or packaged modules.
Returns a module finder that locates the system modules.
Optional<ModuleReference> find(String name)
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
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.
resolveAndBind that need to scan the
module path to find modules that provide a specific service.
FindException - If an error occurs finding all modules
SecurityException - If denied by the security manager
static ModuleFinder ofSystem()
If there is a security manager set then its
checkPermission method is
invoked to check that the caller has been granted
to recursively read the directory that is the value of the system
ModuleFinder that locates the system modules
SecurityException - If denied by the security manager
static ModuleFinder of(Path... entries)
A path to a directory of modules.
A path to the top-level directory of an exploded module.
A path to a packaged module.
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. It it an error if a directory contains more than one
module with the same name. If an element 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
The module finder returned by this method supports modules that are
packaged as JAR files. A JAR file with a
the top-level directory of the JAR file (or overridden by a versioned
entry in a
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 created as an automatic module. The components
for the automatic module are derived as follows:
.jar suffix is removed.
If the name matches the regular expression
"-(\\d+(\\.|$))" then the module name will be derived from the
subsequence preceding 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
For the module name, then any trailing digits and dots
are removed, all non-alphanumeric characters (
are replaced with a dot (
"."), all repeating dots are
replaced with one dot, and all leading and trailing dots are
As an example, a JAR file named
derive a module name
foo.bar and no version. A JAR file
foo-1.2.3-SNAPSHOT.jar will derive a module name
1.2.3-SNAPSHOT as the version.
The set of packages in the module is derived from the
non-directory entries in the JAR file that have names ending in
.class". A candidate package name is derived from the name
using the characters up to, but not including, the last forward slash.
All remaining forward slashes are replaced with dot (
the resulting string is a legal package name then it is assumed to be
a package name. For example, if the JAR file contains the entry
p/q/Foo.class" then the package name derived is
The contents of entries starting with
META-INF/services/ are assumed to be service configuration files
ServiceLoader). If the name of a file
META-INF/services/) is a legal class name
then it is assumed to be the fully-qualified class name of a service
type. The entries in the file are assumed to be the fully-qualified
class names of provider classes.
If the JAR file has a
Main-Class attribute in its
main manifest then its value is the module
ModuleDescriptor cannot be created (by means of the
ModuleDescriptor.Builder API) for an
automatic module then
FindException is thrown. This can arise
when a legal module name cannot be derived from the file name of the JAR
file, where the JAR file contains a
.class in the top-level
directory of the JAR file, where an entry in a service configuration
file is not a legal class name or its package name is not in the set of
packages derived for the module, or where the module main class is not
a legal class name or its package is not in the module.
In addition to JAR files, an implementation may also support modules
that are packaged in other implementation specific module formats. If
an element in the array specified to this method is a path to a directory
of modules then entries in the directory that not recognized as modules
are ignored. If an element in the array is a path to a packaged module
that is not recognized then a
FindException is thrown when the
file is encountered. 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 (other than
module-info.class) is found in the top-level directory then it is
assumed to be a class in the unnamed package and so
Finders created by this method are lazy and do not eagerly check
that the given file paths are directories or packaged modules.
findAll methods will only
fail if invoking these methods results in searching a directory or
packaged module and an error is encountered.
entries - A possibly-empty array of paths to directories of modules
or paths to packaged or exploded modules
ModuleFinder that locates modules on the file system
static ModuleFinder compose(ModuleFinder... finders)
find method of the resulting
module finder will locate a module by invoking the
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
findAll methods of the underlying module finders
will be propagated to the caller of the resulting module finder's
finders - The array of module finders
ModuleFinder that composes a sequence of module finders
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.