JavaFileManagerpublic interface JavaFileManager implements Closeable, Flushable, OptionChecker| File manager for tools operating on Java™ programming language
source and class files. In this context, file means an
abstraction of regular files and other sources of data.
When constructing new JavaFileObjects, the file manager must
determine where to create them. For example, if a file manager
manages regular files on a file system, it would most likely have a
current/working directory to use as default location when creating
or finding files. A number of hints can be provided to a file
manager as to where to create files. Any file manager might choose
to ignore these hints.
Some methods in this interface use class names. Such class
names must be given in the Java Virtual Machine internal form of
fully qualified class and interface names. For convenience '.'
and '/' are interchangeable. The internal form is defined in
chapter four of the
Java
Virtual Machine Specification.
Discussion: this means that the names
"java/lang.package-info", "java/lang/package-info",
"java.lang.package-info", are valid and equivalent. Compare to
binary name as defined in the
Java Language
Specification (JLS) section 13.1 "The Form of a Binary".
The case of names is significant. All names should be treated
as case-sensitive. For example, some file systems have
case-insensitive, case-aware file names. File objects representing
such files should take care to preserve case by using {@link
java.io.File#getCanonicalFile} or similar means. If the system is
not case-aware, file objects must use other means to preserve case.
Relative names: some
methods in this interface use relative names. A relative name is a
non-null, non-empty sequence of path segments separated by '/'.
'.' or '..' are invalid path segments. A valid relative name must
match the "path-rootless" rule of RFC 3986,
section 3.3. Informally, this should be true:
URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)
All methods in this interface might throw a SecurityException.
An object of this interface is not required to support
multi-threaded access, that is, be synchronized. However, it must
support concurrent access to different file objects created by this
object.
Implementation note: a consequence of this requirement
is that a trivial implementation of output to a {@linkplain
java.util.jar.JarOutputStream} is not a sufficient implementation.
That is, rather than creating a JavaFileObject that returns the
JarOutputStream directly, the contents must be cached until closed
and then written to the JarOutputStream.
Unless explicitly allowed, all methods in this interface might
throw a NullPointerException if given a {@code null} argument. |
| Methods Summary |
|---|
| public void | close()Releases any resources opened by this file manager directly or
indirectly. This might render this file manager useless and
the effect of subsequent calls to methods on this object or any
objects obtained through this object is undefined unless
explicitly allowed. However, closing a file manager which has
already been closed has no effect.
| | public void | flush()Flushes any resources opened for output by this file manager
directly or indirectly. Flushing a closed file manager has no
effect.
| | public java.lang.ClassLoader | getClassLoader(javax.tools.JavaFileManager$Location location)Gets a class loader for loading plug-ins from the given
location. For example, to load annotation processors, a
compiler will request a class loader for the {@link
StandardLocation#ANNOTATION_PROCESSOR_PATH
ANNOTATION_PROCESSOR_PATH} location.
| | public javax.tools.FileObject | getFileForInput(javax.tools.JavaFileManager$Location location, java.lang.String packageName, java.lang.String relativeName)Gets a {@linkplain FileObject file object} for input
representing the specified relative
name in the specified package in the given location.
If the returned object represents a {@linkplain
JavaFileObject.Kind#SOURCE source} or {@linkplain
JavaFileObject.Kind#CLASS class} file, it must be an instance
of {@link JavaFileObject}.
Informally, the file object returned by this method is
located in the concatenation of the location, package name, and
relative name. For example, to locate the properties file
"resources/compiler.properties" in the package
"com.sun.tools.javac" in the {@linkplain
StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
might be called like so:
getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");
If the call was executed on Windows, with SOURCE_PATH set to
"C:\Documents and Settings\UncleBob\src\share\classes",
a valid result would be a file object representing the file
"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties".
| | public javax.tools.FileObject | getFileForOutput(javax.tools.JavaFileManager$Location location, java.lang.String packageName, java.lang.String relativeName, javax.tools.FileObject sibling)Gets a {@linkplain FileObject file object} for output
representing the specified relative
name in the specified package in the given location.
Optionally, this file manager might consider the sibling as
a hint for where to place the output. The exact semantics of
this hint is unspecified. Sun's compiler, javac, for
example, will place class files in the same directories as
originating source files unless a class file output directory
is provided. To facilitate this behavior, javac might provide
the originating source file as sibling when calling this
method.
If the returned object represents a {@linkplain
JavaFileObject.Kind#SOURCE source} or {@linkplain
JavaFileObject.Kind#CLASS class} file, it must be an instance
of {@link JavaFileObject}.
Informally, the file object returned by this method is
located in the concatenation of the location, package name, and
relative name or next to the sibling argument. See {@link
#getFileForInput getFileForInput} for an example.
| | public javax.tools.JavaFileObject | getJavaFileForInput(javax.tools.JavaFileManager$Location location, java.lang.String className, javax.tools.JavaFileObject.Kind kind)Gets a {@linkplain JavaFileObject file object} for input
representing the specified class of the specified kind in the
given location.
| | public javax.tools.JavaFileObject | getJavaFileForOutput(javax.tools.JavaFileManager$Location location, java.lang.String className, javax.tools.JavaFileObject.Kind kind, javax.tools.FileObject sibling)Gets a {@linkplain JavaFileObject file object} for output
representing the specified class of the specified kind in the
given location.
Optionally, this file manager might consider the sibling as
a hint for where to place the output. The exact semantics of
this hint is unspecified. Sun's compiler, javac, for
example, will place class files in the same directories as
originating source files unless a class file output directory
is provided. To facilitate this behavior, javac might provide
the originating source file as sibling when calling this
method.
| | public boolean | handleOption(java.lang.String current, java.util.Iterator remaining)Handles one option. If {@code current} is an option to this
file manager it will consume any arguments to that option from
{@code remaining} and return true, otherwise return false.
| | public boolean | hasLocation(javax.tools.JavaFileManager$Location location)Determines if a location is known to this file manager.
| | public java.lang.String | inferBinaryName(javax.tools.JavaFileManager$Location location, javax.tools.JavaFileObject file)Infers a binary name of a file object based on a location. The
binary name returned might not be a valid JLS binary name.
| | public boolean | isSameFile(javax.tools.FileObject a, javax.tools.FileObject b)Compares two file objects and return true if they represent the
same underlying object.
| | public java.lang.Iterable | list(javax.tools.JavaFileManager$Location location, java.lang.String packageName, java.util.Set kinds, boolean recurse)Lists all file objects matching the given criteria in the given
location. List file objects in "subpackages" if recurse is
true.
Note: even if the given location is unknown to this file
manager, it may not return {@code null}. Also, an unknown
location may not cause an exception.
|
|
