Mercurial > jdk8-mips64-public > langtools / file comparison
comparison: src/share/classes/javax/tools/StandardJavaFileManager.java
src/share/classes/javax/tools/StandardJavaFileManager.java
- changeset 1
- 9a66ca7c79fa
- child 450
- 4011f49b4af8
equal
deleted
inserted
replaced
| -1:000000000000 | 1:9a66ca7c79fa |
|---|---|
| 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 } |
