StandardJavaFileManager.java revision 2571:10fc81ac75b4
1238384Sjkim/* 2238384Sjkim * Copyright (c) 2006, 2014, Oracle and/or its affiliates. All rights reserved. 3238384Sjkim * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4238384Sjkim * 5238384Sjkim * This code is free software; you can redistribute it and/or modify it 6238384Sjkim * under the terms of the GNU General Public License version 2 only, as 7238384Sjkim * published by the Free Software Foundation. Oracle designates this 8238384Sjkim * particular file as subject to the "Classpath" exception as provided 9238384Sjkim * by Oracle in the LICENSE file that accompanied this code. 10238384Sjkim * 11238384Sjkim * This code is distributed in the hope that it will be useful, but WITHOUT 12238384Sjkim * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13238384Sjkim * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14238384Sjkim * version 2 for more details (a copy is included in the LICENSE file that 15238384Sjkim * accompanied this code). 16238384Sjkim * 17238384Sjkim * You should have received a copy of the GNU General Public License version 18238384Sjkim * 2 along with this work; if not, write to the Free Software Foundation, 19238384Sjkim * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20238384Sjkim * 21238384Sjkim * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22238384Sjkim * or visit www.oracle.com if you need additional information or have any 23238384Sjkim * questions. 24238384Sjkim */ 25238384Sjkim 26238384Sjkimpackage javax.tools; 27238384Sjkim 28238384Sjkimimport java.io.File; 29238384Sjkimimport java.io.IOException; 30238384Sjkimimport java.util.*; 31238384Sjkim 32280297Sjkim/** 33280297Sjkim * File manager based on {@linkplain File java.io.File}. A common way 34280297Sjkim * to obtain an instance of this class is using {@linkplain 35280297Sjkim * JavaCompiler#getStandardFileManager 36280297Sjkim * getStandardFileManager}, for example: 37238384Sjkim * 38280297Sjkim * <pre> 39280297Sjkim * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); 40280297Sjkim * {@code DiagnosticCollector<JavaFileObject>} diagnostics = 41352193Sjkim * new {@code DiagnosticCollector<JavaFileObject>()}; 42238384Sjkim * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null); 43280297Sjkim * </pre> 44238384Sjkim * 45280297Sjkim * This file manager creates file objects representing regular 46280297Sjkim * {@linkplain File files}, 47280297Sjkim * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in 48280297Sjkim * similar file system based containers. Any file object returned 49280297Sjkim * from a file manager implementing this interface must observe the 50238384Sjkim * following behavior: 51238384Sjkim * 52238384Sjkim * <ul> 53238384Sjkim * <li> 54280297Sjkim * File names need not be canonical. 55280297Sjkim * </li> 56280297Sjkim * <li> 57280297Sjkim * For file objects representing regular files 58280297Sjkim * <ul> 59238384Sjkim * <li> 60238384Sjkim * the method <code>{@linkplain FileObject#delete()}</code> 61238384Sjkim * is equivalent to <code>{@linkplain File#delete()}</code>, 62280297Sjkim * </li> 63280297Sjkim * <li> 64280297Sjkim * the method <code>{@linkplain FileObject#getLastModified()}</code> 65280297Sjkim * is equivalent to <code>{@linkplain File#lastModified()}</code>, 66280297Sjkim * </li> 67280297Sjkim * <li> 68280297Sjkim * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>, 69280297Sjkim * <code>{@linkplain FileObject#openInputStream()}</code>, and 70280297Sjkim * <code>{@linkplain FileObject#openReader(boolean)}</code> 71280297Sjkim * must succeed if the following would succeed (ignoring 72280297Sjkim * encoding issues): 73280297Sjkim * <blockquote> 74280297Sjkim * <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> 75280297Sjkim * </blockquote> 76280297Sjkim * </li> 77280297Sjkim * <li> 78280297Sjkim * and the methods 79280297Sjkim * <code>{@linkplain FileObject#openOutputStream()}</code>, and 80280297Sjkim * <code>{@linkplain FileObject#openWriter()}</code> must 81280297Sjkim * succeed if the following would succeed (ignoring encoding 82280297Sjkim * issues): 83280297Sjkim * <blockquote> 84280297Sjkim * <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> 85280297Sjkim * </blockquote> 86280297Sjkim * </li> 87280297Sjkim * </ul> 88280297Sjkim * </li> 89280297Sjkim * <li> 90280297Sjkim * The {@linkplain java.net.URI URI} returned from 91280297Sjkim * <code>{@linkplain FileObject#toUri()}</code> 92280297Sjkim * <ul> 93280297Sjkim * <li> 94280297Sjkim * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and 95280297Sjkim * </li> 96280297Sjkim * <li> 97280297Sjkim * must have a {@linkplain java.net.URI#normalize() normalized} 98280297Sjkim * {@linkplain java.net.URI#getPath() path component} which 99280297Sjkim * can be resolved without any process-specific context such 100280297Sjkim * as the current directory (file names must be absolute). 101280297Sjkim * </li> 102280297Sjkim * </ul> 103280297Sjkim * </li> 104280297Sjkim * </ul> 105280297Sjkim * 106280297Sjkim * According to these rules, the following URIs, for example, are 107280297Sjkim * allowed: 108280297Sjkim * <ul> 109280297Sjkim * <li> 110280297Sjkim * <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code> 111280297Sjkim * </li> 112280297Sjkim * <li> 113238384Sjkim * <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class</code> 114280297Sjkim * </li> 115280297Sjkim * </ul> 116238384Sjkim * Whereas these are not (reason in parentheses): 117238384Sjkim * <ul> 118238384Sjkim * <li> 119238384Sjkim * <code>file:BobsApp/Test.java</code> (the file name is relative 120238384Sjkim * and depend on the current directory) 121238384Sjkim * </li> 122238384Sjkim * <li> 123238384Sjkim * <code>jar:lib/vendorA.jar!com/vendora/LibraryClass.class</code> 124238384Sjkim * (the first half of the path depends on the current directory, 125238384Sjkim * whereas the component after ! is legal) 126238384Sjkim * </li> 127238384Sjkim * <li> 128280297Sjkim * <code>Test.java</code> (this URI depends on the current 129238384Sjkim * directory and does not have a schema) 130238384Sjkim * </li> 131238384Sjkim * <li> 132238384Sjkim * <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code> 133238384Sjkim * (the path is not normalized) 134238384Sjkim * </li> 135238384Sjkim * </ul> 136238384Sjkim * 137280297Sjkim * @author Peter von der Ahé 138280297Sjkim * @since 1.6 139280297Sjkim */ 140280297Sjkimpublic interface StandardJavaFileManager extends JavaFileManager { 141238384Sjkim 142280297Sjkim /** 143280297Sjkim * Compares two file objects and return true if they represent the 144280297Sjkim * same canonical file, zip file entry, or entry in any file 145280297Sjkim * system based container. 146280297Sjkim * 147280297Sjkim * @param a a file object 148280297Sjkim * @param b a file object 149280297Sjkim * @return true if the given file objects represent the same 150280297Sjkim * canonical file or zip file entry; false otherwise 151280297Sjkim * 152280297Sjkim * @throws IllegalArgumentException if either of the arguments 153238384Sjkim * were created with another file manager implementation 154280297Sjkim */ 155280297Sjkim boolean isSameFile(FileObject a, FileObject b); 156280297Sjkim 157280297Sjkim /** 158238384Sjkim * Returns file objects representing the given files. 159280297Sjkim * 160280297Sjkim * @param files a list of files 161280297Sjkim * @return a list of file objects 162280297Sjkim * @throws IllegalArgumentException if the list of files includes 163280297Sjkim * a directory 164280297Sjkim */ 165280297Sjkim Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles( 166280297Sjkim Iterable<? extends File> files); 167280297Sjkim 168280297Sjkim /** 169280297Sjkim * Returns file objects representing the given files. 170280297Sjkim * Convenience method equivalent to: 171238384Sjkim * 172238384Sjkim * <pre> 173238384Sjkim * getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files)) 174280297Sjkim * </pre> 175280297Sjkim * 176352193Sjkim * @param files an array of files 177238384Sjkim * @return a list of file objects 178352193Sjkim * @throws IllegalArgumentException if the array of files includes 179280297Sjkim * a directory 180280297Sjkim * @throws NullPointerException if the given array contains null 181280297Sjkim * elements 182352193Sjkim */ 183352193Sjkim Iterable<? extends JavaFileObject> getJavaFileObjects(File... files); 184280297Sjkim 185280297Sjkim /** 186280297Sjkim * Returns file objects representing the given file names. 187280297Sjkim * 188280297Sjkim * @param names a list of file names 189280297Sjkim * @return a list of file objects 190238384Sjkim * @throws IllegalArgumentException if the list of file names 191238384Sjkim * includes a directory 192238384Sjkim */ 193280297Sjkim Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings( 194352193Sjkim Iterable<String> names); 195352193Sjkim 196352193Sjkim /** 197280297Sjkim * Returns file objects representing the given file names. 198238384Sjkim * Convenience method equivalent to: 199280297Sjkim * 200280297Sjkim * <pre> 201280297Sjkim * getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names)) 202280297Sjkim * </pre> 203238384Sjkim * 204238384Sjkim * @param names a list of file names 205280297Sjkim * @return a list of file objects 206280297Sjkim * @throws IllegalArgumentException if the array of file names 207280297Sjkim * includes a directory 208280297Sjkim * @throws NullPointerException if the given array contains null 209280297Sjkim * elements 210280297Sjkim */ 211280297Sjkim Iterable<? extends JavaFileObject> getJavaFileObjects(String... names); 212280297Sjkim 213280297Sjkim /** 214280297Sjkim * Associates the given path with the given location. Any 215280297Sjkim * previous value will be discarded. 216238384Sjkim * 217238384Sjkim * @param location a location 218280297Sjkim * @param path a list of files, if {@code null} use the default 219280297Sjkim * path for this location 220280297Sjkim * @see #getLocation 221280297Sjkim * @throws IllegalArgumentException if location is an output 222280297Sjkim * location and path does not contain exactly one element 223280297Sjkim * @throws IOException if location is an output location and path 224280297Sjkim * does not represent an existing directory 225280297Sjkim */ 226280297Sjkim void setLocation(Location location, Iterable<? extends File> path) 227280297Sjkim throws IOException; 228280297Sjkim 229238384Sjkim /** 230238384Sjkim * Returns the path associated with the given location. 231238384Sjkim * 232280297Sjkim * @param location a location 233280297Sjkim * @return a list of files or {@code null} if this location has no 234280297Sjkim * associated path 235280297Sjkim * @see #setLocation 236280297Sjkim */ 237280297Sjkim Iterable<? extends File> getLocation(Location location); 238280297Sjkim 239280297Sjkim} 240280297Sjkim