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(
213: String... names);
214:
215: /**
216: * Associates the given path with the given location. Any
217: * previous value will be discarded.
218: *
219: * @param location a location
220: * @param path a list of files, if {@code null} use the default
221: * path for this location
222: * @see #getLocation
223: * @throws IllegalArgumentException if location is an output
224: * location and path does not contain exactly one element
225: * @throws IOException if location is an output location and path
226: * does not represent an existing directory
227: */
228: void setLocation(Location location, Iterable<? extends File> path)
229: throws IOException;
230:
231: /**
232: * Gets the path associated with the given location.
233: *
234: * @param location a location
235: * @return a list of files or {@code null} if this location has no
236: * associated path
237: * @see #setLocation
238: */
239: Iterable<? extends File> getLocation(Location location);
240:
241: }
|