/* * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.lang.module; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.security.AccessController; import java.security.Permission; import java.security.PrivilegedAction; import java.util.Collections; import java.util.HashMap; import java.util.HashSet; import java.util.List; import java.util.Map; import java.util.Objects; import java.util.Optional; import java.util.Set; import jdk.internal.module.ModuleBootstrap; import jdk.internal.module.ModulePatcher; import jdk.internal.module.ModulePath; import jdk.internal.module.SystemModuleFinder; /** * A finder of modules. A {@code ModuleFinder} is used to find modules during * resolution or * service binding. * *

A {@code ModuleFinder} can only find one module with a given name. A * {@code 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:

* * 
{@code
 *     Path dir1, dir2, dir3;
 *
 *     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
 *
 *     Optional omref = finder.find("jdk.foo");
 *     omref.ifPresent(mref -> ... );
 *
 * }
* *

The {@link #find(String) find} and {@link #findAll() findAll} methods * defined here can fail for several reasons. These include I/O errors, errors * detected parsing a module descriptor ({@code module-info.class}), or in the * case of {@code ModuleFinder} returned by {@link #of 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 {@link FindException * FindException} with an appropriate {@link Throwable#getCause cause}. * The behavior of a {@code ModuleFinder} after a {@code FindException} is * thrown is undefined. For example, invoking {@code 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 {@code ModuleFinder} is not required to be thread safe.

* * @since 9 * @spec JPMS */ public interface ModuleFinder { /** * Finds a reference to a module of a given name. * *

A {@code ModuleFinder} provides a consistent view of the * modules that it locates. If {@code 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 {@link #findAll() findAll} * method.

* * @param name * The name of the module to find * * @return A reference to a module with the given name or an empty * {@code Optional} if not found * * @throws FindException * If an error occurs finding the module * * @throws SecurityException * If denied by the security manager */ Optional find(String name); /** * Returns the set of all module references that this finder can locate. * *

A {@code ModuleFinder} provides a consistent view of the modules * that it locates. If {@link #findAll() findAll} is invoked several times * then it will return the same (equals) result each time. For each {@code * ModuleReference} element in the returned set then it is guaranteed that * {@link #find find} will locate the {@code ModuleReference} if invoked * to find that module.

* * @apiNote This is important to have for methods such as {@link * Configuration#resolveAndBind resolveAndBind} that need to scan the * module path to find modules that provide a specific service. * * @return The set of all module references that this finder locates * * @throws FindException * If an error occurs finding all modules * * @throws SecurityException * If denied by the security manager */ Set findAll(); /** * Returns a module finder that locates the system modules. The * system modules are the modules in the Java run-time image. * The module finder will always find {@code java.base}. * *

If there is a security manager set then its {@link * SecurityManager#checkPermission(Permission) checkPermission} method is * invoked to check that the caller has been granted * {@link RuntimePermission RuntimePermission("accessSystemModules")} * to access the system modules.

* * @return A {@code ModuleFinder} that locates the system modules * * @throws SecurityException * If denied by the security manager */ static ModuleFinder ofSystem() { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new RuntimePermission("accessSystemModules")); PrivilegedAction pa = ModuleFinder::privilegedOfSystem; return AccessController.doPrivileged(pa); } else { return privilegedOfSystem(); } } /** * Returns a module finder that locates the system modules. This method * assumes it has permissions to access the runtime image. */ private static ModuleFinder privilegedOfSystem() { String home = System.getProperty("java.home"); Path modules = Paths.get(home, "lib", "modules"); if (Files.isRegularFile(modules)) { return SystemModuleFinder.getInstance(); } else { Path dir = Paths.get(home, "modules"); if (Files.isDirectory(dir)) { return privilegedOf(ModuleBootstrap.patcher(), dir); } else { throw new InternalError("Unable to detect the run-time image"); } } } /** * Returns a module finder that locates the system modules in an exploded * image. The image may be patched. */ private static ModuleFinder privilegedOf(ModulePatcher patcher, Path dir) { ModuleFinder finder = ModulePath.of(patcher, dir); return new ModuleFinder() { @Override public Optional find(String name) { PrivilegedAction> pa = () -> finder.find(name); return AccessController.doPrivileged(pa); } @Override public Set findAll() { PrivilegedAction> pa = finder::findAll; return AccessController.doPrivileged(pa); } }; } /** * 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. *

  2. A path to the top-level directory of an * exploded module.

    3. *

  3. A path to a packaged module.

    4. *
* * 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. It is 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 {@code 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 {@code module-info.class} in * the top-level directory of the JAR file (or overridden by a versioned * entry in a {@link java.util.jar.JarFile#isMultiRelease() multi-release} * JAR file) is a modular JAR and is an explicit module. * A JAR file that does not have a {@code module-info.class} in the * top-level directory is created as an automatic module. The components * for the automatic module are derived as follows: * *

    * *

  • The module {@link ModuleDescriptor#name() name}, and {@link * ModuleDescriptor#version() version} if applicable, is derived from * the file name of the JAR file as follows:

    * *
      * *

    • The {@code .jar} suffix is removed.

      • * *

    • If the name matches the regular expression {@code * "-(\\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 {@link * ModuleDescriptor.Version} and ignored if it cannot be parsed as * a {@code Version}.

      • * *

    • For the module name, then any trailing digits and dots * are removed, all non-alphanumeric characters ({@code [^A-Za-z0-9]}) * are replaced with a dot ({@code "."}), all repeating dots are * replaced with one dot, and all leading and trailing dots are * removed.

      • * *

    • As an example, a JAR file named {@code foo-bar.jar} will * derive a module name {@code foo.bar} and no version. A JAR file * named {@code foo-1.2.3-SNAPSHOT.jar} will derive a module name * {@code foo} and {@code 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 * "{@code .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 ({@code "."}). If * 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 * "{@code p/q/Foo.class}" then the package name derived is * "{@code p.q}".

    • * *

  • The contents of entries starting with {@code * META-INF/services/} are assumed to be service configuration files * (see {@link java.util.ServiceLoader}). If the name of a file * (that follows {@code 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 {@code Main-Class} attribute in its * main manifest then its value is the module {@link * ModuleDescriptor#mainClass() main class}.

    • * *
* *

If a {@code ModuleDescriptor} cannot be created (by means of the * {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an * automatic module then {@code 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 {@code .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 {@code 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 {@code .class} file (other than {@code * module-info.class}) is found in the top-level directory then it is * assumed to be a class in the unnamed package and so {@code 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 {@code find} or {@code findAll} methods will only * fail if invoking these methods results in searching a directory or * packaged module and an error is encountered.

* * @param entries * A possibly-empty array of paths to directories of modules * or paths to packaged or exploded modules * * @return A {@code ModuleFinder} that locates modules on the file system */ static ModuleFinder of(Path... entries) { // special case zero entries if (entries.length == 0) { return new ModuleFinder() { @Override public Optional find(String name) { Objects.requireNonNull(name); return Optional.empty(); } @Override public Set findAll() { return Collections.emptySet(); } }; } return ModulePath.of(entries); } /** * Returns a module finder that is composed from a sequence of zero or more * module finders. The {@link #find(String) find} method of the resulting * module finder will locate a module by invoking the {@code find} method * of each module finder, in array index order, until either the module is * found or all module finders have been searched. The {@link #findAll() * 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 * {@code find} or {@code findAll} methods of the underlying module finders * will be propagated to the caller of the resulting module finder's * {@code find} or {@code findAll} methods.

* * @param finders * The array of module finders * * @return A {@code ModuleFinder} that composes a sequence of module finders */ static ModuleFinder compose(ModuleFinder... finders) { // copy the list and check for nulls final List finderList = List.of(finders); return new ModuleFinder() { private final Map nameToModule = new HashMap<>(); private Set allModules; @Override public Optional find(String name) { // cached? ModuleReference mref = nameToModule.get(name); if (mref != null) return Optional.of(mref); Optional omref = finderList.stream() .map(f -> f.find(name)) .flatMap(Optional::stream) .findFirst(); omref.ifPresent(m -> nameToModule.put(name, m)); return omref; } @Override public Set findAll() { if (allModules != null) return allModules; // seed with modules already found Set result = new HashSet<>(nameToModule.values()); finderList.stream() .flatMap(f -> f.findAll().stream()) .forEach(mref -> { String name = mref.descriptor().name(); if (nameToModule.putIfAbsent(name, mref) == null) { result.add(mref); } }); allModules = Collections.unmodifiableSet(result); return allModules; } }; } }