1 /* 2 * Copyright (c) 2014, 2017, 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.nio.file.Path; 29 import java.security.AccessController; 30 import java.security.Permission; 31 import java.security.PrivilegedAction; 32 import java.util.Collections; 33 import java.util.HashMap; 34 import java.util.HashSet; 35 import java.util.List; 36 import java.util.Map; 37 import java.util.Objects; 38 import java.util.Optional; 39 import java.util.Set; 40 41 import jdk.internal.module.ModulePath; 42 import jdk.internal.module.SystemModuleFinders; 43 44 /** 45 * A finder of modules. A {@code ModuleFinder} is used to find modules during 46 * <a href="package-summary.html#resolution">resolution</a> or 47 * <a href="Configuration.html#service-binding">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 * omref.ifPresent(mref -> ... ); 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 I/O errors, errors 69 * detected parsing a module descriptor ({@code module-info.class}), or in the 70 * case of {@code ModuleFinder} returned by {@link #of ModuleFinder.of}, that 71 * 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 */ find(String name)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#resolveAndBind resolveAndBind} that need to scan the 123 * 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 */ findAll()133 Set<ModuleReference> findAll(); 134 135 /** 136 * Returns a module finder that locates the <em>system modules</em>. The 137 * system modules are the modules in 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 143 * {@link RuntimePermission RuntimePermission("accessSystemModules")} 144 * to access the system modules. </p> 145 * 146 * @return A {@code ModuleFinder} that locates the system modules 147 * 148 * @throws SecurityException 149 * If denied by the security manager 150 */ ofSystem()151 static ModuleFinder ofSystem() { 152 SecurityManager sm = System.getSecurityManager(); 153 if (sm != null) { 154 sm.checkPermission(new RuntimePermission("accessSystemModules")); 155 PrivilegedAction<ModuleFinder> pa = SystemModuleFinders::ofSystem; 156 return AccessController.doPrivileged(pa); 157 } else { 158 return SystemModuleFinders.ofSystem(); 159 } 160 } 161 162 /** 163 * Returns a module finder that locates modules on the file system by 164 * searching a sequence of directories and/or packaged modules. 165 * 166 * Each element in the given array is one of: 167 * <ol> 168 * <li><p> A path to a directory of modules.</p></li> 169 * <li><p> A path to the <em>top-level</em> directory of an 170 * <em>exploded module</em>. </p></li> 171 * <li><p> A path to a <em>packaged module</em>. </p></li> 172 * </ol> 173 * 174 * The module finder locates modules by searching each directory, exploded 175 * module, or packaged module in array index order. It finds the first 176 * occurrence of a module with a given name and ignores other modules of 177 * that name that appear later in the sequence. 178 * 179 * <p> If an element is a path to a directory of modules then each entry in 180 * the directory is a packaged module or the top-level directory of an 181 * exploded module. It is an error if a directory contains more than one 182 * module with the same name. If an element is a path to a directory, and 183 * that directory contains a file named {@code module-info.class}, then the 184 * directory is treated as an exploded module rather than a directory of 185 * modules. </p> 186 * 187 * <p id="automatic-modules"> The module finder returned by this method 188 * supports modules packaged as JAR files. A JAR file with a {@code 189 * module-info.class} in its top-level directory, or in a versioned entry 190 * in a {@linkplain java.util.jar.JarFile#isMultiRelease() multi-release} 191 * JAR file, is a modular JAR file and thus defines an <em>explicit</em> 192 * module. A JAR file that does not have a {@code module-info.class} in its 193 * top-level directory defines an <em>automatic module</em>, as follows: 194 * </p> 195 * 196 * <ul> 197 * 198 * <li><p> If the JAR file has the attribute "{@code Automatic-Module-Name}" 199 * in its main manifest then its value is the {@linkplain 200 * ModuleDescriptor#name() module name}. The module name is otherwise 201 * derived from the name of the JAR file. </p></li> 202 * 203 * <li><p> The {@link ModuleDescriptor#version() version}, and the 204 * module name when the attribute "{@code Automatic-Module-Name}" is not 205 * present, are derived from the file name of the JAR file as follows: </p> 206 * 207 * <ul> 208 * 209 * <li><p> The "{@code .jar}" suffix is removed. </p></li> 210 * 211 * <li><p> If the name matches the regular expression {@code 212 * "-(\\d+(\\.|$))"} then the module name will be derived from the 213 * subsequence preceding the hyphen of the first occurrence. The 214 * subsequence after the hyphen is parsed as a {@link 215 * ModuleDescriptor.Version Version} and ignored if it cannot be 216 * parsed as a {@code Version}. </p></li> 217 * 218 * <li><p> All non-alphanumeric characters ({@code [^A-Za-z0-9]}) 219 * in the module name are replaced with a dot ({@code "."}), all 220 * repeating dots are replaced with one dot, and all leading and 221 * trailing dots are removed. </p></li> 222 * 223 * <li><p> As an example, a JAR file named "{@code foo-bar.jar}" will 224 * derive a module name "{@code foo.bar}" and no version. A JAR file 225 * named "{@code foo-bar-1.2.3-SNAPSHOT.jar}" will derive a module 226 * name "{@code foo.bar}" and "{@code 1.2.3-SNAPSHOT}" as the version. 227 * </p></li> 228 * 229 * </ul></li> 230 * 231 * <li><p> The set of packages in the module is derived from the 232 * non-directory entries in the JAR file that have names ending in 233 * "{@code .class}". A candidate package name is derived from the name 234 * using the characters up to, but not including, the last forward slash. 235 * All remaining forward slashes are replaced with dot ({@code "."}). If 236 * the resulting string is a legal package name then it is assumed to be 237 * a package name. For example, if the JAR file contains the entry 238 * "{@code p/q/Foo.class}" then the package name derived is 239 * "{@code p.q}".</p></li> 240 * 241 * <li><p> The contents of entries starting with {@code 242 * META-INF/services/} are assumed to be service configuration files 243 * (see {@link java.util.ServiceLoader}). If the name of a file 244 * (that follows {@code META-INF/services/}) is a legal class name 245 * then it is assumed to be the fully-qualified class name of a service 246 * type. The entries in the file are assumed to be the fully-qualified 247 * class names of provider classes. </p></li> 248 * 249 * <li><p> If the JAR file has a {@code Main-Class} attribute in its 250 * main manifest, its value is a legal class name, and its package is 251 * in the set of packages derived for the module, then the value is the 252 * module {@linkplain ModuleDescriptor#mainClass() main class}. </p></li> 253 * 254 * </ul> 255 * 256 * <p> If a {@code ModuleDescriptor} cannot be created (by means of the 257 * {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an 258 * automatic module then {@code FindException} is thrown. This can arise 259 * when the value of the "{@code Automatic-Module-Name}" attribute is not a 260 * legal module name, a legal module name cannot be derived from the file 261 * name of the JAR file, where the JAR file contains a {@code .class} in 262 * the top-level directory of the JAR file, where an entry in a service 263 * configuration file is not a legal class name or its package name is not 264 * in the set of packages derived for the module. </p> 265 * 266 * <p> In addition to JAR files, an implementation may also support modules 267 * that are packaged in other implementation specific module formats. If 268 * an element in the array specified to this method is a path to a directory 269 * of modules then entries in the directory that not recognized as modules 270 * are ignored. If an element in the array is a path to a packaged module 271 * that is not recognized then a {@code FindException} is thrown when the 272 * file is encountered. Paths to files that do not exist are always ignored. 273 * </p> 274 * 275 * <p> As with automatic modules, the contents of a packaged or exploded 276 * module may need to be <em>scanned</em> in order to determine the packages 277 * in the module. Whether {@linkplain java.nio.file.Files#isHidden(Path) 278 * hidden files} are ignored or not is implementation specific and therefore 279 * not specified. If a {@code .class} file (other than {@code 280 * module-info.class}) is found in the top-level directory then it is 281 * assumed to be a class in the unnamed package and so {@code FindException} 282 * is thrown. </p> 283 * 284 * <p> Finders created by this method are lazy and do not eagerly check 285 * that the given file paths are directories or packaged modules. 286 * Consequently, the {@code find} or {@code findAll} methods will only 287 * fail if invoking these methods results in searching a directory or 288 * packaged module and an error is encountered. </p> 289 * 290 * @param entries 291 * A possibly-empty array of paths to directories of modules 292 * or paths to packaged or exploded modules 293 * 294 * @return A {@code ModuleFinder} that locates modules on the file system 295 */ of(Path... entries)296 static ModuleFinder of(Path... entries) { 297 // special case zero entries 298 if (entries.length == 0) { 299 return new ModuleFinder() { 300 @Override 301 public Optional<ModuleReference> find(String name) { 302 Objects.requireNonNull(name); 303 return Optional.empty(); 304 } 305 306 @Override 307 public Set<ModuleReference> findAll() { 308 return Set.of(); 309 } 310 }; 311 } 312 313 return ModulePath.of(entries); 314 } 315 316 /** 317 * Returns a module finder that is composed from a sequence of zero or more 318 * module finders. The {@link #find(String) find} method of the resulting 319 * module finder will locate a module by invoking the {@code find} method 320 * of each module finder, in array index order, until either the module is 321 * found or all module finders have been searched. The {@link #findAll() 322 * findAll} method of the resulting module finder will return a set of 323 * modules that includes all modules located by the first module finder. 324 * The set of modules will include all modules located by the second or 325 * subsequent module finder that are not located by previous module finders 326 * in the sequence. 327 * 328 * <p> When locating modules then any exceptions or errors thrown by the 329 * {@code find} or {@code findAll} methods of the underlying module finders 330 * will be propagated to the caller of the resulting module finder's 331 * {@code find} or {@code findAll} methods. </p> 332 * 333 * @param finders 334 * The array of module finders 335 * 336 * @return A {@code ModuleFinder} that composes a sequence of module finders 337 */ 338 static ModuleFinder compose(ModuleFinder... finders) { 339 // copy the list and check for nulls 340 final List<ModuleFinder> finderList = List.of(finders); 341 342 return new ModuleFinder() { 343 private final Map<String, ModuleReference> nameToModule = new HashMap<>(); 344 private Set<ModuleReference> allModules; 345 346 @Override 347 public Optional<ModuleReference> find(String name) { 348 // cached? 349 ModuleReference mref = nameToModule.get(name); 350 if (mref != null) 351 return Optional.of(mref); 352 Optional<ModuleReference> omref = finderList.stream() 353 .map(f -> f.find(name)) 354 .flatMap(Optional::stream) 355 .findFirst(); 356 omref.ifPresent(m -> nameToModule.put(name, m)); 357 return omref; 358 } 359 360 @Override 361 public Set<ModuleReference> findAll() { 362 if (allModules != null) 363 return allModules; 364 // seed with modules already found 365 Set<ModuleReference> result = new HashSet<>(nameToModule.values()); 366 finderList.stream() 367 .flatMap(f -> f.findAll().stream()) 368 .forEach(mref -> { 369 String name = mref.descriptor().name(); 370 if (nameToModule.putIfAbsent(name, mref) == null) { 371 result.add(mref); 372 } 373 }); 374 allModules = Collections.unmodifiableSet(result); 375 return allModules; 376 } 377 }; 378 } 379 380 } 381