001 /* 002 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. 003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 004 * 005 * This code is free software; you can redistribute it and/or modify it 006 * under the terms of the GNU General Public License version 2 only, as 007 * published by the Free Software Foundation. Sun designates this 008 * particular file as subject to the "Classpath" exception as provided 009 * by Sun in the LICENSE file that accompanied this code. 010 * 011 * This code is distributed in the hope that it will be useful, but WITHOUT 012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 014 * version 2 for more details (a copy is included in the LICENSE file that 015 * accompanied this code). 016 * 017 * You should have received a copy of the GNU General Public License version 018 * 2 along with this work; if not, write to the Free Software Foundation, 019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 020 * 021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 022 * CA 95054 USA or visit www.sun.com if you need additional information or 023 * have any questions. 024 */ 025 026 package javax.tools; 027 028 import java.io.File; 029 import java.io.IOException; 030 import java.util.*; 031 import java.util.concurrent.*; 032 033 /** 034 * File manager based on {@linkplain File java.io.File}. A common way 035 * to obtain an instance of this class is using {@linkplain 036 * JavaCompiler#getStandardFileManager 037 * getStandardFileManager}, for example: 038 * 039 * <pre> 040 * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); 041 * {@code DiagnosticCollector<JavaFileObject>} diagnostics = 042 * new {@code DiagnosticCollector<JavaFileObject>()}; 043 * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null); 044 * </pre> 045 * 046 * This file manager creates file objects representing regular 047 * {@linkplain File files}, 048 * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in 049 * similar file system based containers. Any file object returned 050 * from a file manager implementing this interface must observe the 051 * following behavior: 052 * 053 * <ul> 054 * <li> 055 * File names need not be canonical. 056 * </li> 057 * <li> 058 * For file objects representing regular files 059 * <ul> 060 * <li> 061 * the method <code>{@linkplain FileObject#delete()}</code> 062 * is equivalent to <code>{@linkplain File#delete()}</code>, 063 * </li> 064 * <li> 065 * the method <code>{@linkplain FileObject#getLastModified()}</code> 066 * is equivalent to <code>{@linkplain File#lastModified()}</code>, 067 * </li> 068 * <li> 069 * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>, 070 * <code>{@linkplain FileObject#openInputStream()}</code>, and 071 * <code>{@linkplain FileObject#openReader(boolean)}</code> 072 * must succeed if the following would succeed (ignoring 073 * encoding issues): 074 * <blockquote> 075 * <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> 076 * </blockquote> 077 * </li> 078 * <li> 079 * and the methods 080 * <code>{@linkplain FileObject#openOutputStream()}</code>, and 081 * <code>{@linkplain FileObject#openWriter()}</code> must 082 * succeed if the following would succeed (ignoring encoding 083 * issues): 084 * <blockquote> 085 * <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> 086 * </blockquote> 087 * </li> 088 * </ul> 089 * </li> 090 * <li> 091 * The {@linkplain java.net.URI URI} returned from 092 * <code>{@linkplain FileObject#toUri()}</code> 093 * <ul> 094 * <li> 095 * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and 096 * </li> 097 * <li> 098 * must have a {@linkplain java.net.URI#normalize() normalized} 099 * {@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 }