1 /*
2 * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.module;
27
28 import java.io.File;
29 import java.io.FilePermission;
30 import java.nio.file.Files;
31 import java.nio.file.Path;
32 import java.nio.file.Paths;
33 import java.security.AccessController;
34 import java.security.Permission;
35 import java.security.PrivilegedAction;
36 import java.util.Collections;
37 import java.util.HashMap;
38 import java.util.HashSet;
39 import java.util.List;
40 import java.util.Map;
41 import java.util.Objects;
42 import java.util.Optional;
43 import java.util.Set;
44
45 import sun.security.action.GetPropertyAction;
46
47 /**
48 * A finder of modules. A {@code ModuleFinder} is used to find modules during
49 * <a href="Configuration.html#resolution">resolution</a> or
50 * <a href="Configuration.html#servicebinding">service binding</a>.
51 *
52 * <p> A {@code ModuleFinder} can only find one module with a given name. A
53 * {@code ModuleFinder} that finds modules in a sequence of directories, for
54 * example, will locate the first occurrence of a module of a given name and
55 * will ignore other modules of that name that appear in directories later in
56 * the sequence. </p>
57 *
58 * <p> Example usage: </p>
59 *
60 * <pre>{@code
61 * Path dir1, dir2, dir3;
62 *
63 * ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
64 *
65 * Optional<ModuleReference> omref = finder.find("jdk.foo");
66 * omref.ifPresent(mref -> ... );
67 *
68 * }</pre>
69 *
70 * <p> The {@link #find(String) find} and {@link #findAll() findAll} methods
71 * defined here can fail for several reasons. These include I/O errors, errors
72 * detected parsing a module descriptor ({@code module-info.class}), or in the
73 * case of {@code ModuleFinder} returned by {@link #of ModuleFinder.of}, that
74 * two or more modules with the same name are found in a directory.
75 * When an error is detected then these methods throw {@link FindException
76 * FindException} with an appropriate {@link Throwable#getCause cause}.
77 * The behavior of a {@code ModuleFinder} after a {@code FindException} is
78 * thrown is undefined. For example, invoking {@code find} after an exception
79 * is thrown may or may not scan the same modules that lead to the exception.
80 * It is recommended that a module finder be discarded after an exception is
81 * thrown. </p>
82 *
83 * <p> A {@code ModuleFinder} is not required to be thread safe. </p>
84 *
85 * @since 9
86 */
87
88 public interface ModuleFinder {
89
90 /**
91 * Finds a reference to a module of a given name.
92 *
93 * <p> A {@code ModuleFinder} provides a consistent view of the
94 * modules that it locates. If {@code find} is invoked several times to
95 * locate the same module (by name) then it will return the same result
96 * each time. If a module is located then it is guaranteed to be a member
97 * of the set of modules returned by the {@link #findAll() findAll}
98 * method. </p>
99 *
100 * @param name
101 * The name of the module to find
102 *
103 * @return A reference to a module with the given name or an empty
104 * {@code Optional} if not found
105 *
106 * @throws FindException
107 * If an error occurs finding the module
108 *
109 * @throws SecurityException
110 * If denied by the security manager
111 */
112 Optional<ModuleReference> find(String name);
113
114 /**
115 * Returns the set of all module references that this finder can locate.
116 *
117 * <p> A {@code ModuleFinder} provides a consistent view of the modules
118 * that it locates. If {@link #findAll() findAll} is invoked several times
119 * then it will return the same (equals) result each time. For each {@code
120 * ModuleReference} element in the returned set then it is guaranteed that
121 * {@link #find find} will locate the {@code ModuleReference} if invoked
122 * to find that module. </p>
123 *
124 * @apiNote This is important to have for methods such as {@link
125 * Configuration#resolveRequiresAndUses resolveRequiresAndUses} that need
126 * to scan the module path to find modules that provide a specific service.
127 *
128 * @return The set of all module references that this finder locates
129 *
130 * @throws FindException
131 * If an error occurs finding all modules
132 *
133 * @throws SecurityException
134 * If denied by the security manager
135 */
136 Set<ModuleReference> findAll();
137
138 /**
139 * Returns a module finder that locates the <em>system modules</em>. The
140 * system modules are typically linked into the Java run-time image.
141 * The module finder will always find {@code java.base}.
142 *
143 * <p> If there is a security manager set then its {@link
144 * SecurityManager#checkPermission(Permission) checkPermission} method is
145 * invoked to check that the caller has been granted {@link FilePermission}
146 * to recursively read the directory that is the value of the system
147 * property {@code java.home}. </p>
148 *
149 * @return A {@code ModuleFinder} that locates the system modules
150 *
151 * @throws SecurityException
152 * If denied by the security manager
153 */
154 static ModuleFinder ofSystem() {
155 String home;
156
157 SecurityManager sm = System.getSecurityManager();
158 if (sm != null) {
159 PrivilegedAction<String> pa = new GetPropertyAction("java.home");
160 home = AccessController.doPrivileged(pa);
161 Permission p = new FilePermission(home + File.separator + "-", "read");
162 sm.checkPermission(p);
163 } else {
164 home = System.getProperty("java.home");
165 }
166
167 Path modules = Paths.get(home, "lib", "modules");
168 if (Files.isRegularFile(modules)) {
169 return new SystemModuleFinder();
170 } else {
171 Path mlib = Paths.get(home, "modules");
172 if (Files.isDirectory(mlib)) {
173 return of(mlib);
174 } else {
175 throw new InternalError("Unable to detect the run-time image");
176 }
177 }
178 }
179
180 /**
181 * Returns a module finder that locates modules on the file system by
182 * searching a sequence of directories and/or packaged modules.
183 *
184 * Each element in the given array is one of:
185 * <ol>
186 * <li><p> A path to a directory of modules.</p></li>
187 * <li><p> A path to the <em>top-level</em> directory of an
188 * <em>exploded module</em>. </p></li>
189 * <li><p> A path to a <em>packaged module</em>. </p></li>
190 * </ol>
191 *
192 * The module finder locates modules by searching each directory, exploded
193 * module, or packaged module in array index order. It finds the first
194 * occurrence of a module with a given name and ignores other modules of
195 * that name that appear later in the sequence.
196 *
197 * <p> If an element is a path to a directory of modules then each entry in
198 * the directory is a packaged module or the top-level directory of an
199 * exploded module. The module finder's {@link #find(String) find} or
200 * {@link #findAll() findAll} methods throw {@link FindException} if a
201 * directory containing more than one module with the same name is
202 * encountered. </p>
203 *
204 * <p> If an element in the array is a path to a directory, and that
205 * directory contains a file named {@code module-info.class}, then the
206 * directory is treated as an exploded module rather than a directory of
207 * modules. </p>
208 *
209 * <p> The module finder returned by this method supports modules that are
210 * packaged as JAR files. A JAR file with a {@code module-info.class} in
211 * the top-level directory of the JAR file (or overridden by a versioned
212 * entry in a {@link java.util.jar.JarFile#isMultiRelease() multi-release}
213 * JAR file) is a modular JAR and is an <em>explicit module</em>.
214 * A JAR file that does not have a {@code module-info.class} in the
215 * top-level directory is an {@link ModuleDescriptor#isAutomatic automatic}
216 * module. The {@link ModuleDescriptor} for an automatic module is created as
217 * follows:
218 *
219 * <ul>
220 *
221 * <li><p> The module {@link ModuleDescriptor#name() name}, and {@link
222 * ModuleDescriptor#version() version} if applicable, is derived from
223 * the file name of the JAR file as follows: </p>
224 *
225 * <ul>
226 *
227 * <li><p> The {@code .jar} suffix is removed. </p></li>
228 *
229 * <li><p> If the name matches the regular expression {@code
230 * "-(\\d+(\\.|$))"} then the module name will be derived from the
231 * subsequence proceeding the hyphen of the first occurrence. The
232 * subsequence after the hyphen is parsed as a {@link
233 * ModuleDescriptor.Version} and ignored if it cannot be parsed as
234 * a {@code Version}. </p></li>
235 *
236 * <li><p> For the module name, then all non-alphanumeric
237 * characters ({@code [^A-Za-z0-9])} are replaced with a dot
238 * ({@code "."}), all repeating dots are replaced with one dot,
239 * and all leading and trailing dots are removed. </p></li>
240 *
241 * <li><p> As an example, a JAR file named {@code foo-bar.jar} will
242 * derive a module name {@code foo.bar} and no version. A JAR file
243 * named {@code foo-1.2.3-SNAPSHOT.jar} will derive a module name
244 * {@code foo} and {@code 1.2.3-SNAPSHOT} as the version. </p></li>
245 *
246 * </ul></li>
247 *
248 * <li><p> It {@link ModuleDescriptor#requires() requires} {@code
249 * java.base}. </p></li>
250 *
251 * <li><p> All entries in the JAR file with names ending with {@code
252 * .class} are assumed to be class files where the name corresponds
253 * to the fully qualified name of the class. The packages of all
254 * classes are {@link ModuleDescriptor#exports() exported}. </p></li>
255 *
256 * <li><p> The contents of all entries starting with {@code
257 * META-INF/services/} are assumed to be service configuration files
258 * (see {@link java.util.ServiceLoader}). The name of the file
259 * (that follows {@code META-INF/services/}) is assumed to be the
260 * fully-qualified binary name of a service type. The entries in the
261 * file are assumed to be the fully-qualified binary names of
262 * provider classes. </p></li>
263 *
264 * <li><p> If the JAR file has a {@code Main-Class} attribute in its
265 * main manifest then its value is the {@link
266 * ModuleDescriptor#mainClass() main class}. </p></li>
267 *
268 * </ul>
269 *
270 * <p> If a {@code ModuleDescriptor} cannot be created (by means of the
271 * {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an
272 * automatic module then {@code FindException} is thrown. This can arise,
273 * for example, when a legal Java identifier name cannot be derived from
274 * the file name of the JAR file or where a package name derived from an
275 * entry ending with {@code .class} is not a legal Java identifier. </p>
276 *
277 * <p> In addition to JAR files, an implementation may also support modules
278 * that are packaged in other implementation specific module formats. When
279 * a file is encountered that is not recognized as a packaged module then
280 * {@code FindException} is thrown. An implementation may choose to ignore
281 * some files, {@link java.nio.file.Files#isHidden hidden} files for
282 * example. Paths to files that do not exist are always ignored. </p>
283 *
284 * <p> As with automatic modules, the contents of a packaged or exploded
285 * module may need to be <em>scanned</em> in order to determine the packages
286 * in the module. If a {@code .class} file that corresponds to a class in an
287 * unnamed package is encountered then {@code FindException} is thrown. </p>
288 *
289 * <p> Finders created by this method are lazy and do not eagerly check
290 * that the given file paths are directories or packaged modules.
291 * Consequently, the {@code find} or {@code findAll} methods will only
292 * fail if invoking these methods results in searching a directory or
293 * packaged module and an error is encountered. </p>
294 *
295 * @param entries
296 * A possibly-empty array of paths to directories of modules
297 * or paths to packaged or exploded modules
298 *
299 * @return A {@code ModuleFinder} that locates modules on the file system
300 */
301 static ModuleFinder of(Path... entries) {
302 // special case zero entries
303 if (entries.length == 0) {
304 return new ModuleFinder() {
305 @Override
306 public Optional<ModuleReference> find(String name) {
307 Objects.requireNonNull(name);
308 return Optional.empty();
309 }
310
311 @Override
312 public Set<ModuleReference> findAll() {
313 return Collections.emptySet();
314 }
315 };
316 }
317
318 return new ModulePath(entries);
319 }
320
321 /**
322 * Returns a module finder that is composed from a sequence of zero or more
323 * module finders. The {@link #find(String) find} method of the resulting
324 * module finder will locate a module by invoking the {@code find} method
325 * of each module finder, in array index order, until either the module is
326 * found or all module finders have been searched. The {@link #findAll()
327 * findAll} method of the resulting module finder will return a set of
328 * modules that includes all modules located by the first module finder.
329 * The set of modules will include all modules located by the second or
330 * subsequent module finder that are not located by previous module finders
331 * in the sequence.
332 *
333 * <p> When locating modules then any exceptions or errors thrown by the
334 * {@code find} or {@code findAll} methods of the underlying module finders
335 * will be propogated to the caller of the resulting module finder's
336 * {@code find} or {@code findAll} methods. </p>
337 *
338 * @param finders
339 * The array of module finders
340 *
341 * @return A {@code ModuleFinder} that composes a sequence of module finders
342 */
343 static ModuleFinder compose(ModuleFinder... finders) {
344 // make a copy since it's captured by the ModuleFinder instance below
345 final List<ModuleFinder> finderList = List.of(finders);
346
347 return new ModuleFinder() {
348 private final Map<String, ModuleReference> nameToModule = new HashMap<>();
349 private Set<ModuleReference> allModules;
350
351 @Override
352 public Optional<ModuleReference> find(String name) {
353 // cached?
354 ModuleReference mref = nameToModule.get(name);
355 if (mref != null)
356 return Optional.of(mref);
357 Optional<ModuleReference> omref = finderList.stream()
358 .map(f -> f.find(name))
359 .flatMap(Optional::stream)
360 .findFirst();
361 omref.ifPresent(m -> nameToModule.put(name, m));
362 return omref;
363 }
364
365 @Override
366 public Set<ModuleReference> findAll() {
367 if (allModules != null)
368 return allModules;
369 // seed with modules already found
370 Set<ModuleReference> result = new HashSet<>(nameToModule.values());
371 finderList.stream()
372 .flatMap(f -> f.findAll().stream())
373 .forEach(mref -> {
374 String name = mref.descriptor().name();
375 if (nameToModule.putIfAbsent(name, mref) == null) {
376 result.add(mref);
377 }
378 });
379 allModules = Collections.unmodifiableSet(result);
380 return allModules;
381 }
382 };
383 }
384
385 }