JavaFileManager


1   /*
2    * @(#)JavaFileManager.java 1.17 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.Closeable  ;
11  import java.io.Flushable  ;
12  import java.io.IOException  ;
13  import java.util.Iterator  ;
14  import java.util.Set  ;
15  import static javax.tools.JavaFileObject.Kind;
16  
17  /**
18   * File manager for tools operating on Java&trade; programming language
19   * source and class files.  In this context, <em>file</em> means an
20   * abstraction of regular files and other sources of data.
21   *
22   * <p>When constructing new JavaFileObjects, the file manager must
23   * determine where to create them.  For example, if a file manager
24   * manages regular files on a file system, it would most likely have a
25   * current/working directory to use as default location when creating
26   * or finding files.  A number of hints can be provided to a file
27   * manager as to where to create files.  Any file manager might choose
28   * to ignore these hints.
29   *
30   * <p>Some methods in this interface use class names.  Such class
31   * names must be given in the Java Virtual Machine internal form of
32   * fully qualified class and interface names.  For convenience '.'
33   * and '/' are interchangeable.  The internal form is defined in
34   * chapter four of the
35   * <a HREF="http://java.sun.com/docs/books/vmspec/2nd-edition/jvms-maintenance.html">Java
36   * Virtual Machine Specification</a>.
37  
38   * <blockquote><p>
39   *   <i>Discussion:</i> this means that the names
40   *   "java/lang.package-info", "java/lang/package-info",
41   *   "java.lang.package-info", are valid and equivalent.  Compare to
42   *   binary name as defined in the
43   *   <a HREF="http://java.sun.com/docs/books/jls/">Java Language
44   *   Specification (JLS)</a> section 13.1 "The Form of a Binary".
45   * </p></blockquote>
46   *
47   * <p>The case of names is significant.  All names should be treated
48   * as case-sensitive.  For example, some file systems have
49   * case-insensitive, case-aware file names.  File objects representing
50   * such files should take care to preserve case by using {@link
51   * java.io.File#getCanonicalFile} or similar means.  If the system is
52   * not case-aware, file objects must use other means to preserve case.
53   *
54   * <p><em><a name="relative_name">Relative names</a>:</em> some
55   * methods in this interface use relative names.  A relative name is a
56   * non-null, non-empty sequence of path segments separated by '/'.
57   * '.' or '..'  are invalid path segments.  A valid relative name must
58   * match the "path-rootless" rule of <a
59   * HREF="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>,
60   * section&nbsp;3.3.  Informally, this should be true:
61   *
62   * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
63   * <pre>  URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
64   *
65   * <p>All methods in this interface might throw a SecurityException.
66   *
67   * <p>An object of this interface is not required to support
68   * multi-threaded access, that is, be synchronized.  However, it must
69   * support concurrent access to different file objects created by this
70   * object.
71   *
72   * <p><em>Implementation note:</em> a consequence of this requirement
73   * is that a trivial implementation of output to a {@linkplain
74   * java.util.jar.JarOutputStream} is not a sufficient implementation.
75   * That is, rather than creating a JavaFileObject that returns the
76   * JarOutputStream directly, the contents must be cached until closed
77   * and then written to the JarOutputStream.
78   *
79   * <p>Unless explicitly allowed, all methods in this interface might
80   * throw a NullPointerException if given a {@code null} argument.
81   *
82   * @author Peter von der Ah&eacute;
83   * @author Jonathan Gibbons
84   * @see JavaFileObject
85   * @see FileObject
86   * @since 1.6
87   */
88  public interface JavaFileManager extends Closeable  , Flushable  , OptionChecker {
89  
90      /**
91       * Interface for locations of file objects.  Used by file managers
92       * to determine where to place or search for file objects.
93       */
94      interface Location {
95          /**
96           * Gets the name of this location.
97           *
98           * @return a name
99           */
100         String   getName();
101 
102         /**
103          * Determines if this is an output location.  An output
104          * location is a location that is conventionally used for
105          * output.
106          *
107          * @return true if this is an output location, false otherwise
108          */
109         boolean isOutputLocation();
110     }
111 
112     /**
113      * Gets a class loader for loading plug-ins from the given
114      * location.  For example, to load annotation processors, a
115      * compiler will request a class loader for the {@link
116      * StandardLocation#ANNOTATION_PROCESSOR_PATH
117      * ANNOTATION_PROCESSOR_PATH} location.
118      *
119      * @param location a location
120      * @return a class loader for the given location; or {@code null}
121      * if loading plug-ins from the given location is disabled or if
122      * the location is not known
123      * @throws SecurityException if a class loader can not be created
124      * in the current security context
125      * @throws IllegalStateException if {@link #close} has been called
126      * and this file manager cannot be reopened
127      */
128     ClassLoader   getClassLoader(Location location);
129 
130     /**
131      * Lists all file objects matching the given criteria in the given
132      * location.  List file objects in "subpackages" if recurse is
133      * true.
134      *
135      * <p>Note: even if the given location is unknown to this file
136      * manager, it may not return {@code null}.  Also, an unknown
137      * location may not cause an exception.
138      *
139      * @param location     a location
140      * @param packageName  a package name
141      * @param kinds        return objects only of these kinds
142      * @param recurse      if true include "subpackages"
143      * @return an Iterable of file objects matching the given criteria
144      * @throws IOException if an I/O error occurred, or if {@link
145      * #close} has been called and this file manager cannot be
146      * reopened
147      * @throws IllegalStateException if {@link #close} has been called
148      * and this file manager cannot be reopened
149      */
150     Iterable  <JavaFileObject> list(Location location,
151                                   String   packageName,
152                                   Set  <Kind> kinds,
153                                   boolean recurse)
154         throws IOException  ;
155 
156     /**
157      * Infers a binary name of a file object based on a location.  The
158      * binary name returned might not be a valid JLS binary name.
159      *
160      * @param location a location
161      * @param file a file object
162      * @return a binary name or {@code null} the file object is not
163      * found in the given location
164      * @throws IllegalStateException if {@link #close} has been called
165      * and this file manager cannot be reopened
166      */
167     String   inferBinaryName(Location location, JavaFileObject file);
168 
169     /**
170      * Compares two file objects and return true if they represent the
171      * same underlying object.
172      *
173      * @param a a file object
174      * @param b a file object
175      * @return true if the given file objects represent the same
176      * underlying object
177      *
178      * @throws IllegalArgumentException if either of the arguments
179      * were created with another file manager and this file manager
180      * does not support foreign file objects
181      */
182     boolean isSameFile(FileObject a, FileObject b);
183 
184     /**
185      * Handles one option.  If {@code current} is an option to this
186      * file manager it will consume any arguments to that option from
187      * {@code remaining} and return true, otherwise return false.
188      *
189      * @param current current option
190      * @param remaining remaining options
191      * @return true if this option was handled by this file manager,
192      * false otherwise
193      * @throws IllegalArgumentException if this option to this file
194      * manager is used incorrectly
195      * @throws IllegalStateException if {@link #close} has been called
196      * and this file manager cannot be reopened
197      */
198     boolean handleOption(String   current, Iterator  <String  > remaining);
199 
200     /**
201      * Determines if a location is known to this file manager.
202      *
203      * @param location a location
204      * @return true if the location is known
205      */
206     boolean hasLocation(Location location);
207 
208     /**
209      * Gets a {@linkplain JavaFileObject file object} for input
210      * representing the specified class of the specified kind in the
211      * given location.
212      *
213      * @param location a location
214      * @param className the name of a class
215      * @param kind the kind of file, must be one of {@link
216      * JavaFileObject.Kind#SOURCE SOURCE} or {@link
217      * JavaFileObject.Kind#CLASS CLASS}
218      * @return a file object, might return {@code null} if the
219      * file does not exist
220      * @throws IllegalArgumentException if the location is not known
221      * to this file manager and the file manager does not support
222      * unknown locations, or if the kind is not valid
223      * @throws IOException if an I/O error occurred, or if {@link
224      * #close} has been called and this file manager cannot be
225      * reopened
226      * @throws IllegalStateException if {@link #close} has been called
227      * and this file manager cannot be reopened
228      */
229     JavaFileObject getJavaFileForInput(Location location,
230                                        String   className,
231                                        Kind kind)
232         throws IOException  ;
233 
234     /**
235      * Gets a {@linkplain JavaFileObject file object} for output
236      * representing the specified class of the specified kind in the
237      * given location.
238      *
239      * <p>Optionally, this file manager might consider the sibling as
240      * a hint for where to place the output.  The exact semantics of
241      * this hint is unspecified.  Sun's compiler, javac, for
242      * example, will place class files in the same directories as
243      * originating source files unless a class file output directory
244      * is provided.  To facilitate this behavior, javac might provide
245      * the originating source file as sibling when calling this
246      * method.
247      *
248      * @param location a location
249      * @param className the name of a class
250      * @param kind the kind of file, must be one of {@link
251      * JavaFileObject.Kind#SOURCE SOURCE} or {@link
252      * JavaFileObject.Kind#CLASS CLASS}
253      * @param sibling a file object to be used as hint for placement;
254      * might be {@code null}
255      * @return a file object for output
256      * @throws IllegalArgumentException if sibling is not known to
257      * this file manager, or if the location is not known to this file
258      * manager and the file manager does not support unknown
259      * locations, or if the kind is not valid
260      * @throws IOException if an I/O error occurred, or if {@link
261      * #close} has been called and this file manager cannot be
262      * reopened
263      * @throws IllegalStateException {@link #close} has been called
264      * and this file manager cannot be reopened
265      */
266     JavaFileObject getJavaFileForOutput(Location location,
267                                         String   className,
268                                         Kind kind,
269                                         FileObject sibling)
270         throws IOException  ;
271 
272     /**
273      * Gets a {@linkplain FileObject file object} for input
274      * representing the specified <a HREF="JavaFileManager.html#relative_name">relative
275      * name</a> in the specified package in the given location.
276      *
277      * <p>If the returned object represents a {@linkplain
278      * JavaFileObject.Kind#SOURCE source} or {@linkplain
279      * JavaFileObject.Kind#CLASS class} file, it must be an instance
280      * of {@link JavaFileObject}.
281      *
282      * <p>Informally, the file object returned by this method is
283      * located in the concatenation of the location, package name, and
284      * relative name.  For example, to locate the properties file
285      * "resources/compiler.properties" in the package
286      * "com.sun.tools.javac" in the {@linkplain
287      * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
288      * might be called like so:
289      *
290      * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>
291      *
292      * <p>If the call was executed on Windows, with SOURCE_PATH set to
293      * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes"</code>,
294      * a valid result would be a file object representing the file
295      * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.
296      *
297      * @param location a location
298      * @param packageName a package name
299      * @param relativeName a relative name
300      * @return a file object, might return {@code null} if the file
301      * does not exist
302      * @throws IllegalArgumentException if the location is not known
303      * to this file manager and the file manager does not support
304      * unknown locations, or if {@code relativeName} is not valid
305      * @throws IOException if an I/O error occurred, or if {@link
306      * #close} has been called and this file manager cannot be
307      * reopened
308      * @throws IllegalStateException if {@link #close} has been called
309      * and this file manager cannot be reopened
310      */
311     FileObject getFileForInput(Location location,
312                                String   packageName,
313                                String   relativeName)
314         throws IOException  ;
315 
316     /**
317      * Gets a {@linkplain FileObject file object} for output
318      * representing the specified <a HREF="JavaFileManager.html#relative_name">relative
319      * name</a> in the specified package in the given location.
320      *
321      * <p>Optionally, this file manager might consider the sibling as
322      * a hint for where to place the output.  The exact semantics of
323      * this hint is unspecified.  Sun's compiler, javac, for
324      * example, will place class files in the same directories as
325      * originating source files unless a class file output directory
326      * is provided.  To facilitate this behavior, javac might provide
327      * the originating source file as sibling when calling this
328      * method.
329      *
330      * <p>If the returned object represents a {@linkplain
331      * JavaFileObject.Kind#SOURCE source} or {@linkplain
332      * JavaFileObject.Kind#CLASS class} file, it must be an instance
333      * of {@link JavaFileObject}.
334      *
335      * <p>Informally, the file object returned by this method is
336      * located in the concatenation of the location, package name, and
337      * relative name or next to the sibling argument.  See {@link
338      * #getFileForInput getFileForInput} for an example.
339      *
340      * @param location a location
341      * @param packageName a package name
342      * @param relativeName a relative name
343      * @param sibling a file object to be used as hint for placement;
344      * might be {@code null}
345      * @return a file object
346      * @throws IllegalArgumentException if sibling is not known to
347      * this file manager, or if the location is not known to this file
348      * manager and the file manager does not support unknown
349      * locations, or if {@code relativeName} is not valid
350      * @throws IOException if an I/O error occurred, or if {@link
351      * #close} has been called and this file manager cannot be
352      * reopened
353      * @throws IllegalStateException if {@link #close} has been called
354      * and this file manager cannot be reopened
355      */
356     FileObject getFileForOutput(Location location,
357                                 String   packageName,
358                                 String   relativeName,
359                                 FileObject sibling)
360         throws IOException  ;
361 
362     /**
363      * Flushes any resources opened for output by this file manager
364      * directly or indirectly.  Flushing a closed file manager has no
365      * effect.
366      *
367      * @throws IOException if an I/O error occurred
368      * @see #close
369      */
370     void flush() throws IOException  ;
371 
372     /**
373      * Releases any resources opened by this file manager directly or
374      * indirectly.  This might render this file manager useless and
375      * the effect of subsequent calls to methods on this object or any
376      * objects obtained through this object is undefined unless
377      * explicitly allowed.  However, closing a file manager which has
378      * already been closed has no effect.
379      *
380      * @throws IOException if an I/O error occurred
381      * @see #flush
382      */
383     void close() throws IOException  ;
384 }
385
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags