1 /* 2 * Copyright 2006 Sun Microsystems, Inc. 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. Sun designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 22 * CA 95054 USA or visit www.sun.com if you need additional information or 23 * have any questions. 24 */ 25 26 package javax.tools; 27 28 import java.io.File; 29 import java.io.IOException; 30 import java.util.*; 31 import java.util.concurrent.*; 32 33 /** 34 * File manager based on {@linkplain File java.io.File}. A common way 35 * to obtain an instance of this class is using {@linkplain 36 * JavaCompiler#getStandardFileManager 37 * getStandardFileManager}, for example: 38 * 39 * <pre> 40 * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); 41 * {@code DiagnosticCollector<JavaFileObject>} diagnostics = 42 * new {@code DiagnosticCollector<JavaFileObject>()}; 43 * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null); 44 * </pre> 45 * 46 * This file manager creates file objects representing regular 47 * {@linkplain File files}, 48 * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in 49 * similar file system based containers. Any file object returned 50 * from a file manager implementing this interface must observe the 51 * following behavior: 52 * 53 * <ul> 54 * <li> 55 * File names need not be canonical. 56 * </li> 57 * <li> 58 * For file objects representing regular files 59 * <ul> 60 * <li> 61 * the method <code>{@linkplain FileObject#delete()}</code> 62 * is equivalent to <code>{@linkplain File#delete()}</code>, 63 * </li> 64 * <li> 65 * the method <code>{@linkplain FileObject#getLastModified()}</code> 66 * is equivalent to <code>{@linkplain File#lastModified()}</code>, 67 * </li> 68 * <li> 69 * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>, 70 * <code>{@linkplain FileObject#openInputStream()}</code>, and 71 * <code>{@linkplain FileObject#openReader(boolean)}</code> 72 * must succeed if the following would succeed (ignoring 73 * encoding issues): 74 * <blockquote> 75 * <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> 76 * </blockquote> 77 * </li> 78 * <li> 79 * and the methods 80 * <code>{@linkplain FileObject#openOutputStream()}</code>, and 81 * <code>{@linkplain FileObject#openWriter()}</code> must 82 * succeed if the following would succeed (ignoring encoding 83 * issues): 84 * <blockquote> 85 * <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> 86 * </blockquote> 87 * </li> 88 * </ul> 89 * </li> 90 * <li> 91 * The {@linkplain java.net.URI URI} returned from 92 * <code>{@linkplain FileObject#toUri()}</code> 93 * <ul> 94 * <li> 95 * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and 96 * </li> 97 * <li> 98 * must have a {@linkplain java.net.URI#normalize() normalized} 99 * {@linkplain java.net.URI#getPath() path component} which 100 * can be resolved without any process-specific context such 101 * as the current directory (file names must be absolute). 102 * </li> 103 * </ul> 104 * </li> 105 * </ul> 106 * 107 * According to these rules, the following URIs, for example, are 108 * allowed: 109 * <ul> 110 * <li> 111 * <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code> 112 * </li> 113 * <li> 114 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class</code> 115 * </li> 116 * </ul> 117 * Whereas these are not (reason in parentheses): 118 * <ul> 119 * <li> 120 * <code>file:BobsApp/Test.java</code> (the file name is relative 121 * and depend on the current directory) 122 * </li> 123 * <li> 124 * <code>jar:lib/vendorA.jar!com/vendora/LibraryClass.class</code> 125 * (the first half of the path depends on the current directory, 126 * whereas the component after ! is legal) 127 * </li> 128 * <li> 129 * <code>Test.java</code> (this URI depends on the current 130 * directory and does not have a schema) 131 * </li> 132 * <li> 133 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code> 134 * (the path is not normalized) 135 * </li> 136 * </ul> 137 * 138 * @author Peter von der Ahé 139 * @since 1.6 140 */ 141 public interface StandardJavaFileManager extends JavaFileManager { 142 143 /** 144 * Compares two file objects and return true if they represent the 145 * same canonical file, zip file entry, or entry in any file 146 * system based container. 147 * 148 * @param a a file object 149 * @param b a file object 150 * @return true if the given file objects represent the same 151 * canonical file or zip file entry; false otherwise 152 * 153 * @throws IllegalArgumentException if either of the arguments 154 * were created with another file manager implementation 155 */ 156 boolean isSameFile(FileObject a, FileObject b); 157 158 /** 159 * Gets file objects representing the given files. 160 * 161 * @param files a list of files 162 * @return a list of file objects 163 * @throws IllegalArgumentException if the list of files includes 164 * a directory 165 */ 166 Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles( 167 Iterable<? extends File> files); 168 169 /** 170 * Gets file objects representing the given files. 171 * Convenience method equivalent to: 172 * 173 * <pre> 174 * getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files)) 175 * </pre> 176 * 177 * @param files an array of files 178 * @return a list of file objects 179 * @throws IllegalArgumentException if the array of files includes 180 * a directory 181 * @throws NullPointerException if the given array contains null 182 * elements 183 */ 184 Iterable<? extends JavaFileObject> getJavaFileObjects(File... files); 185 186 /** 187 * Gets file objects representing the given file names. 188 * 189 * @param names a list of file names 190 * @return a list of file objects 191 * @throws IllegalArgumentException if the list of file names 192 * includes a directory 193 */ 194 Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings( 195 Iterable<String> names); 196 197 /** 198 * Gets file objects representing the given file names. 199 * Convenience method equivalent to: 200 * 201 * <pre> 202 * getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names)) 203 * </pre> 204 * 205 * @param names a list of file names 206 * @return a list of file objects 207 * @throws IllegalArgumentException if the array of file names 208 * includes a directory 209 * @throws NullPointerException if the given array contains null 210 * elements 211 */ 212 Iterable<? extends JavaFileObject> getJavaFileObjects(String... names); 213 214 /** 215 * Associates the given path with the given location. Any 216 * previous value will be discarded. 217 * 218 * @param location a location 219 * @param path a list of files, if {@code null} use the default 220 * path for this location 221 * @see #getLocation 222 * @throws IllegalArgumentException if location is an output 223 * location and path does not contain exactly one element 224 * @throws IOException if location is an output location and path 225 * does not represent an existing directory 226 */ 227 void setLocation(Location location, Iterable<? extends File> path) 228 throws IOException; 229 230 /** 231 * Gets the path associated with the given location. 232 * 233 * @param location a location 234 * @return a list of files or {@code null} if this location has no 235 * associated path 236 * @see #setLocation 237 */ 238 Iterable<? extends File> getLocation(Location location); 239 240 }