JavaFileManager.java revision 2571:10fc81ac75b4
1/* 2 * Copyright (c) 2005, 2014, 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 26package javax.tools; 27 28import java.io.Closeable; 29import java.io.Flushable; 30import java.io.IOException; 31import java.util.Iterator; 32import java.util.Set; 33import static javax.tools.JavaFileObject.Kind; 34 35/** 36 * File manager for tools operating on Java™ programming language 37 * source and class files. In this context, <em>file</em> means an 38 * abstraction of regular files and other sources of data. 39 * 40 * <p>When constructing new JavaFileObjects, the file manager must 41 * determine where to create them. For example, if a file manager 42 * manages regular files on a file system, it would most likely have a 43 * current/working directory to use as default location when creating 44 * or finding files. A number of hints can be provided to a file 45 * manager as to where to create files. Any file manager might choose 46 * to ignore these hints. 47 * 48 * <p>Some methods in this interface use class names. Such class 49 * names must be given in the Java Virtual Machine internal form of 50 * fully qualified class and interface names. For convenience '.' 51 * and '/' are interchangeable. The internal form is defined in 52 * chapter four of 53 * <cite>The Java™ Virtual Machine Specification</cite>. 54 55 * <blockquote><p> 56 * <i>Discussion:</i> this means that the names 57 * "java/lang.package-info", "java/lang/package-info", 58 * "java.lang.package-info", are valid and equivalent. Compare to 59 * binary name as defined in 60 * <cite>The Java™ 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 treated 65 * as case-sensitive. For example, some file systems have 66 * case-insensitive, case-aware file names. File objects representing 67 * such files should take care to preserve case by using {@link 68 * java.io.File#getCanonicalFile} or similar means. If the system is 69 * not case-aware, file objects must use other means to preserve case. 70 * 71 * <p><em><a name="relative_name">Relative names</a>:</em> some 72 * methods in this interface use relative names. A relative name is a 73 * non-null, non-empty sequence of path segments separated by '/'. 74 * '.' or '..' are invalid path segments. A valid relative name must 75 * match the "path-rootless" rule of <a 76 * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, 77 * section 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 support 85 * multi-threaded access, that is, be synchronized. However, it must 86 * support concurrent access to different file objects created by this 87 * object. 88 * 89 * <p><em>Implementation note:</em> a consequence of this requirement 90 * is that a trivial implementation of output to a {@linkplain 91 * java.util.jar.JarOutputStream} is not a sufficient implementation. 92 * That is, rather than creating a JavaFileObject that returns the 93 * JarOutputStream directly, the contents must be cached until closed 94 * and then written to the JarOutputStream. 95 * 96 * <p>Unless explicitly allowed, all methods in this interface might 97 * throw a NullPointerException if given a {@code null} argument. 98 * 99 * @author Peter von der Ahé 100 * @author Jonathan Gibbons 101 * @see JavaFileObject 102 * @see FileObject 103 * @since 1.6 104 */ 105public interface JavaFileManager extends Closeable, Flushable, OptionChecker { 106 107 /** 108 * Interface for locations of file objects. Used by file managers 109 * to determine where to place or search for file objects. 110 */ 111 interface Location { 112 /** 113 * Returns the name of this location. 114 * 115 * @return a name 116 */ 117 String getName(); 118 119 /** 120 * Determines if this is an output location. An output 121 * location is a location that is conventionally used for 122 * output. 123 * 124 * @return true if this is an output location, false otherwise 125 */ 126 boolean isOutputLocation(); 127 } 128 129 /** 130 * Returns a class loader for loading plug-ins from the given 131 * location. For example, to load annotation processors, a 132 * compiler will request a class loader for the {@link 133 * StandardLocation#ANNOTATION_PROCESSOR_PATH 134 * ANNOTATION_PROCESSOR_PATH} location. 135 * 136 * @param location a location 137 * @return a class loader for the given location; or {@code null} 138 * if loading plug-ins from the given location is disabled or if 139 * the location is not known 140 * @throws SecurityException if a class loader can not be created 141 * in the current security context 142 * @throws IllegalStateException if {@link #close} has been called 143 * and this file manager cannot be reopened 144 */ 145 ClassLoader getClassLoader(Location location); 146 147 /** 148 * Lists all file objects matching the given criteria in the given 149 * location. List file objects in "subpackages" if recurse is 150 * true. 151 * 152 * <p>Note: even if the given location is unknown to this file 153 * manager, it may not return {@code null}. Also, an unknown 154 * location may not cause an exception. 155 * 156 * @param location a location 157 * @param packageName a package name 158 * @param kinds return objects only of these kinds 159 * @param recurse if true include "subpackages" 160 * @return an Iterable of file objects matching the given criteria 161 * @throws IOException if an I/O error occurred, or if {@link 162 * #close} has been called and this file manager cannot be 163 * reopened 164 * @throws IllegalStateException if {@link #close} has been called 165 * and this file manager cannot be reopened 166 */ 167 Iterable<JavaFileObject> list(Location location, 168 String packageName, 169 Set<Kind> kinds, 170 boolean recurse) 171 throws IOException; 172 173 /** 174 * Infers a binary name of a file object based on a location. The 175 * binary name returned might not be a valid binary name according to 176 * <cite>The Java™ Language Specification</cite>. 177 * 178 * @param location a location 179 * @param file a file object 180 * @return a binary name or {@code null} the file object is not 181 * found in the given location 182 * @throws IllegalStateException if {@link #close} has been called 183 * and this file manager cannot be reopened 184 */ 185 String inferBinaryName(Location location, JavaFileObject file); 186 187 /** 188 * Compares two file objects and return true if they represent the 189 * same underlying object. 190 * 191 * @param a a file object 192 * @param b a file object 193 * @return true if the given file objects represent the same 194 * underlying object 195 * 196 * @throws IllegalArgumentException if either of the arguments 197 * were created with another file manager and this file manager 198 * does not support foreign file objects 199 */ 200 boolean isSameFile(FileObject a, FileObject b); 201 202 /** 203 * Handles one option. If {@code current} is an option to this 204 * file manager it will consume any arguments to that option from 205 * {@code remaining} and return true, otherwise return false. 206 * 207 * @param current current option 208 * @param remaining remaining options 209 * @return true if this option was handled by this file manager, 210 * false otherwise 211 * @throws IllegalArgumentException if this option to this file 212 * manager is used incorrectly 213 * @throws IllegalStateException if {@link #close} has been called 214 * and this file manager cannot be reopened 215 */ 216 boolean handleOption(String current, Iterator<String> remaining); 217 218 /** 219 * Determines if a location is known to this file manager. 220 * 221 * @param location a location 222 * @return true if the location is known 223 */ 224 boolean hasLocation(Location location); 225 226 /** 227 * Returns a {@linkplain JavaFileObject file object} for input 228 * representing the specified class of the specified kind in the 229 * given location. 230 * 231 * @param location a location 232 * @param className the name of a class 233 * @param kind the kind of file, must be one of {@link 234 * JavaFileObject.Kind#SOURCE SOURCE} or {@link 235 * JavaFileObject.Kind#CLASS CLASS} 236 * @return a file object, might return {@code null} if the 237 * file does not exist 238 * @throws IllegalArgumentException if the location is not known 239 * to this file manager and the file manager does not support 240 * unknown locations, or if the kind is not valid 241 * @throws IOException if an I/O error occurred, or if {@link 242 * #close} has been called and this file manager cannot be 243 * reopened 244 * @throws IllegalStateException if {@link #close} has been called 245 * and this file manager cannot be reopened 246 */ 247 JavaFileObject getJavaFileForInput(Location location, 248 String className, 249 Kind kind) 250 throws IOException; 251 252 /** 253 * Returns a {@linkplain JavaFileObject file object} for output 254 * representing the specified class of the specified kind in the 255 * given location. 256 * 257 * <p>Optionally, this file manager might consider the sibling as 258 * a hint for where to place the output. The exact semantics of 259 * this hint is unspecified. The JDK compiler, javac, for 260 * example, will place class files in the same directories as 261 * originating source files unless a class file output directory 262 * is provided. To facilitate this behavior, javac might provide 263 * the originating source file as sibling when calling this 264 * method. 265 * 266 * @param location a location 267 * @param className the name of a class 268 * @param kind the kind of file, must be one of {@link 269 * JavaFileObject.Kind#SOURCE SOURCE} or {@link 270 * 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 output 274 * @throws IllegalArgumentException if sibling is not known to 275 * this file manager, or if the location is not known to this file 276 * manager and the file manager does not support unknown 277 * locations, or if the kind is not valid 278 * @throws IOException if an I/O error occurred, or if {@link 279 * #close} has been called and this file manager cannot be 280 * reopened 281 * @throws IllegalStateException {@link #close} has been called 282 * and this file manager cannot be reopened 283 */ 284 JavaFileObject getJavaFileForOutput(Location location, 285 String className, 286 Kind kind, 287 FileObject sibling) 288 throws IOException; 289 290 /** 291 * Returns a {@linkplain FileObject file object} for input 292 * representing the specified <a href="JavaFileManager.html#relative_name">relative 293 * name</a> in the specified package in the given location. 294 * 295 * <p>If the returned object represents a {@linkplain 296 * JavaFileObject.Kind#SOURCE source} or {@linkplain 297 * JavaFileObject.Kind#CLASS class} file, it must be an instance 298 * of {@link JavaFileObject}. 299 * 300 * <p>Informally, the file object returned by this method is 301 * located in the concatenation of the location, package name, and 302 * relative name. For example, to locate the properties file 303 * "resources/compiler.properties" in the package 304 * "com.sun.tools.javac" in the {@linkplain 305 * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method 306 * 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 to 311 * <code>"C:\Documents and Settings\UncleBob\src\share\classes"</code>, 312 * a valid result would be a file object representing the file 313 * <code>"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>. 314 * 315 * @param location a location 316 * @param packageName a package name 317 * @param relativeName a relative name 318 * @return a file object, might return {@code null} if the file 319 * does not exist 320 * @throws IllegalArgumentException if the location is not known 321 * to this file manager and the file manager does not support 322 * unknown locations, or if {@code relativeName} is not valid 323 * @throws IOException if an I/O error occurred, or if {@link 324 * #close} has been called and this file manager cannot be 325 * reopened 326 * @throws IllegalStateException if {@link #close} has been called 327 * and this file manager cannot be reopened 328 */ 329 FileObject getFileForInput(Location location, 330 String packageName, 331 String relativeName) 332 throws IOException; 333 334 /** 335 * Returns a {@linkplain FileObject file object} for output 336 * representing the specified <a href="JavaFileManager.html#relative_name">relative 337 * name</a> in the specified package in the given location. 338 * 339 * <p>Optionally, this file manager might consider the sibling as 340 * a hint for where to place the output. The exact semantics of 341 * this hint is unspecified. The JDK compiler, javac, for 342 * example, will place class files in the same directories as 343 * originating source files unless a class file output directory 344 * is provided. To facilitate this behavior, javac might provide 345 * the originating source file as sibling when calling this 346 * method. 347 * 348 * <p>If the returned object represents a {@linkplain 349 * JavaFileObject.Kind#SOURCE source} or {@linkplain 350 * JavaFileObject.Kind#CLASS class} file, it must be an instance 351 * of {@link JavaFileObject}. 352 * 353 * <p>Informally, the file object returned by this method is 354 * located in the concatenation of the location, package name, and 355 * relative name or next to the sibling argument. See {@link 356 * #getFileForInput getFileForInput} for an example. 357 * 358 * @param location a location 359 * @param packageName a package name 360 * @param relativeName a relative name 361 * @param sibling a file object to be used as hint for placement; 362 * might be {@code null} 363 * @return a file object 364 * @throws IllegalArgumentException if sibling is not known to 365 * this file manager, or if the location is not known to this file 366 * manager and the file manager does not support unknown 367 * locations, or if {@code relativeName} is not valid 368 * @throws IOException if an I/O error occurred, or if {@link 369 * #close} has been called and this file manager cannot be 370 * reopened 371 * @throws IllegalStateException if {@link #close} has been called 372 * and this file manager cannot be reopened 373 */ 374 FileObject getFileForOutput(Location location, 375 String packageName, 376 String relativeName, 377 FileObject sibling) 378 throws IOException; 379 380 /** 381 * Flushes any resources opened for output by this file manager 382 * directly or indirectly. Flushing a closed file manager has no 383 * effect. 384 * 385 * @throws IOException if an I/O error occurred 386 * @see #close 387 */ 388 void flush() throws IOException; 389 390 /** 391 * Releases any resources opened by this file manager directly or 392 * indirectly. This might render this file manager useless and 393 * the effect of subsequent calls to methods on this object or any 394 * objects obtained through this object is undefined unless 395 * explicitly allowed. However, closing a file manager which has 396 * already been closed has no effect. 397 * 398 * @throws IOException if an I/O error occurred 399 * @see #flush 400 */ 401 void close() throws IOException; 402} 403