StandardJavaFileManager


1   /*
2    * @(#)StandardJavaFileManager.java 1.13 06/09/25
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.tools;
9   
10  import java.io.File  ;
11  import java.io.IOException  ;
12  import java.util.*;
13  import java.util.concurrent.*;
14  
15  /**
16   * File manager based on {@linkplain File java.io.File}.  A common way
17   * to obtain an instance of this class is using {@linkplain
18   * JavaCompiler#getStandardFileManager
19   * getStandardFileManager}, for example:
20   *
21   * <pre>
22   *   JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
23   *   {@code DiagnosticCollector<JavaFileObject>} diagnostics =
24   *       new {@code DiagnosticCollector<JavaFileObject>()};
25   *   StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
26   * </pre>
27   *
28   * This file manager creates file objects representing regular
29   * {@linkplain File files},
30   * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in
31   * similar file system based containers.  Any file object returned
32   * from a file manager implementing this interface must observe the
33   * following behavior:
34   *
35   * <ul>
36   *   <li>
37   *     File names need not be canonical.
38   *   </li>
39   *   <li>
40   *     For file objects representing regular files
41   *     <ul>
42   *       <li>
43   *         the method <code>{@linkplain FileObject#delete()}</code>
44   *         is equivalent to <code>{@linkplain File#delete()}</code>,
45   *       </li>
46   *       <li>
47   *         the method <code>{@linkplain FileObject#getLastModified()}</code>
48   *         is equivalent to <code>{@linkplain File#lastModified()}</code>,
49   *       </li>
50   *       <li>
51   *         the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>,
52   *         <code>{@linkplain FileObject#openInputStream()}</code>, and
53   *         <code>{@linkplain FileObject#openReader(boolean)}</code>
54   *         must succeed if the following would succeed (ignoring
55   *         encoding issues):
56   *         <blockquote>
57   *           <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>
58   *         </blockquote>
59   *       </li>
60   *       <li>
61   *         and the methods
62   *         <code>{@linkplain FileObject#openOutputStream()}</code>, and
63   *         <code>{@linkplain FileObject#openWriter()}</code> must
64   *         succeed if the following would succeed (ignoring encoding
65   *         issues):
66   *         <blockquote>
67   *           <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>
68   *         </blockquote>
69   *       </li>
70   *     </ul>
71   *   </li>
72   *   <li>
73   *     The {@linkplain java.net.URI URI} returned from
74   *     <code>{@linkplain FileObject#toUri()}</code>
75   *     <ul>
76   *       <li>
77   *         must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and
78   *       </li>
79   *       <li>
80   *         must have a {@linkplain java.net.URI#normalize() normalized}
81   *         {@linkplain java.net.URI#getPath() path component} which
82   *         can be resolved without any process-specific context such
83   *         as the current directory (file names must be absolute).
84   *       </li>
85   *     </ul>
86   *   </li>
87   * </ul>
88   *
89   * According to these rules, the following URIs, for example, are
90   * allowed:
91   * <ul>
92   *   <li>
93   *     <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code>
94   *   </li>
95   *   <li>
96   *     <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class</code>
97   *   </li>
98   * </ul>
99   * Whereas these are not (reason in parentheses):
100  * <ul>
101  *   <li>
102  *     <code>file:BobsApp/Test.java</code> (the file name is relative
103  *     and depend on the current directory)
104  *   </li>
105  *   <li>
106  *     <code>jar:lib/vendorA.jar!com/vendora/LibraryClass.class</code>
107  *     (the first half of the path depends on the current directory,
108  *     whereas the component after ! is legal)
109  *   </li>
110  *   <li>
111  *     <code>Test.java</code> (this URI depends on the current
112  *     directory and does not have a schema)
113  *   </li>
114  *   <li>
115  *     <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code>
116  *     (the path is not normalized)
117  *   </li>
118  * </ul>
119  *
120  * @author Peter von der Ah&eacute;
121  * @since 1.6
122  */
123 public interface StandardJavaFileManager extends JavaFileManager {
124 
125     /**
126      * Compares two file objects and return true if they represent the
127      * same canonical file, zip file entry, or entry in any file
128      * system based container.
129      *
130      * @param a a file object
131      * @param b a file object
132      * @return true if the given file objects represent the same
133      * canonical file or zip file entry; false otherwise
134      *
135      * @throws IllegalArgumentException if either of the arguments
136      * were created with another file manager implementation
137      */
138     boolean isSameFile(FileObject a, FileObject b);
139 
140     /**
141      * Gets file objects representing the given files.
142      *
143      * @param files a list of files
144      * @return a list of file objects
145      * @throws IllegalArgumentException if the list of files includes
146      * a directory
147      */
148     Iterable  <? extends JavaFileObject> getJavaFileObjectsFromFiles(
149         Iterable  <? extends File  > files);
150 
151     /**
152      * Gets file objects representing the given files.
153      * Convenience method equivalent to:
154      *
155      * <pre>
156      *     getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files))
157      * </pre>
158      *
159      * @param files an array of files
160      * @return a list of file objects
161      * @throws IllegalArgumentException if the array of files includes
162      * a directory
163      * @throws NullPointerException if the given array contains null
164      * elements
165      */
166     Iterable  <? extends JavaFileObject> getJavaFileObjects(File  ... files);
167 
168     /**
169      * Gets file objects representing the given file names.
170      *
171      * @param names a list of file names
172      * @return a list of file objects
173      * @throws IllegalArgumentException if the list of file names
174      * includes a directory
175      */
176     Iterable  <? extends JavaFileObject> getJavaFileObjectsFromStrings(
177         Iterable  <String  > names);
178 
179     /**
180      * Gets file objects representing the given file names.
181      * Convenience method equivalent to:
182      *
183      * <pre>
184      *     getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names))
185      * </pre>
186      *
187      * @param names a list of file names
188      * @return a list of file objects
189      * @throws IllegalArgumentException if the array of file names
190      * includes a directory
191      * @throws NullPointerException if the given array contains null
192      * elements
193      */
194     Iterable  <? extends JavaFileObject> getJavaFileObjects(String  ... names);
195 
196     /**
197      * Associates the given path with the given location.  Any
198      * previous value will be discarded.
199      *
200      * @param location a location
201      * @param path a list of files, if {@code null} use the default
202      * path for this location
203      * @see #getLocation
204      * @throws IllegalArgumentException if location is an output
205      * location and path does not contain exactly one element
206      * @throws IOException if location is an output location and path
207      * does not represent an existing directory
208      */
209     void setLocation(Location location, Iterable  <? extends File  > path)
210         throws IOException  ;
211 
212     /**
213      * Gets the path associated with the given location.
214      *
215      * @param location a location
216      * @return a list of files or {@code null} if this location has no
217      * associated path
218      * @see #setLocation
219      */
220     Iterable  <? extends File  > getLocation(Location location);
221 
222 }
223
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags