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