1 /*
2 * Copyright (c) 2005, 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 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 name="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#listLocationsForModule}.
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 */
169 default boolean isModuleOrientedLocation() {
170 return getName().matches("\\bMODULE\\b");
171 }
172 }
173
174 /**
175 * Returns a class loader for loading plug-ins from the given
176 * package-oriented location.
177 * For example, to load annotation processors,
178 * a compiler will request a class loader for the {@link
179 * StandardLocation#ANNOTATION_PROCESSOR_PATH
180 * ANNOTATION_PROCESSOR_PATH} location.
181 *
182 * @param location a location
183 * @return a class loader for the given location; or {@code null}
184 * if loading plug-ins from the given location is disabled or if
185 * the location is not known
186 * @throws SecurityException if a class loader can not be created
187 * in the current security context
188 * @throws IllegalStateException if {@link #close} has been called
189 * and this file manager cannot be reopened
190 * @throws IllegalArgumentException if the location is a module-oriented location
191 */
192 ClassLoader getClassLoader(Location location);
193
194 /**
195 * Lists all file objects matching the given criteria in the given
196 * package-oriented location.
197 * List file objects in "subpackages" if recurse is true.
198 *
199 * <p>Note: even if the given location is unknown to this file
200 * manager, it may not return {@code null}. Also, an unknown
201 * location may not cause an exception.
202 *
203 * @param location a location
204 * @param packageName a package name
205 * @param kinds return objects only of these kinds
206 * @param recurse if true include "subpackages"
207 * @return an Iterable of file objects matching the given criteria
208 * @throws IOException if an I/O error occurred, or if {@link
209 * #close} has been called and this file manager cannot be
210 * reopened
211 * @throws IllegalArgumentException if the location is a module-oriented location
212 * @throws IllegalStateException if {@link #close} has been called
213 * and this file manager cannot be reopened
214 */
215 Iterable<JavaFileObject> list(Location location,
216 String packageName,
217 Set<Kind> kinds,
218 boolean recurse)
219 throws IOException;
220
221 /**
222 * Infers a binary name of a file object based on a package-oriented location.
223 * The binary name returned might not be a valid binary name according to
224 * <cite>The Java™ Language Specification</cite>.
225 *
226 * @param location a location
227 * @param file a file object
228 * @return a binary name or {@code null} the file object is not
229 * found in the given location
230 * @throws IllegalArgumentException if the location is a module-oriented location
231 * @throws IllegalStateException if {@link #close} has been called
232 * and this file manager cannot be reopened
233 */
234 String inferBinaryName(Location location, JavaFileObject file);
235
236 /**
237 * Compares two file objects and return true if they represent the
238 * same underlying object.
239 *
240 * @param a a file object
241 * @param b a file object
242 * @return true if the given file objects represent the same
243 * underlying object
244 *
245 * @throws IllegalArgumentException if either of the arguments
246 * were created with another file manager and this file manager
247 * does not support foreign file objects
248 */
249 boolean isSameFile(FileObject a, FileObject b);
250
251 /**
252 * Handles one option. If {@code current} is an option to this
253 * file manager it will consume any arguments to that option from
254 * {@code remaining} and return true, otherwise return false.
255 *
256 * @param current current option
257 * @param remaining remaining options
258 * @return true if this option was handled by this file manager,
259 * false otherwise
260 * @throws IllegalArgumentException if this option to this file
261 * manager is used incorrectly
262 * @throws IllegalStateException if {@link #close} has been called
263 * and this file manager cannot be reopened
264 */
265 boolean handleOption(String current, Iterator<String> remaining);
266
267 /**
268 * Determines if a location is known to this file manager.
269 *
270 * @param location a location
271 * @return true if the location is known
272 */
273 boolean hasLocation(Location location);
274
275 /**
276 * Returns a {@linkplain JavaFileObject file object} for input
277 * representing the specified class of the specified kind in the
278 * given package-oriented location.
279 *
280 * @param location a location
281 * @param className the name of a class
282 * @param kind the kind of file, must be one of {@link
283 * JavaFileObject.Kind#SOURCE SOURCE} or {@link
284 * JavaFileObject.Kind#CLASS CLASS}
285 * @return a file object, might return {@code null} if the
286 * file does not exist
287 * @throws IllegalArgumentException if the location is not known
288 * to this file manager and the file manager does not support
289 * unknown locations, or if the kind is not valid, or if the
290 * location is a module-oriented location
291 * @throws IOException if an I/O error occurred, or if {@link
292 * #close} has been called and this file manager cannot be
293 * reopened
294 * @throws IllegalStateException if {@link #close} has been called
295 * and this file manager cannot be reopened
296 */
297 JavaFileObject getJavaFileForInput(Location location,
298 String className,
299 Kind kind)
300 throws IOException;
301
302 /**
303 * Returns a {@linkplain JavaFileObject file object} for output
304 * representing the specified class of the specified kind in the
305 * given package-oriented location.
306 *
307 * <p>Optionally, this file manager might consider the sibling as
308 * a hint for where to place the output. The exact semantics of
309 * this hint is unspecified. The JDK compiler, javac, for
310 * example, will place class files in the same directories as
311 * originating source files unless a class file output directory
312 * is provided. To facilitate this behavior, javac might provide
313 * the originating source file as sibling when calling this
314 * method.
315 *
316 * @param location a package-oriented location
317 * @param className the name of a class
318 * @param kind the kind of file, must be one of {@link
319 * JavaFileObject.Kind#SOURCE SOURCE} or {@link
320 * JavaFileObject.Kind#CLASS CLASS}
321 * @param sibling a file object to be used as hint for placement;
322 * might be {@code null}
323 * @return a file object for output
324 * @throws IllegalArgumentException if sibling is not known to
325 * this file manager, or if the location is not known to this file
326 * manager and the file manager does not support unknown
327 * locations, or if the kind is not valid, or if the location is
328 * not an output location
329 * @throws IOException if an I/O error occurred, or if {@link
330 * #close} has been called and this file manager cannot be
331 * reopened
332 * @throws IllegalStateException {@link #close} has been called
333 * and this file manager cannot be reopened
334 */
335 JavaFileObject getJavaFileForOutput(Location location,
336 String className,
337 Kind kind,
338 FileObject sibling)
339 throws IOException;
340
341 /**
342 * Returns a {@linkplain FileObject file object} for input
343 * representing the specified <a href="JavaFileManager.html#relative_name">relative
344 * name</a> in the specified package in the given package-oriented location.
345 *
346 * <p>If the returned object represents a {@linkplain
347 * JavaFileObject.Kind#SOURCE source} or {@linkplain
348 * JavaFileObject.Kind#CLASS class} file, it must be an instance
349 * of {@link JavaFileObject}.
350 *
351 * <p>Informally, the file object returned by this method is
352 * located in the concatenation of the location, package name, and
353 * relative name. For example, to locate the properties file
354 * "resources/compiler.properties" in the package
355 * "com.sun.tools.javac" in the {@linkplain
356 * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
357 * might be called like so:
358 *
359 * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>
360 *
361 * <p>If the call was executed on Windows, with SOURCE_PATH set to
362 * <code>"C:\Documents and Settings\UncleBob\src\share\classes"</code>,
363 * a valid result would be a file object representing the file
364 * <code>"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.
365 *
366 * @param location a package-oriented location
367 * @param packageName a package name
368 * @param relativeName a relative name
369 * @return a file object, might return {@code null} if the file
370 * does not exist
371 * @throws IllegalArgumentException if the location is not known
372 * to this file manager and the file manager does not support
373 * unknown locations, or if {@code relativeName} is not valid,
374 * or if the location is a module-oriented location
375 * @throws IOException if an I/O error occurred, or if {@link
376 * #close} has been called and this file manager cannot be
377 * reopened
378 * @throws IllegalStateException if {@link #close} has been called
379 * and this file manager cannot be reopened
380 */
381 FileObject getFileForInput(Location location,
382 String packageName,
383 String relativeName)
384 throws IOException;
385
386 /**
387 * Returns a {@linkplain FileObject file object} for output
388 * representing the specified <a href="JavaFileManager.html#relative_name">relative
389 * name</a> in the specified package in the given location.
390 *
391 * <p>Optionally, this file manager might consider the sibling as
392 * a hint for where to place the output. The exact semantics of
393 * this hint is unspecified. The JDK compiler, javac, for
394 * example, will place class files in the same directories as
395 * originating source files unless a class file output directory
396 * is provided. To facilitate this behavior, javac might provide
397 * the originating source file as sibling when calling this
398 * method.
399 *
400 * <p>If the returned object represents a {@linkplain
401 * JavaFileObject.Kind#SOURCE source} or {@linkplain
402 * JavaFileObject.Kind#CLASS class} file, it must be an instance
403 * of {@link JavaFileObject}.
404 *
405 * <p>Informally, the file object returned by this method is
406 * located in the concatenation of the location, package name, and
407 * relative name or next to the sibling argument. See {@link
408 * #getFileForInput getFileForInput} for an example.
409 *
410 * @param location an output location
411 * @param packageName a package name
412 * @param relativeName a relative name
413 * @param sibling a file object to be used as hint for placement;
414 * might be {@code null}
415 * @return a file object
416 * @throws IllegalArgumentException if sibling is not known to
417 * this file manager, or if the location is not known to this file
418 * manager and the file manager does not support unknown
419 * locations, or if {@code relativeName} is not valid,
420 * or if the location is not an output location
421 * @throws IOException if an I/O error occurred, or if {@link
422 * #close} has been called and this file manager cannot be
423 * reopened
424 * @throws IllegalStateException if {@link #close} has been called
425 * and this file manager cannot be reopened
426 */
427 FileObject getFileForOutput(Location location,
428 String packageName,
429 String relativeName,
430 FileObject sibling)
431 throws IOException;
432
433 /**
434 * Flushes any resources opened for output by this file manager
435 * directly or indirectly. Flushing a closed file manager has no
436 * effect.
437 *
438 * @throws IOException if an I/O error occurred
439 * @see #close
440 */
441 @Override
442 void flush() throws IOException;
443
444 /**
445 * Releases any resources opened by this file manager directly or
446 * indirectly. This might render this file manager useless and
447 * the effect of subsequent calls to methods on this object or any
448 * objects obtained through this object is undefined unless
449 * explicitly allowed. However, closing a file manager which has
450 * already been closed has no effect.
451 *
452 * @throws IOException if an I/O error occurred
453 * @see #flush
454 */
455 @Override
456 void close() throws IOException;
457
458 /**
459 * Gets a location for a named module within a location, which may be either
460 * a module-oriented location or an output location.
461 * The result will be an output location if the given location is
462 * an output location, or it will be a package-oriented location.
463 *
464 * @implSpec This implementation throws {@code UnsupportedOperationException}.
465 *
466 * @param location the module-oriented location
467 * @param moduleName the name of the module to be found
468 * @return the location for the named module
469 *
470 * @throws IOException if an I/O error occurred
471 * @throws UnsupportedOperationException if this operation if not supported by this file manager
472 * @throws IllegalArgumentException if the location is neither an output location nor a
473 * module-oriented location
474 * @since 9
475 */ // TODO: describe failure modes
476 default Location getLocationForModule(Location location, String moduleName) throws IOException {
477 throw new UnsupportedOperationException();
478 }
479
480 /**
481 * Gets a location for the module containing a specific file representing a Java
482 * source or class, to be found within a location, which may be either
483 * a module-oriented location or an output location.
484 * The result will be an output location if the given location is
485 * an output location, or it will be a package-oriented location.
486 *
487 * @apiNote the package name is used to identify the position of the file object
488 * within the <em>module/package/class</em> hierarchy identified by by the location.
489 *
490 * @implSpec This implementation throws {@code UnsupportedOperationException}.
491 *
492 * @param location the module-oriented location
493 * @param fo the file
494 * @param pkgName the package name for the class(es) defined in this file
495 * @return the module containing the file
496 *
497 * @throws IOException if an I/O error occurred
498 * @throws UnsupportedOperationException if this operation if not supported by this file manager
499 * @throws IllegalArgumentException if the location is neither an output location nor a
500 * module-oriented location
501 * @since 9
502 */
503 default Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
504 throw new UnsupportedOperationException();
505 }
506
507 /**
508 * Get a service loader for a specific service class from a given location.
509 *
510 * If the location is a module-oriented location, the service loader will use the
511 * service declarations in the modules found in that location. Otherwise, a service loader
512 * is created using the package-oriented location, in which case, the services are
513 * determined using the provider-configuration files in {@code META-INF/services}.
514 *
515 * @implSpec This implementation throws {@code UnsupportedOperationException}.
516 *
517 * @param location the module-oriented location
518 * @param service the {@code Class} object of the service class
519 * @param <S> the service class
520 * @return a service loader for the given service class
521 *
522 * @throws IOException if an I/O error occurred
523 * @throws UnsupportedOperationException if this operation if not supported by this file manager
524 * @since 9
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 */ // TODO: describe failure modes
544 default String inferModuleName(Location location) throws IOException {
545 throw new UnsupportedOperationException();
546 }
547
548 /**
549 * Lists the locations for all the modules in a module-oriented location or an output location.
550 * The locations that are returned will be output locations if the given location is an output,
551 * or it will be a package-oriented locations.
552 *
553 * @implSpec This implementation throws {@code UnsupportedOperationException}.
554 *
555 * @param location the module-oriented location for which to list the modules
556 * @return a series of sets of locations containing modules
557 *
558 * @throws IOException if an I/O error occurred
559 * @throws UnsupportedOperationException if this operation if not supported by this file manager
560 * @throws IllegalArgumentException if the location is not a module-oriented location
561 * @since 9
562 */ // TODO: describe failure modes
563 default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
564 throw new UnsupportedOperationException();
565 }
566
567 }