StandardJavaFileManager.java revision 3392:04fcbc7234a4
1/* 2 * Copyright (c) 2006, 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 26package javax.tools; 27 28import java.io.File; 29import java.io.IOException; 30import java.nio.file.Path; 31import java.util.Arrays; 32import java.util.Collection; 33 34import static javax.tools.FileManagerUtils.*; 35 36/** 37 * File manager based on {@linkplain File java.io.File} and {@linkplain Path java.nio.file.Path}. 38 * 39 * A common way to obtain an instance of this class is using 40 * {@linkplain JavaCompiler#getStandardFileManager getStandardFileManager}, for example: 41 * 42 * <pre> 43 * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); 44 * {@code DiagnosticCollector<JavaFileObject>} diagnostics = 45 * new {@code DiagnosticCollector<JavaFileObject>()}; 46 * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null); 47 * </pre> 48 * 49 * This file manager creates file objects representing regular 50 * {@linkplain File files}, 51 * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in 52 * similar file system based containers. Any file object returned 53 * from a file manager implementing this interface must observe the 54 * following behavior: 55 * 56 * <ul> 57 * <li> 58 * File names need not be canonical. 59 * </li> 60 * <li> 61 * For file objects representing regular files 62 * <ul> 63 * <li> 64 * the method <code>{@linkplain FileObject#delete()}</code> 65 * is equivalent to <code>{@linkplain File#delete()}</code>, 66 * </li> 67 * <li> 68 * the method <code>{@linkplain FileObject#getLastModified()}</code> 69 * is equivalent to <code>{@linkplain File#lastModified()}</code>, 70 * </li> 71 * <li> 72 * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>, 73 * <code>{@linkplain FileObject#openInputStream()}</code>, and 74 * <code>{@linkplain FileObject#openReader(boolean)}</code> 75 * must succeed if the following would succeed (ignoring 76 * encoding issues): 77 * <blockquote> 78 * <pre>new {@linkplain java.io.FileInputStream#FileInputStream(File) FileInputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre> 79 * </blockquote> 80 * </li> 81 * <li> 82 * and the methods 83 * <code>{@linkplain FileObject#openOutputStream()}</code>, and 84 * <code>{@linkplain FileObject#openWriter()}</code> must 85 * succeed if the following would succeed (ignoring encoding 86 * issues): 87 * <blockquote> 88 * <pre>new {@linkplain java.io.FileOutputStream#FileOutputStream(File) FileOutputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre> 89 * </blockquote> 90 * </li> 91 * </ul> 92 * </li> 93 * <li> 94 * The {@linkplain java.net.URI URI} returned from 95 * <code>{@linkplain FileObject#toUri()}</code> 96 * <ul> 97 * <li> 98 * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and 99 * </li> 100 * <li> 101 * must have a {@linkplain java.net.URI#normalize() normalized} 102 * {@linkplain java.net.URI#getPath() path component} which 103 * can be resolved without any process-specific context such 104 * as the current directory (file names must be absolute). 105 * </li> 106 * </ul> 107 * </li> 108 * </ul> 109 * 110 * According to these rules, the following URIs, for example, are 111 * allowed: 112 * <ul> 113 * <li> 114 * <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code> 115 * </li> 116 * <li> 117 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!/com/vendora/LibraryClass.class</code> 118 * </li> 119 * </ul> 120 * Whereas these are not (reason in parentheses): 121 * <ul> 122 * <li> 123 * <code>file:BobsApp/Test.java</code> (the file name is relative 124 * and depend on the current directory) 125 * </li> 126 * <li> 127 * <code>jar:lib/vendorA.jar!/com/vendora/LibraryClass.class</code> 128 * (the first half of the path depends on the current directory, 129 * whereas the component after ! is legal) 130 * </li> 131 * <li> 132 * <code>Test.java</code> (this URI depends on the current 133 * directory and does not have a schema) 134 * </li> 135 * <li> 136 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code> 137 * (the path is not normalized) 138 * </li> 139 * </ul> 140 * 141 * <p>All implementations of this interface must support Path objects representing 142 * files in the {@linkplain java.nio.file.FileSystems#getDefault() default file system.} 143 * It is recommended that implementations should support Path objects from any filesystem.</p> 144 * 145 * @author Peter von der Ahé 146 * @since 1.6 147 */ 148public interface StandardJavaFileManager extends JavaFileManager { 149 150 /** 151 * Compares two file objects and return true if they represent the 152 * same canonical file, zip file entry, or entry in any file 153 * system based container. 154 * 155 * @param a a file object 156 * @param b a file object 157 * @return true if the given file objects represent the same 158 * canonical file, zip file entry or path; false otherwise 159 * 160 * @throws IllegalArgumentException if either of the arguments 161 * were created with another file manager implementation 162 */ 163 @Override 164 boolean isSameFile(FileObject a, FileObject b); 165 166 /** 167 * Returns file objects representing the given files. 168 * 169 * @param files a list of files 170 * @return a list of file objects 171 * @throws IllegalArgumentException if the list of files includes 172 * a directory 173 */ 174 Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles( 175 Iterable<? extends File> files); 176 177 /** 178 * Returns file objects representing the given paths. 179 * 180 * @implSpec 181 * The default implementation converts each path to a file and calls 182 * {@link #getJavaFileObjectsFromFiles getJavaObjectsFromFiles}. 183 * IllegalArgumentException will be thrown if any of the paths 184 * cannot be converted to a file. 185 * 186 * @param paths a list of paths 187 * @return a list of file objects 188 * @throws IllegalArgumentException if the list of paths includes 189 * a directory or if this file manager does not support any of the 190 * given paths. 191 * 192 * @since 9 193 */ 194 default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths( 195 Iterable<? extends Path> paths) { 196 return getJavaFileObjectsFromFiles(asFiles(paths)); 197 } 198 199 /** 200 * Returns file objects representing the given files. 201 * Convenience method equivalent to: 202 * 203 * <pre> 204 * getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files)) 205 * </pre> 206 * 207 * @param files an array of files 208 * @return a list of file objects 209 * @throws IllegalArgumentException if the array of files includes 210 * a directory 211 * @throws NullPointerException if the given array contains null 212 * elements 213 */ 214 Iterable<? extends JavaFileObject> getJavaFileObjects(File... files); 215 216 /** 217 * Returns file objects representing the given paths. 218 * Convenience method equivalent to: 219 * 220 * <pre> 221 * getJavaFileObjectsFromPaths({@linkplain java.util.Arrays#asList Arrays.asList}(paths)) 222 * </pre> 223 * 224 * @param paths an array of paths 225 * @return a list of file objects 226 * @throws IllegalArgumentException if the array of files includes 227 * a directory 228 * @throws NullPointerException if the given array contains null 229 * elements 230 * 231 * @since 9 232 */ 233 default Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths) { 234 return getJavaFileObjectsFromPaths(Arrays.asList(paths)); 235 } 236 237 /** 238 * Returns file objects representing the given file names. 239 * 240 * @param names a list of file names 241 * @return a list of file objects 242 * @throws IllegalArgumentException if the list of file names 243 * includes a directory 244 */ 245 Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings( 246 Iterable<String> names); 247 248 /** 249 * Returns file objects representing the given file names. 250 * Convenience method equivalent to: 251 * 252 * <pre> 253 * getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names)) 254 * </pre> 255 * 256 * @param names a list of file names 257 * @return a list of file objects 258 * @throws IllegalArgumentException if the array of file names 259 * includes a directory 260 * @throws NullPointerException if the given array contains null 261 * elements 262 */ 263 Iterable<? extends JavaFileObject> getJavaFileObjects(String... names); 264 265 /** 266 * Associates the given search path with the given location. Any 267 * previous value will be discarded. 268 * 269 * @param location a location 270 * @param files a list of files, if {@code null} use the default 271 * search path for this location 272 * @see #getLocation 273 * @throws IllegalArgumentException if {@code location} is an output 274 * location and {@code files} does not contain exactly one element 275 * @throws IOException if {@code location} is an output location and 276 * does not represent an existing directory 277 */ 278 void setLocation(Location location, Iterable<? extends File> files) 279 throws IOException; 280 281 /** 282 * Associates the given search path with the given location. Any 283 * previous value will be discarded. 284 * 285 * @apiNote 286 * The type of the {@code paths} parameter is a {@code Collection} 287 * and not {@code Iterable}. This is to prevent the possibility of 288 * accidentally calling the method with a single {@code Path} as 289 * the second argument, because although {@code Path} implements 290 * {@code Iterable<Path>}, it would almost never be correct to call 291 * this method with a single {@code Path} and have it be treated as 292 * an {@code Iterable} of its components. 293 * 294 * 295 * @implSpec 296 * The default implementation converts each path to a file and calls 297 * {@link #getJavaFileObjectsFromFiles getJavaObjectsFromFiles}. 298 * IllegalArgumentException will be thrown if any of the paths 299 * cannot be converted to a file. 300 * 301 * @param location a location 302 * @param paths a list of paths, if {@code null} use the default 303 * search path for this location 304 * @see #getLocation 305 * @throws IllegalArgumentException if {@code location} is an output 306 * location and {@code paths} does not contain exactly one element 307 * or if this file manager does not support any of the given paths 308 * @throws IOException if {@code location} is an output location and 309 * {@code paths} does not represent an existing directory 310 * 311 * @since 9 312 */ 313 default void setLocationFromPaths(Location location, Collection<? extends Path> paths) 314 throws IOException { 315 setLocation(location, asFiles(paths)); 316 } 317 318 /** 319 * Returns the search path associated with the given location. 320 * 321 * @param location a location 322 * @return a list of files or {@code null} if this location has no 323 * associated search path 324 * @throws IllegalStateException if any element of the search path 325 * cannot be converted to a {@linkplain File}. 326 * 327 * @see #setLocation 328 * @see Path#toFile 329 */ 330 Iterable<? extends File> getLocation(Location location); 331 332 /** 333 * Returns the search path associated with the given location. 334 * 335 * @implSpec 336 * The default implementation calls {@link #getLocation getLocation} 337 * and then returns an {@code Iterable} formed by calling {@code toPath()} 338 * on each {@code File} returned from {@code getLocation}. 339 * 340 * @param location a location 341 * @return a list of paths or {@code null} if this location has no 342 * associated search path 343 * 344 * @see #setLocationFromPaths 345 * @since 9 346 */ 347 default Iterable<? extends Path> getLocationAsPaths(Location location) { 348 return asPaths(getLocation(location)); 349 } 350 351 /** 352 * Returns the path, if any, underlying this file object (optional operation). 353 * File objects derived from a {@link java.nio.file.FileSystem FileSystem}, 354 * including the default file system, typically have a corresponding underlying 355 * {@link java.nio.file.Path Path} object. In such cases, this method may be 356 * used to access that object. 357 * 358 * @implSpec 359 * The default implementation throws {@link UnsupportedOperationException} 360 * for all files. 361 * 362 * @param file a file object 363 * @return a path representing the same underlying file system artifact 364 * @throws IllegalArgumentException if the file object does not have an underlying path 365 * @throws UnsupportedOperationException if the operation is not supported by this file manager 366 * 367 * @since 9 368 */ 369 default Path asPath(FileObject file) { 370 throw new UnsupportedOperationException(); 371 } 372 373 /** 374 * Factory to create {@code Path} objects from strings. 375 * 376 * @since 9 377 */ 378 interface PathFactory { 379 /** 380 * Converts a path string, or a sequence of strings that when joined form a path string, to a Path. 381 * 382 * @param first the path string or initial part of the path string 383 * @param more additional strings to be joined to form the path string 384 * @return the resulting {@code Path} 385 */ 386 Path getPath(String first, String... more); 387 } 388 389 /** 390 * Specify a factory that can be used to generate a path from a string, or series of strings. 391 * 392 * If this method is not called, a factory whose {@code getPath} method is 393 * equivalent to calling 394 * {@link java.nio.file.Paths#get(String, String...) java.nio.file.Paths.get(first, more)} 395 * will be used. 396 * 397 * @implSpec 398 * The default implementation of this method ignores the factory that is provided. 399 * 400 * @param f the factory 401 * 402 * @since 9 403 */ 404 default void setPathFactory(PathFactory f) { } 405} 406