/* * Copyright (c) 2014, 2016, 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.io.File; import java.io.FilePermission; 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.Objects; import java.util.Optional; import java.util.Set; import java.util.stream.Collectors; import java.util.stream.Stream; import sun.security.action.GetPropertyAction; /** * 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"); * if (omref.isPresent()) { ... } * * }
The {@link #find(String) find} and {@link #findAll() findAll} methods * defined here can fail for several reasons. These include 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 */ 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 */ OptionalA {@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#resolveRequiresAndUses resolveRequiresAndUses} 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 */ SetIf 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 FilePermission} * to recursively read the directory that is the value of the system * property {@code java.home}.
* * @return A {@code ModuleFinder} that locates the system modules * * @throws SecurityException * If denied by the security manager */ static ModuleFinder ofSystem() { String home; SecurityManager sm = System.getSecurityManager(); if (sm != null) { PrivilegedActionA 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. The module finder's {@link #find(String) find} or * {@link #findAll() findAll} methods throw {@link 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 {@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 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 an {@link * ModuleDescriptor#isAutomatic automatic} module. The {@link * ModuleDescriptor} for an automatic module is created 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 proceeding 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 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.
It {@link ModuleDescriptor#requires() requires} {@code * java.base}.
All entries in the JAR file with names ending with {@code * .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 {@link ModuleDescriptor#exports() exported}.
The contents of all entries starting with {@code * META-INF/services/} are assumed to be service configuration files * (see {@link java.util.ServiceLoader}). The name of the file * (that follows {@code 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 {@code Main-Class} attribute in its * main manifest then its value is the {@link * ModuleDescriptor#mainClass() 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 {@code .class} file that corresponds to a class in an * unnamed package is encountered then {@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. Paths to files that do not * exist are ignored.
* * @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) { return new ModulePath(entries); } /** * Returns a module finder that is the equivalent to composing two * module finders. The resulting finder will locate modules references * using {@code first}; if not found then it will attempt to locate module * references using {@code second}. * *The {@link #findAll() 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.
* * @apiNote This method will eventually be changed to take a sequence of * module finders. * * @param first * The first module finder * @param second * The second module finder * * @return A {@code ModuleFinder} that composes two module finders */ static ModuleFinder compose(ModuleFinder first, ModuleFinder second) { Objects.requireNonNull(first); Objects.requireNonNull(second); return new ModuleFinder() { Set