1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/classes/javax/tools/StandardJavaFileManager.java Sat Dec 01 00:00:00 2007 +0000 1.3 @@ -0,0 +1,240 @@ 1.4 +/* 1.5 + * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Sun designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Sun in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or 1.26 + * have any questions. 1.27 + */ 1.28 + 1.29 +package javax.tools; 1.30 + 1.31 +import java.io.File; 1.32 +import java.io.IOException; 1.33 +import java.util.*; 1.34 +import java.util.concurrent.*; 1.35 + 1.36 +/** 1.37 + * File manager based on {@linkplain File java.io.File}. A common way 1.38 + * to obtain an instance of this class is using {@linkplain 1.39 + * JavaCompiler#getStandardFileManager 1.40 + * getStandardFileManager}, for example: 1.41 + * 1.42 + * <pre> 1.43 + * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); 1.44 + * {@code DiagnosticCollector<JavaFileObject>} diagnostics = 1.45 + * new {@code DiagnosticCollector<JavaFileObject>()}; 1.46 + * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null); 1.47 + * </pre> 1.48 + * 1.49 + * This file manager creates file objects representing regular 1.50 + * {@linkplain File files}, 1.51 + * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in 1.52 + * similar file system based containers. Any file object returned 1.53 + * from a file manager implementing this interface must observe the 1.54 + * following behavior: 1.55 + * 1.56 + * <ul> 1.57 + * <li> 1.58 + * File names need not be canonical. 1.59 + * </li> 1.60 + * <li> 1.61 + * For file objects representing regular files 1.62 + * <ul> 1.63 + * <li> 1.64 + * the method <code>{@linkplain FileObject#delete()}</code> 1.65 + * is equivalent to <code>{@linkplain File#delete()}</code>, 1.66 + * </li> 1.67 + * <li> 1.68 + * the method <code>{@linkplain FileObject#getLastModified()}</code> 1.69 + * is equivalent to <code>{@linkplain File#lastModified()}</code>, 1.70 + * </li> 1.71 + * <li> 1.72 + * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>, 1.73 + * <code>{@linkplain FileObject#openInputStream()}</code>, and 1.74 + * <code>{@linkplain FileObject#openReader(boolean)}</code> 1.75 + * must succeed if the following would succeed (ignoring 1.76 + * encoding issues): 1.77 + * <blockquote> 1.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> 1.79 + * </blockquote> 1.80 + * </li> 1.81 + * <li> 1.82 + * and the methods 1.83 + * <code>{@linkplain FileObject#openOutputStream()}</code>, and 1.84 + * <code>{@linkplain FileObject#openWriter()}</code> must 1.85 + * succeed if the following would succeed (ignoring encoding 1.86 + * issues): 1.87 + * <blockquote> 1.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> 1.89 + * </blockquote> 1.90 + * </li> 1.91 + * </ul> 1.92 + * </li> 1.93 + * <li> 1.94 + * The {@linkplain java.net.URI URI} returned from 1.95 + * <code>{@linkplain FileObject#toUri()}</code> 1.96 + * <ul> 1.97 + * <li> 1.98 + * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and 1.99 + * </li> 1.100 + * <li> 1.101 + * must have a {@linkplain java.net.URI#normalize() normalized} 1.102 + * {@linkplain java.net.URI#getPath() path component} which 1.103 + * can be resolved without any process-specific context such 1.104 + * as the current directory (file names must be absolute). 1.105 + * </li> 1.106 + * </ul> 1.107 + * </li> 1.108 + * </ul> 1.109 + * 1.110 + * According to these rules, the following URIs, for example, are 1.111 + * allowed: 1.112 + * <ul> 1.113 + * <li> 1.114 + * <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code> 1.115 + * </li> 1.116 + * <li> 1.117 + * <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class</code> 1.118 + * </li> 1.119 + * </ul> 1.120 + * Whereas these are not (reason in parentheses): 1.121 + * <ul> 1.122 + * <li> 1.123 + * <code>file:BobsApp/Test.java</code> (the file name is relative 1.124 + * and depend on the current directory) 1.125 + * </li> 1.126 + * <li> 1.127 + * <code>jar:lib/vendorA.jar!com/vendora/LibraryClass.class</code> 1.128 + * (the first half of the path depends on the current directory, 1.129 + * whereas the component after ! is legal) 1.130 + * </li> 1.131 + * <li> 1.132 + * <code>Test.java</code> (this URI depends on the current 1.133 + * directory and does not have a schema) 1.134 + * </li> 1.135 + * <li> 1.136 + * <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code> 1.137 + * (the path is not normalized) 1.138 + * </li> 1.139 + * </ul> 1.140 + * 1.141 + * @author Peter von der Ahé 1.142 + * @since 1.6 1.143 + */ 1.144 +public interface StandardJavaFileManager extends JavaFileManager { 1.145 + 1.146 + /** 1.147 + * Compares two file objects and return true if they represent the 1.148 + * same canonical file, zip file entry, or entry in any file 1.149 + * system based container. 1.150 + * 1.151 + * @param a a file object 1.152 + * @param b a file object 1.153 + * @return true if the given file objects represent the same 1.154 + * canonical file or zip file entry; false otherwise 1.155 + * 1.156 + * @throws IllegalArgumentException if either of the arguments 1.157 + * were created with another file manager implementation 1.158 + */ 1.159 + boolean isSameFile(FileObject a, FileObject b); 1.160 + 1.161 + /** 1.162 + * Gets file objects representing the given files. 1.163 + * 1.164 + * @param files a list of files 1.165 + * @return a list of file objects 1.166 + * @throws IllegalArgumentException if the list of files includes 1.167 + * a directory 1.168 + */ 1.169 + Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles( 1.170 + Iterable<? extends File> files); 1.171 + 1.172 + /** 1.173 + * Gets file objects representing the given files. 1.174 + * Convenience method equivalent to: 1.175 + * 1.176 + * <pre> 1.177 + * getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files)) 1.178 + * </pre> 1.179 + * 1.180 + * @param files an array of files 1.181 + * @return a list of file objects 1.182 + * @throws IllegalArgumentException if the array of files includes 1.183 + * a directory 1.184 + * @throws NullPointerException if the given array contains null 1.185 + * elements 1.186 + */ 1.187 + Iterable<? extends JavaFileObject> getJavaFileObjects(File... files); 1.188 + 1.189 + /** 1.190 + * Gets file objects representing the given file names. 1.191 + * 1.192 + * @param names a list of file names 1.193 + * @return a list of file objects 1.194 + * @throws IllegalArgumentException if the list of file names 1.195 + * includes a directory 1.196 + */ 1.197 + Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings( 1.198 + Iterable<String> names); 1.199 + 1.200 + /** 1.201 + * Gets file objects representing the given file names. 1.202 + * Convenience method equivalent to: 1.203 + * 1.204 + * <pre> 1.205 + * getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names)) 1.206 + * </pre> 1.207 + * 1.208 + * @param names a list of file names 1.209 + * @return a list of file objects 1.210 + * @throws IllegalArgumentException if the array of file names 1.211 + * includes a directory 1.212 + * @throws NullPointerException if the given array contains null 1.213 + * elements 1.214 + */ 1.215 + Iterable<? extends JavaFileObject> getJavaFileObjects(String... names); 1.216 + 1.217 + /** 1.218 + * Associates the given path with the given location. Any 1.219 + * previous value will be discarded. 1.220 + * 1.221 + * @param location a location 1.222 + * @param path a list of files, if {@code null} use the default 1.223 + * path for this location 1.224 + * @see #getLocation 1.225 + * @throws IllegalArgumentException if location is an output 1.226 + * location and path does not contain exactly one element 1.227 + * @throws IOException if location is an output location and path 1.228 + * does not represent an existing directory 1.229 + */ 1.230 + void setLocation(Location location, Iterable<? extends File> path) 1.231 + throws IOException; 1.232 + 1.233 + /** 1.234 + * Gets the path associated with the given location. 1.235 + * 1.236 + * @param location a location 1.237 + * @return a list of files or {@code null} if this location has no 1.238 + * associated path 1.239 + * @see #setLocation 1.240 + */ 1.241 + Iterable<? extends File> getLocation(Location location); 1.242 + 1.243 +}