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.Objects;
38 import java.util.Optional;
39 import java.util.Set;
40 import java.util.stream.Collectors;
41 import java.util.stream.Stream;
42 import sun.security.action.GetPropertyAction;
43
44 /**
45 * A finder of modules. A {@code ModuleFinder} is used to find modules during
46 * <a href="Configuration.html#resolution">resolution</a> or
47 * <a href="Configuration.html#servicebinding">service binding</a>.
48 *
49 * <p> A {@code ModuleFinder} can only find one module with a given name. A
50 * {@code ModuleFinder} that finds modules in a sequence of directories, for
51 * example, will locate the first occurrence of a module of a given name and
52 * will ignore other modules of that name that appear in directories later in
53 * the sequence. </p>
54 *
55 * <p> Example usage: </p>
56 *
57 * <pre>{@code
58 * Path dir1, dir2, dir3;
59 *
60 * ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
61 *
62 * Optional<ModuleReference> omref = finder.find("jdk.foo");
63 * if (omref.isPresent()) { ... }
64 *
65 * }</pre>
66 *
67 * <p> The {@link #find(String) find} and {@link #findAll() findAll} methods
68 * defined here can fail for several reasons. These include include I/O errors,
69 * errors detected parsing a module descriptor ({@code module-info.class}), or
70 * in the case of {@code ModuleFinder} returned by {@link #of ModuleFinder.of},
71 * that two or more modules with the same name are found in a directory.
72 * When an error is detected then these methods throw {@link FindException
73 * FindException} with an appropriate {@link Throwable#getCause cause}.
74 * The behavior of a {@code ModuleFinder} after a {@code FindException} is
75 * thrown is undefined. For example, invoking {@code find} after an exception
76 * is thrown may or may not scan the same modules that lead to the exception.
77 * It is recommended that a module finder be discarded after an exception is
78 * thrown. </p>
79 *
80 * <p> A {@code ModuleFinder} is not required to be thread safe. </p>
81 *
82 * @since 9
83 */
84
85 public interface ModuleFinder {
86
87 /**
88 * Finds a reference to a module of a given name.
89 *
90 * <p> A {@code ModuleFinder} provides a consistent view of the
91 * modules that it locates. If {@code find} is invoked several times to
92 * locate the same module (by name) then it will return the same result
93 * each time. If a module is located then it is guaranteed to be a member
94 * of the set of modules returned by the {@link #findAll() findAll}
95 * method. </p>
96 *
97 * @param name
98 * The name of the module to find
99 *
100 * @return A reference to a module with the given name or an empty
101 * {@code Optional} if not found
102 *
103 * @throws FindException
104 * If an error occurs finding the module
105 *
106 * @throws SecurityException
107 * If denied by the security manager
108 */
109 Optional<ModuleReference> find(String name);
110
111 /**
112 * Returns the set of all module references that this finder can locate.
113 *
114 * <p> A {@code ModuleFinder} provides a consistent view of the modules
115 * that it locates. If {@link #findAll() findAll} is invoked several times
116 * then it will return the same (equals) result each time. For each {@code
117 * ModuleReference} element in the returned set then it is guaranteed that
118 * {@link #find find} will locate the {@code ModuleReference} if invoked
119 * to find that module. </p>
120 *
121 * @apiNote This is important to have for methods such as {@link
122 * Configuration#resolveRequiresAndUses resolveRequiresAndUses} that need
123 * to scan the module path to find modules that provide a specific service.
124 *
125 * @return The set of all module references that this finder locates
126 *
127 * @throws FindException
128 * If an error occurs finding all modules
129 *
130 * @throws SecurityException
131 * If denied by the security manager
132 */
133 Set<ModuleReference> findAll();
134
135 /**
136 * Returns a module finder that locates the <em>system modules</em>. The
137 * system modules are typically linked into the Java run-time image.
138 * The module finder will always find {@code java.base}.
139 *
140 * <p> If there is a security manager set then its {@link
141 * SecurityManager#checkPermission(Permission) checkPermission} method is
142 * invoked to check that the caller has been granted {@link FilePermission}
143 * to recursively read the directory that is the value of the system
144 * property {@code java.home}. </p>
145 *
146 * @return A {@code ModuleFinder} that locates the system modules
147 *
148 * @throws SecurityException
149 * If denied by the security manager
150 */
151 static ModuleFinder ofSystem() {
152 String home;
153
154 SecurityManager sm = System.getSecurityManager();
155 if (sm != null) {
156 PrivilegedAction<String> pa = new GetPropertyAction("java.home");
157 home = AccessController.doPrivileged(pa);
158 Permission p = new FilePermission(home + File.separator + "-", "read");
159 sm.checkPermission(p);
160 } else {
161 home = System.getProperty("java.home");
162 }
163
164 Path modules = Paths.get(home, "lib", "modules");
165 if (Files.isRegularFile(modules)) {
166 return new SystemModuleFinder();
167 } else {
168 Path mlib = Paths.get(home, "modules");
169 if (Files.isDirectory(mlib)) {
170 return of(mlib);
171 } else {
172 throw new InternalError("Unable to detect the run-time image");
173 }
174 }
175 }
176
177 /**
178 * Returns a module finder that locates modules on the file system by
179 * searching a sequence of directories and/or packaged modules.
180 *
181 * Each element in the given array is one of:
182 * <ol>
183 * <li><p> A path to a directory of modules.</p></li>
184 * <li><p> A path to the <em>top-level</em> directory of an
185 * <em>exploded module</em>. </p></li>
186 * <li><p> A path to a <em>packaged module</em>. </p></li>
187 * </ol>
188 *
189 * The module finder locates modules by searching each directory, exploded
190 * module, or packaged module in array index order. It finds the first
191 * occurrence of a module with a given name and ignores other modules of
192 * that name that appear later in the sequence.
193 *
194 * <p> If an element is a path to a directory of modules then each entry in
195 * the directory is a packaged module or the top-level directory of an
196 * exploded module. The module finder's {@link #find(String) find} or
197 * {@link #findAll() findAll} methods throw {@link FindException} if a
198 * directory containing more than one module with the same name is
199 * encountered. </p>
200 *
201 * <p> If an element in the array is a path to a directory, and that
202 * directory contains a file named {@code module-info.class}, then the
203 * directory is treated as an exploded module rather than a directory of
204 * modules. </p>
205 *
206 * <p> The module finder returned by this method supports modules that are
207 * packaged as JAR files. A JAR file with a {@code module-info.class} in
208 * the top-level directory of the JAR file is a modular JAR and is an
209 * <em>explicit module</em>. A JAR file that does not have a {@code
210 * module-info.class} in the top-level directory is an {@link
211 * ModuleDescriptor#isAutomatic automatic} module. The {@link
212 * ModuleDescriptor} for an automatic module is created as follows:
213 *
214 * <ul>
215 *
216 * <li><p> The module {@link ModuleDescriptor#name() name}, and {@link
217 * ModuleDescriptor#version() version} if applicable, is derived from
218 * the file name of the JAR file as follows: </p>
219 *
220 * <ul>
221 *
222 * <li><p> The {@code .jar} suffix is removed. </p></li>
223 *
224 * <li><p> If the name matches the regular expression {@code
225 * "-(\\d+(\\.|$))"} then the module name will be derived from the
226 * subsequence proceeding the hyphen of the first occurrence. The
227 * subsequence after the hyphen is parsed as a {@link
228 * ModuleDescriptor.Version} and ignored if it cannot be parsed as
229 * a {@code Version}. </p></li>
230 *
231 * <li><p> For the module name, then all non-alphanumeric
232 * characters ({@code [^A-Za-z0-9])} are replaced with a dot
233 * ({@code "."}), all repeating dots are replaced with one dot,
234 * and all leading and trailing dots are removed. </p></li>
235 *
236 * <li><p> As an example, a JAR file named {@code foo-bar.jar} will
237 * derive a module name {@code foo.bar} and no version. A JAR file
238 * named {@code foo-1.2.3-SNAPSHOT.jar} will derive a module name
239 * {@code foo} and {@code 1.2.3-SNAPSHOT} as the version. </p></li>
240 *
241 * </ul></li>
242 *
243 * <li><p> It {@link ModuleDescriptor#requires() requires} {@code
244 * java.base}. </p></li>
245 *
246 * <li><p> All entries in the JAR file with names ending with {@code
247 * .class} are assumed to be class files where the name corresponds
248 * to the fully qualified name of the class. The packages of all
249 * classes are {@link ModuleDescriptor#exports() exported}. </p></li>
250 *
251 * <li><p> The contents of all entries starting with {@code
252 * META-INF/services/} are assumed to be service configuration files
253 * (see {@link java.util.ServiceLoader}). The name of the file
254 * (that follows {@code META-INF/services/}) is assumed to be the
255 * fully-qualified binary name of a service type. The entries in the
256 * file are assumed to be the fully-qualified binary names of
257 * provider classes. </p></li>
258 *
259 * <li><p> If the JAR file has a {@code Main-Class} attribute in its
260 * main manifest then its value is the {@link
261 * ModuleDescriptor#mainClass() main class}. </p></li>
262 *
263 * </ul>
264 *
265 * <p> In addition to JAR files, an implementation may also support modules
266 * that are packaged in other implementation specific module formats. As
267 * with automatic modules, the contents of a packaged or exploded module
268 * may need to be <em>scanned</em> in order to determine the packages in
269 * the module. If a {@code .class} file that corresponds to a class in an
270 * unnamed package is encountered then {@code FindException} is thrown. </p>
271 *
272 * <p> Finders created by this method are lazy and do not eagerly check
273 * that the given file paths are directories or packaged modules.
274 * Consequently, the {@code find} or {@code findAll} methods will only
275 * fail if invoking these methods results in searching a directory or
276 * packaged module and an error is encountered. Paths to files that do not
277 * exist are ignored. </p>
278 *
279 * @param entries
280 * A possibly-empty array of paths to directories of modules
281 * or paths to packaged or exploded modules
282 *
283 * @return A {@code ModuleFinder} that locates modules on the file system
284 */
285 static ModuleFinder of(Path... entries) {
286 return new ModulePath(entries);
287 }
288
289 /**
290 * Returns a module finder that is the equivalent to composing two
291 * module finders. The resulting finder will locate modules references
292 * using {@code first}; if not found then it will attempt to locate module
293 * references using {@code second}.
294 *
295 * <p> The {@link #findAll() findAll} method of the resulting module finder
296 * will locate all modules located by the first module finder. It will
297 * also locate all modules located by the second module finder that are not
298 * located by the first module finder. </p>
299 *
300 * @apiNote This method will eventually be changed to take a sequence of
301 * module finders.
302 *
303 * @param first
304 * The first module finder
305 * @param second
306 * The second module finder
307 *
308 * @return A {@code ModuleFinder} that composes two module finders
309 */
310 static ModuleFinder compose(ModuleFinder first, ModuleFinder second) {
311 Objects.requireNonNull(first);
312 Objects.requireNonNull(second);
313
314 return new ModuleFinder() {
315 Set<ModuleReference> allModules;
316
317 @Override
318 public Optional<ModuleReference> find(String name) {
319 Optional<ModuleReference> om = first.find(name);
320 if (!om.isPresent())
321 om = second.find(name);
322 return om;
323 }
324 @Override
325 public Set<ModuleReference> findAll() {
326 if (allModules == null) {
327 allModules = Stream.concat(first.findAll().stream(),
328 second.findAll().stream())
329 .map(a -> a.descriptor().name())
330 .distinct()
331 .map(this::find)
332 .map(Optional::get)
333 .collect(Collectors.toSet());
334 }
335 return allModules;
336 }
337 };
338 }
339
340 /**
341 * Returns an empty module finder. The empty finder does not find any
342 * modules.
343 *
344 * @apiNote This is useful when using methods such as {@link
345 * Configuration#resolveRequires resolveRequires} where two finders are
346 * specified. An alternative is {@code ModuleFinder.of()}.
347 *
348 * @return A {@code ModuleFinder} that does not find any modules
349 */
350 static ModuleFinder empty() {
351 // an alternative implementation of ModuleFinder.of()
352 return new ModuleFinder() {
353 @Override public Optional<ModuleReference> find(String name) {
354 Objects.requireNonNull(name);
355 return Optional.empty();
356 }
357 @Override public Set<ModuleReference> findAll() {
358 return Collections.emptySet();
359 }
360 };
361 }
362
363 }