1/*2 * Copyright (c) 2005, 2006, 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 it6 * under the terms of the GNU General Public License version 2 only, as7 * published by the Free Software Foundation. Oracle designates this8 * particular file as subject to the "Classpath" exception as provided9 * 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 WITHOUT12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License14 * version 2 for more details (a copy is included in the LICENSE file that15 * accompanied this code).16 *17 * You should have received a copy of the GNU General Public License version18 * 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 USA22 * or visit www.oracle.com if you need additional information or have any23 * questions.24 */2526package javax.tools;
2728import java.io.Closeable;
29import java.io.Flushable;
30import java.io.IOException;
31import java.util.Iterator;
32import java.util.Set;
33importstatic javax.tools.JavaFileObject.Kind;
3435/**36 * File manager for tools operating on Java&trade; programming language37 * source and class files. In this context, <em>file</em> means an38 * abstraction of regular files and other sources of data.39 *40 * <p>When constructing new JavaFileObjects, the file manager must41 * determine where to create them. For example, if a file manager42 * manages regular files on a file system, it would most likely have a43 * current/working directory to use as default location when creating44 * or finding files. A number of hints can be provided to a file45 * manager as to where to create files. Any file manager might choose46 * to ignore these hints.47 *48 * <p>Some methods in this interface use class names. Such class49 * names must be given in the Java Virtual Machine internal form of50 * fully qualified class and interface names. For convenience '.'51 * and '/' are interchangeable. The internal form is defined in52 * chapter four of53 * <cite>The Java&trade; Virtual Machine Specification</cite>.5455 * <blockquote><p>56 * <i>Discussion:</i> this means that the names57 * "java/lang.package-info", "java/lang/package-info",58 * "java.lang.package-info", are valid and equivalent. Compare to59 * binary name as defined in60 * <cite>The Java&trade; Language Specification</cite>,61 * section 13.1 "The Form of a Binary".62 * </p></blockquote>63 *64 * <p>The case of names is significant. All names should be treated65 * as case-sensitive. For example, some file systems have66 * case-insensitive, case-aware file names. File objects representing67 * such files should take care to preserve case by using {@link68 * java.io.File#getCanonicalFile} or similar means. If the system is69 * not case-aware, file objects must use other means to preserve case.70 *71 * <p><em><a name="relative_name">Relative names</a>:</em> some72 * methods in this interface use relative names. A relative name is a73 * non-null, non-empty sequence of path segments separated by '/'.74 * '.' or '..' are invalid path segments. A valid relative name must75 * match the "path-rootless" rule of <a76 * href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>,77 * section&nbsp;3.3. Informally, this should be true:78 *79 * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->80 * <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>81 *82 * <p>All methods in this interface might throw a SecurityException.83 *84 * <p>An object of this interface is not required to support85 * multi-threaded access, that is, be synchronized. However, it must86 * support concurrent access to different file objects created by this87 * object.88 *89 * <p><em>Implementation note:</em> a consequence of this requirement90 * is that a trivial implementation of output to a {@linkplain91 * java.util.jar.JarOutputStream} is not a sufficient implementation.92 * That is, rather than creating a JavaFileObject that returns the93 * JarOutputStream directly, the contents must be cached until closed94 * and then written to the JarOutputStream.95 *96 * <p>Unless explicitly allowed, all methods in this interface might97 * throw a NullPointerException if given a {@code null} argument.98 *99 * @author Peter von der Ah&eacute;100 * @author Jonathan Gibbons101 * @see JavaFileObject102 * @see FileObject103 * @since 1.6104 */105publicinterfaceJavaFileManagerextends Closeable, Flushable, OptionChecker {
106107/**108 * Interface for locations of file objects. Used by file managers109 * to determine where to place or search for file objects.110 */111interfaceLocation {
112/**113 * Gets the name of this location.114 *115 * @return a name116 */117String getName();
118119/**120 * Determines if this is an output location. An output121 * location is a location that is conventionally used for122 * output.123 *124 * @return true if this is an output location, false otherwise125 */126boolean isOutputLocation();
127 }
128129/**130 * Gets a class loader for loading plug-ins from the given131 * location. For example, to load annotation processors, a132 * compiler will request a class loader for the {@link133 * StandardLocation#ANNOTATION_PROCESSOR_PATH134 * ANNOTATION_PROCESSOR_PATH} location.135 *136 * @param location a location137 * @return a class loader for the given location; or {@code null}138 * if loading plug-ins from the given location is disabled or if139 * the location is not known140 * @throws SecurityException if a class loader can not be created141 * in the current security context142 * @throws IllegalStateException if {@link #close} has been called143 * and this file manager cannot be reopened144 */145ClassLoader getClassLoader(Location location);
146147/**148 * Lists all file objects matching the given criteria in the given149 * location. List file objects in "subpackages" if recurse is150 * true.151 *152 * <p>Note: even if the given location is unknown to this file153 * manager, it may not return {@code null}. Also, an unknown154 * location may not cause an exception.155 *156 * @param location a location157 * @param packageName a package name158 * @param kinds return objects only of these kinds159 * @param recurse if true include "subpackages"160 * @return an Iterable of file objects matching the given criteria161 * @throws IOException if an I/O error occurred, or if {@link162 * #close} has been called and this file manager cannot be163 * reopened164 * @throws IllegalStateException if {@link #close} has been called165 * and this file manager cannot be reopened166 */167 Iterable<JavaFileObject> list(Location location,
168String packageName,
169 Set<Kind> kinds,
170boolean recurse)
171throws IOException;
172173/**174 * Infers a binary name of a file object based on a location. The175 * binary name returned might not be a valid binary name according to176 * <cite>The Java&trade; Language Specification</cite>.177 *178 * @param location a location179 * @param file a file object180 * @return a binary name or {@code null} the file object is not181 * found in the given location182 * @throws IllegalStateException if {@link #close} has been called183 * and this file manager cannot be reopened184 */185String inferBinaryName(Location location, JavaFileObject file);
186187/**188 * Compares two file objects and return true if they represent the189 * same underlying object.190 *191 * @param a a file object192 * @param b a file object193 * @return true if the given file objects represent the same194 * underlying object195 *196 * @throws IllegalArgumentException if either of the arguments197 * were created with another file manager and this file manager198 * does not support foreign file objects199 */200boolean isSameFile(FileObject a, FileObject b);
201202/**203 * Handles one option. If {@code current} is an option to this204 * file manager it will consume any arguments to that option from205 * {@code remaining} and return true, otherwise return false.206 *207 * @param current current option208 * @param remaining remaining options209 * @return true if this option was handled by this file manager,210 * false otherwise211 * @throws IllegalArgumentException if this option to this file212 * manager is used incorrectly213 * @throws IllegalStateException if {@link #close} has been called214 * and this file manager cannot be reopened215 */216boolean handleOption(String current, Iterator<String> remaining);
217218/**219 * Determines if a location is known to this file manager.220 *221 * @param location a location222 * @return true if the location is known223 */224boolean hasLocation(Location location);
225226/**227 * Gets a {@linkplain JavaFileObject file object} for input228 * representing the specified class of the specified kind in the229 * given location.230 *231 * @param location a location232 * @param className the name of a class233 * @param kind the kind of file, must be one of {@link234 * JavaFileObject.Kind#SOURCE SOURCE} or {@link235 * JavaFileObject.Kind#CLASS CLASS}236 * @return a file object, might return {@code null} if the237 * file does not exist238 * @throws IllegalArgumentException if the location is not known239 * to this file manager and the file manager does not support240 * unknown locations, or if the kind is not valid241 * @throws IOException if an I/O error occurred, or if {@link242 * #close} has been called and this file manager cannot be243 * reopened244 * @throws IllegalStateException if {@link #close} has been called245 * and this file manager cannot be reopened246 */247JavaFileObject getJavaFileForInput(Location location,
248String className,
249Kind kind)
250throws IOException;
251252/**253 * Gets a {@linkplain JavaFileObject file object} for output254 * representing the specified class of the specified kind in the255 * given location.256 *257 * <p>Optionally, this file manager might consider the sibling as258 * a hint for where to place the output. The exact semantics of259 * this hint is unspecified. The JDK compiler, javac, for260 * example, will place class files in the same directories as261 * originating source files unless a class file output directory262 * is provided. To facilitate this behavior, javac might provide263 * the originating source file as sibling when calling this264 * method.265 *266 * @param location a location267 * @param className the name of a class268 * @param kind the kind of file, must be one of {@link269 * JavaFileObject.Kind#SOURCE SOURCE} or {@link270 * JavaFileObject.Kind#CLASS CLASS}271 * @param sibling a file object to be used as hint for placement;272 * might be {@code null}273 * @return a file object for output274 * @throws IllegalArgumentException if sibling is not known to275 * this file manager, or if the location is not known to this file276 * manager and the file manager does not support unknown277 * locations, or if the kind is not valid278 * @throws IOException if an I/O error occurred, or if {@link279 * #close} has been called and this file manager cannot be280 * reopened281 * @throws IllegalStateException {@link #close} has been called282 * and this file manager cannot be reopened283 */284JavaFileObject getJavaFileForOutput(Location location,
285String className,
286Kind kind,
287FileObject sibling)
288throws IOException;
289290/**291 * Gets a {@linkplain FileObject file object} for input292 * representing the specified <a href="JavaFileManager.html#relative_name">relative293 * name</a> in the specified package in the given location.294 *295 * <p>If the returned object represents a {@linkplain296 * JavaFileObject.Kind#SOURCE source} or {@linkplain297 * JavaFileObject.Kind#CLASS class} file, it must be an instance298 * of {@link JavaFileObject}.299 *300 * <p>Informally, the file object returned by this method is301 * located in the concatenation of the location, package name, and302 * relative name. For example, to locate the properties file303 * "resources/compiler.properties" in the package304 * "com.sun.tools.javac" in the {@linkplain305 * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method306 * might be called like so:307 *308 * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>309 *310 * <p>If the call was executed on Windows, with SOURCE_PATH set to311 * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes"</code>,312 * a valid result would be a file object representing the file313 * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.314 *315 * @param location a location316 * @param packageName a package name317 * @param relativeName a relative name318 * @return a file object, might return {@code null} if the file319 * does not exist320 * @throws IllegalArgumentException if the location is not known321 * to this file manager and the file manager does not support322 * unknown locations, or if {@code relativeName} is not valid323 * @throws IOException if an I/O error occurred, or if {@link324 * #close} has been called and this file manager cannot be325 * reopened326 * @throws IllegalStateException if {@link #close} has been called327 * and this file manager cannot be reopened328 */329FileObject getFileForInput(Location location,
330String packageName,
331String relativeName)
332throws IOException;
333334/**335 * Gets a {@linkplain FileObject file object} for output336 * representing the specified <a href="JavaFileManager.html#relative_name">relative337 * name</a> in the specified package in the given location.338 *339 * <p>Optionally, this file manager might consider the sibling as340 * a hint for where to place the output. The exact semantics of341 * this hint is unspecified. The JDK compiler, javac, for342 * example, will place class files in the same directories as343 * originating source files unless a class file output directory344 * is provided. To facilitate this behavior, javac might provide345 * the originating source file as sibling when calling this346 * method.347 *348 * <p>If the returned object represents a {@linkplain349 * JavaFileObject.Kind#SOURCE source} or {@linkplain350 * JavaFileObject.Kind#CLASS class} file, it must be an instance351 * of {@link JavaFileObject}.352 *353 * <p>Informally, the file object returned by this method is354 * located in the concatenation of the location, package name, and355 * relative name or next to the sibling argument. See {@link356 * #getFileForInput getFileForInput} for an example.357 *358 * @param location a location359 * @param packageName a package name360 * @param relativeName a relative name361 * @param sibling a file object to be used as hint for placement;362 * might be {@code null}363 * @return a file object364 * @throws IllegalArgumentException if sibling is not known to365 * this file manager, or if the location is not known to this file366 * manager and the file manager does not support unknown367 * locations, or if {@code relativeName} is not valid368 * @throws IOException if an I/O error occurred, or if {@link369 * #close} has been called and this file manager cannot be370 * reopened371 * @throws IllegalStateException if {@link #close} has been called372 * and this file manager cannot be reopened373 */374FileObject getFileForOutput(Location location,
375String packageName,
376String relativeName,
377FileObject sibling)
378throws IOException;
379380/**381 * Flushes any resources opened for output by this file manager382 * directly or indirectly. Flushing a closed file manager has no383 * effect.384 *385 * @throws IOException if an I/O error occurred386 * @see #close387 */388void flush() throws IOException;
389390/**391 * Releases any resources opened by this file manager directly or392 * indirectly. This might render this file manager useless and393 * the effect of subsequent calls to methods on this object or any394 * objects obtained through this object is undefined unless395 * explicitly allowed. However, closing a file manager which has396 * already been closed has no effect.397 *398 * @throws IOException if an I/O error occurred399 * @see #flush400 */401void close() throws IOException;
402 }