1 /*
2 * Copyright (c) 2005, 2020, 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 javax.tools;
27
28 import java.io.Closeable;
29 import java.io.Flushable;
30 import java.io.IOException;
31 import java.util.Iterator;
32 import java.util.ServiceLoader;
33 import java.util.Set;
34
35 import static javax.tools.JavaFileObject.Kind;
36
37 /**
38 * File manager for tools operating on Java™ programming language
39 * source and class files. In this context, <em>file</em> means an
40 * abstraction of regular files and other sources of data.
41 *
42 * <p>When constructing new JavaFileObjects, the file manager must
43 * determine where to create them. For example, if a file manager
44 * manages regular files on a file system, it would most likely have a
45 * current/working directory to use as default location when creating
46 * or finding files. A number of hints can be provided to a file
47 * manager as to where to create files. Any file manager might choose
48 * to ignore these hints.
49 *
50 * <p>Some methods in this interface use class names. Such class
51 * names must be given in the Java Virtual Machine internal form of
52 * fully qualified class and interface names. For convenience '.'
53 * and '/' are interchangeable. The internal form is defined in
54 * chapter four of
55 * <cite>The Java™ Virtual Machine Specification</cite>.
56
57 * <blockquote><p>
58 * <i>Discussion:</i> this means that the names
59 * "java/lang.package-info", "java/lang/package-info",
60 * "java.lang.package-info", are valid and equivalent. Compare to
61 * binary name as defined in
62 * <cite>The Java™ Language Specification</cite>,
63 * section 13.1 "The Form of a Binary".
64 * </p></blockquote>
65 *
66 * <p>The case of names is significant. All names should be treated
67 * as case-sensitive. For example, some file systems have
68 * case-insensitive, case-aware file names. File objects representing
69 * such files should take care to preserve case by using {@link
70 * java.io.File#getCanonicalFile} or similar means. If the system is
71 * not case-aware, file objects must use other means to preserve case.
72 *
73 * <p><em><a id="relative_name">Relative names</a>:</em> some
74 * methods in this interface use relative names. A relative name is a
75 * non-null, non-empty sequence of path segments separated by '/'.
76 * '.' or '..' are invalid path segments. A valid relative name must
77 * match the "path-rootless" rule of <a
78 * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
79 * section 3.3. Informally, this should be true:
80 *
81 * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
82 * <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize() normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
83 *
84 * <p>All methods in this interface might throw a SecurityException.
85 *
86 * <p>An object of this interface is not required to support
87 * multi-threaded access, that is, be synchronized. However, it must
88 * support concurrent access to different file objects created by this
89 * object.
90 *
91 * <p><em>Implementation note:</em> a consequence of this requirement
92 * is that a trivial implementation of output to a {@linkplain
93 * java.util.jar.JarOutputStream} is not a sufficient implementation.
94 * That is, rather than creating a JavaFileObject that returns the
95 * JarOutputStream directly, the contents must be cached until closed
96 * and then written to the JarOutputStream.
97 *
98 * <p>Unless explicitly allowed, all methods in this interface might
99 * throw a NullPointerException if given a {@code null} argument.
100 *
101 * @author Peter von der Ahé
102 * @author Jonathan Gibbons
103 * @see JavaFileObject
104 * @see FileObject
105 * @since 1.6
106 */
107 public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
108
109 /**
110 * Interface for locations of file objects. Used by file managers
111 * to determine where to place or search for file objects.
112 *
113 * <p>Informally, a {@code Location} corresponds to a "search path", such as a class
114 * path or module path, as used by command-line tools that use the default file system.
115 *
116 * <p>Some locations are typically used to identify a place in which
117 * a tool can find files to be read; others are typically used to identify
118 * a place where a tool can write files. If a location is used to identify
119 * a place for reading files, those files may be organized in a simple
120 * <em>package/class</em> hierarchy: such locations are described as
121 * <strong>package-oriented</strong>.
122 * Alternatively, the files may be organized in a <em>module/package/class</em>
123 * hierarchy: such locations are described as <strong>module-oriented</strong>.
124 * If a location is typically used to identify a place where a tool can write files,
125 * it is up to the tool that writes the files to specify how those files will be
126 * organized.
127 *
128 * <p>You can access the classes in a package-oriented location using methods like
129 * {@link JavaFileManager#getJavaFileForInput} or {@link JavaFileManager#list}.
130 * It is not possible to directly list the classes in a module-oriented
131 * location. Instead, you can get a package-oriented location for any specific module
132 * using methods like {@link JavaFileManager#getLocationForModule} or
133 * {@link JavaFileManager#listLocationsForModules}.
134 */
135 interface Location {
136 /**
137 * Returns the name of this location.
138 *
139 * @return a name
140 */
141 String getName();
142
143 /**
144 * Determines if this is an output location.
145 * An output location is a location that is conventionally used for
146 * output.
147 *
148 * @apiNote An output location may be used to write files in either
149 * a package-oriented organization or in a module-oriented organization.
150 *
151 * @return true if this is an output location, false otherwise
152 */
153 boolean isOutputLocation();
154
155 /**
156 * Indicates if this location is module-oriented location, and therefore
157 * expected to contain classes in a <em>module/package/class</em>
158 * hierarchy, as compared to a package-oriented location, which
159 * is expected to contain classes in a <em>package/class</em> hierarchy.
160 * The result of this method is undefined if this is an output
161 * location.
162 *
163 * @implNote This implementation returns true if the name includes
164 * the word "MODULE".
165 *
166 * @return true if this location is expected to contain modules
167 * @since 9
168 * @spec JPMS
169 */
170 default boolean isModuleOrientedLocation() {
171 return getName().matches("\\bMODULE\\b");
172 }
173 }
174
175 /**
176 * Returns a class loader for loading plug-ins from the given
177 * package-oriented location.
178 * For example, to load annotation processors,
179 * a compiler will request a class loader for the {@link
180 * StandardLocation#ANNOTATION_PROCESSOR_PATH
181 * ANNOTATION_PROCESSOR_PATH} location.
182 *
183 * @param location a location
184 * @return a class loader for the given location; or {@code null}
185 * if loading plug-ins from the given location is disabled or if
186 * the location is not known
187 * @throws SecurityException if a class loader can not be created
188 * in the current security context
189 * @throws IllegalStateException if {@link #close} has been called
190 * and this file manager cannot be reopened
191 * @throws IllegalArgumentException if the location is a module-oriented location
192 */
193 ClassLoader getClassLoader(Location location);
194
195 /**
196 * Lists all file objects matching the given criteria in the given
197 * package-oriented location.
198 * List file objects in "subpackages" if recurse is true.
199 *
200 * <p>Note: even if the given location is unknown to this file
201 * manager, it may not return {@code null}. Also, an unknown
202 * location may not cause an exception.
203 *
204 * @param location a location
205 * @param packageName a package name
206 * @param kinds return objects only of these kinds
207 * @param recurse if true include "subpackages"
208 * @return an Iterable of file objects matching the given criteria
209 * @throws IOException if an I/O error occurred, or if {@link
210 * #close} has been called and this file manager cannot be
211 * reopened
212 * @throws IllegalArgumentException if the location is a module-oriented location
213 * @throws IllegalStateException if {@link #close} has been called
214 * and this file manager cannot be reopened
215 */
216 Iterable<JavaFileObject> list(Location location,
217 String packageName,
218 Set<Kind> kinds,
219 boolean recurse)
220 throws IOException;
221
222 /**
223 * Infers a binary name of a file object based on a package-oriented location.
224 * The binary name returned might not be a valid binary name according to
225 * <cite>The Java™ Language Specification</cite>.
226 *
227 * @param location a location
228 * @param file a file object
229 * @return a binary name or {@code null} the file object is not
230 * found in the given location
231 * @throws IllegalArgumentException if the location is a module-oriented location
232 * @throws IllegalStateException if {@link #close} has been called
233 * and this file manager cannot be reopened
234 */
235 String inferBinaryName(Location location, JavaFileObject file);
236
237 /**
238 * Compares two file objects and return true if they represent the
239 * same underlying object.
240 *
241 * @param a a file object
242 * @param b a file object
243 * @return true if the given file objects represent the same
244 * underlying object
245 *
246 * @throws IllegalArgumentException if either of the arguments
247 * were created with another file manager and this file manager
248 * does not support foreign file objects
249 */
250 boolean isSameFile(FileObject a, FileObject b);
251
252 /**
253 * Handles one option. If {@code current} is an option to this
254 * file manager it will consume any arguments to that option from
255 * {@code remaining} and return true, otherwise return false.
256 *
257 * @param current current option
258 * @param remaining remaining options
259 * @return true if this option was handled by this file manager,
260 * false otherwise
261 * @throws IllegalArgumentException if this option to this file
262 * manager is used incorrectly
263 * @throws IllegalStateException if {@link #close} has been called
264 * and this file manager cannot be reopened
265 */
266 boolean handleOption(String current, Iterator<String> remaining);
267
268 /**
269 * Determines if a location is known to this file manager.
270 *
271 * @param location a location
272 * @return true if the location is known
273 */
274 boolean hasLocation(Location location);
275
276 /**
277 * Returns a {@linkplain JavaFileObject file object} for input
278 * representing the specified class of the specified kind in the
279 * given package-oriented location.
280 *
281 * @param location a location
282 * @param className the name of a class
283 * @param kind the kind of file, must be one of {@link
284 * JavaFileObject.Kind#SOURCE SOURCE} or {@link
285 * JavaFileObject.Kind#CLASS CLASS}
286 * @return a file object, might return {@code null} if the
287 * file does not exist
288 * @throws IllegalArgumentException if the location is not known
289 * to this file manager and the file manager does not support
290 * unknown locations, or if the kind is not valid, or if the
291 * location is a module-oriented location
292 * @throws IOException if an I/O error occurred, or if {@link
293 * #close} has been called and this file manager cannot be
294 * reopened
295 * @throws IllegalStateException if {@link #close} has been called
296 * and this file manager cannot be reopened
297 */
298 JavaFileObject getJavaFileForInput(Location location,
299 String className,
300 Kind kind)
301 throws IOException;
302
303 /**
304 * Returns a {@linkplain JavaFileObject file object} for output
305 * representing the specified class of the specified kind in the
306 * given package-oriented location.
307 *
308 * <p>Optionally, this file manager might consider the sibling as
309 * a hint for where to place the output. The exact semantics of
310 * this hint is unspecified. The JDK compiler, javac, for
311 * example, will place class files in the same directories as
312 * originating source files unless a class file output directory
313 * is provided. To facilitate this behavior, javac might provide
314 * the originating source file as sibling when calling this
315 * method.
316 *
317 * @param location a package-oriented location
318 * @param className the name of a class
319 * @param kind the kind of file, must be one of {@link
320 * JavaFileObject.Kind#SOURCE SOURCE} or {@link
321 * JavaFileObject.Kind#CLASS CLASS}
322 * @param sibling a file object to be used as hint for placement;
323 * might be {@code null}
324 * @return a file object for output
325 * @throws IllegalArgumentException if sibling is not known to
326 * this file manager, or if the location is not known to this file
327 * manager and the file manager does not support unknown
328 * locations, or if the kind is not valid, or if the location is
329 * not an output location
330 * @throws IOException if an I/O error occurred, or if {@link
331 * #close} has been called and this file manager cannot be
332 * reopened
333 * @throws IllegalStateException {@link #close} has been called
334 * and this file manager cannot be reopened
335 */
336 JavaFileObject getJavaFileForOutput(Location location,
337 String className,
338 Kind kind,
339 FileObject sibling)
340 throws IOException;
341
342 /**
343 * Returns a {@linkplain FileObject file object} for input
344 * representing the specified <a href="JavaFileManager.html#relative_name">relative
345 * name</a> in the specified package in the given package-oriented location.
346 *
347 * <p>If the returned object represents a {@linkplain
348 * JavaFileObject.Kind#SOURCE source} or {@linkplain
349 * JavaFileObject.Kind#CLASS class} file, it must be an instance
350 * of {@link JavaFileObject}.
351 *
352 * <p>Informally, the file object returned by this method is
353 * located in the concatenation of the location, package name, and
354 * relative name. For example, to locate the properties file
355 * "resources/compiler.properties" in the package
356 * "com.sun.tools.javac" in the {@linkplain
357 * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
358 * might be called like so:
359 *
360 * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>
361 *
362 * <p>If the call was executed on Windows, with SOURCE_PATH set to
363 * <code>"C:\Documents and Settings\UncleBob\src\share\classes"</code>,
364 * a valid result would be a file object representing the file
365 * <code>"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.
366 *
367 * @param location a package-oriented location
368 * @param packageName a package name
369 * @param relativeName a relative name
370 * @return a file object, might return {@code null} if the file
371 * does not exist
372 * @throws IllegalArgumentException if the location is not known
373 * to this file manager and the file manager does not support
374 * unknown locations, or if {@code relativeName} is not valid,
375 * or if the location is a module-oriented location
376 * @throws IOException if an I/O error occurred, or if {@link
377 * #close} has been called and this file manager cannot be
378 * reopened
379 * @throws IllegalStateException if {@link #close} has been called
380 * and this file manager cannot be reopened
381 */
382 FileObject getFileForInput(Location location,
383 String packageName,
384 String relativeName)
385 throws IOException;
386
387 /**
388 * Returns a {@linkplain FileObject file object} for output
389 * representing the specified <a href="JavaFileManager.html#relative_name">relative
390 * name</a> in the specified package in the given location.
391 *
392 * <p>Optionally, this file manager might consider the sibling as
393 * a hint for where to place the output. The exact semantics of
394 * this hint is unspecified. The JDK compiler, javac, for
395 * example, will place class files in the same directories as
396 * originating source files unless a class file output directory
397 * is provided. To facilitate this behavior, javac might provide
398 * the originating source file as sibling when calling this
399 * method.
400 *
401 * <p>If the returned object represents a {@linkplain
402 * JavaFileObject.Kind#SOURCE source} or {@linkplain
403 * JavaFileObject.Kind#CLASS class} file, it must be an instance
404 * of {@link JavaFileObject}.
405 *
406 * <p>Informally, the file object returned by this method is
407 * located in the concatenation of the location, package name, and
408 * relative name or next to the sibling argument. See {@link
409 * #getFileForInput getFileForInput} for an example.
410 *
411 * @param location an output location
412 * @param packageName a package name
413 * @param relativeName a relative name
414 * @param sibling a file object to be used as hint for placement;
415 * might be {@code null}
416 * @return a file object
417 * @throws IllegalArgumentException if sibling is not known to
418 * this file manager, or if the location is not known to this file
419 * manager and the file manager does not support unknown
420 * locations, or if {@code relativeName} is not valid,
421 * or if the location is not an output location
422 * @throws IOException if an I/O error occurred, or if {@link
423 * #close} has been called and this file manager cannot be
424 * reopened
425 * @throws IllegalStateException if {@link #close} has been called
426 * and this file manager cannot be reopened
427 */
428 FileObject getFileForOutput(Location location,
429 String packageName,
430 String relativeName,
431 FileObject sibling)
432 throws IOException;
433
434 /**
435 * Flushes any resources opened for output by this file manager
436 * directly or indirectly. Flushing a closed file manager has no
437 * effect.
438 *
439 * @throws IOException if an I/O error occurred
440 * @see #close
441 */
442 @Override
443 void flush() throws IOException;
444
445 /**
446 * Releases any resources opened by this file manager directly or
447 * indirectly. This might render this file manager useless and
448 * the effect of subsequent calls to methods on this object or any
449 * objects obtained through this object is undefined unless
450 * explicitly allowed. However, closing a file manager which has
451 * already been closed has no effect.
452 *
453 * @throws IOException if an I/O error occurred
454 * @see #flush
455 */
456 @Override
457 void close() throws IOException;
458
459 /**
460 * Gets a location for a named module within a location, which may be either
461 * a module-oriented location or an output location.
462 * The result will be an output location if the given location is
463 * an output location, or it will be a package-oriented location.
464 *
465 * @implSpec This implementation throws {@code UnsupportedOperationException}.
466 *
467 * @param location the module-oriented location
468 * @param moduleName the name of the module to be found
469 * @return the location for the named module
470 *
471 * @throws IOException if an I/O error occurred
472 * @throws UnsupportedOperationException if this operation if not supported by this file manager
473 * @throws IllegalArgumentException if the location is neither an output location nor a
474 * module-oriented location
475 * @since 9
476 * @spec JPMS
477 */ // TODO: describe failure modes
478 default Location getLocationForModule(Location location, String moduleName) throws IOException {
479 throw new UnsupportedOperationException();
480 }
481
482 /**
483 * Gets a location for the module containing a specific file
484 * to be found within a location, which may be either
485 * a module-oriented location or an output location.
486 * The result will be an output location if the given location is
487 * an output location, or it will be a package-oriented location.
488 *
489 * @implSpec This implementation throws {@code UnsupportedOperationException}.
490 *
491 * @param location the module-oriented location
492 * @param fo the file
493 * @return the module containing the file
494 *
495 * @throws IOException if an I/O error occurred
496 * @throws UnsupportedOperationException if this operation if not supported by this file manager
497 * @throws IllegalArgumentException if the location is neither an output location nor a
498 * module-oriented location
499 * @since 9
500 * @spec JPMS
501 */
502 default Location getLocationForModule(Location location, JavaFileObject fo) throws IOException {
503 throw new UnsupportedOperationException();
504 }
505
506 /**
507 * Get a service loader for a specific service class from a given location.
508 *
509 * If the location is a module-oriented location, the service loader will use the
510 * service declarations in the modules found in that location. Otherwise, a service loader
511 * is created using the package-oriented location, in which case, the services are
512 * determined using the provider-configuration files in {@code META-INF/services}.
513 *
514 * @implSpec This implementation throws {@code UnsupportedOperationException}.
515 *
516 * @param location the module-oriented location
517 * @param service the {@code Class} object of the service class
518 * @param <S> the service class
519 * @return a service loader for the given service class
520 *
521 * @throws IOException if an I/O error occurred
522 * @throws UnsupportedOperationException if this operation if not supported by this file manager
523 * @since 9
524 * @spec JPMS
525 */ // TODO: describe failure modes
526 default <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws IOException {
527 throw new UnsupportedOperationException();
528 }
529
530 /**
531 * Infer the name of the module from its location, as returned by
532 * {@code getLocationForModule} or {@code listModuleLocations}.
533 *
534 * @implSpec This implementation throws {@code UnsupportedOperationException}.
535 *
536 * @param location a package-oriented location representing a module
537 * @return the name of the module
538 *
539 * @throws IOException if an I/O error occurred
540 * @throws UnsupportedOperationException if this operation if not supported by this file manager
541 * @throws IllegalArgumentException if the location is not one known to this file manager
542 * @since 9
543 * @spec JPMS
544 */ // TODO: describe failure modes
545 default String inferModuleName(Location location) throws IOException {
546 throw new UnsupportedOperationException();
547 }
548
549 /**
550 * Lists the locations for all the modules in a module-oriented location or an output location.
551 * The locations that are returned will be output locations if the given location is an output,
552 * or it will be a package-oriented locations.
553 *
554 * @implSpec This implementation throws {@code UnsupportedOperationException}.
555 *
556 * @param location the module-oriented location for which to list the modules
557 * @return a series of sets of locations containing modules
558 *
559 * @throws IOException if an I/O error occurred
560 * @throws UnsupportedOperationException if this operation if not supported by this file manager
561 * @throws IllegalArgumentException if the location is not a module-oriented location
562 * @since 9
563 * @spec JPMS
564 */ // TODO: describe failure modes
565 default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
566 throw new UnsupportedOperationException();
567 }
568
569 /**
570 * Determines whether or not a given file object is "contained in" a specified location.
571 *
572 * <p>For a package-oriented location, a file object is contained in the location if there exist
573 * values for <i>packageName</i> and <i>relativeName</i> such that either of the following
574 * calls would return the {@link #isSameFile same} file object:
575 * <pre>
576 * getFileForInput(location, <i>packageName</i>, <i>relativeName</i>)
577 * getFileForOutput(location, <i>packageName</i>, <i>relativeName</i>, null)
578 * </pre>
579 *
580 * <p>For a module-oriented location, a file object is contained in the location if there exists
581 * a module that may be obtained by the call:
582 * <pre>
583 * getLocationForModule(location, <i>moduleName</i>)
584 * </pre>
585 * such that the file object is contained in the (package-oriented) location for that module.
586 *
587 * @implSpec This implementation throws {@code UnsupportedOperationException}.
588 *
589 * @param location the location
590 * @param fo the file object
591 * @return whether or not the file is contained in the location
592 *
593 * @throws IOException if there is a problem determining the result
594 * @throws UnsupportedOperationException if the method is not supported
595 *
596 * @since 9
597 */
598
599 default boolean contains(Location location, FileObject fo) throws IOException {
600 throw new UnsupportedOperationException();
601 }
602
603 }