View Javadoc
1   /*
2    * Copyright (c) 2006, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * 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&eacute;
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 }