javax.tools

Interface JavaFileManager

All Superinterfaces:
AutoCloseable, Closeable, Flushable, OptionChecker
Known Subinterfaces:
StandardJavaFileManager

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

File manager for tools which operate on source and class files. In this context, the term file is used to refer to the abstract concept of a data source, rather than specifically a regular file on a filesystem.

The file manager determines where to create new FileObjects. It may have a default directory where files are created. The user may provide hints as to how to perform file creation, but the file manager may choose to ignore these.

For methods in this interface which use class names, these must be given in the internal virtual machine form of fully qualified class and interface names. The use of '/' and '.' are interchangeable, making java.lang.Object, java/lang.Object and java/lang/Object all equivalent.

All names should be treated as being case-sensitive. If the underlying system is not case-aware, steps should be taken to handle this in the implementation, such as the use of File.getCanonicalFile() to preserve case.

For methods in this interface which use relative names, these are path separated by '/' and do not include the segments '.' and '..', so that they may only refer to subdirectories. A valid relative name must match the "path-rootless" rule of RFC 3986, section 3.3. The construction URI.create(name).normalize().getPath().equals(name) should hold.

All methods may throw a SecurityException. All methods may throw a NullPointerException if an argument is null, unless otherwise specified. It is not required that the implementation support concurrent access to the file manager, but the file objects created by it should be thread-safe.

Since:
1.6

Nested Class Summary

static interface
JavaFileManager.Location
Interface for obtaining the location of FileObjects.

Method Summary

void
close()
Closes the file manager and releases any resources in use.
void
flush()
Flushes data to any resources controlled by this file manager.
ClassLoader
getClassLoader(JavaFileManager.Location location)
Returns the class loader that is responsible for loading class files from the specified location.
FileObject
getFileForInput(JavaFileManager.Location location, String pkg, String relName)
Returns a file object for reading a file.
FileObject
getFileForOutput(JavaFileManager.Location location, String pkg, String relName, FileObject sibling)
Returns a file object for writing a file.
JavaFileObject
getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)
Returns a JavaFileObject for reading a source file or class file.
JavaFileObject
getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)
Returns a JavaFileObject for writing a source or class file.
boolean
handleOption(String option, Iterator remaining)
Processes one option.
boolean
hasLocation(JavaFileManager.Location location)
Returns true if the specified location is known to this file manager.
String
inferBinaryName(JavaFileManager.Location location, JavaFileObject file)
Infers a binary name for the given file object, based on its location.
boolean
isSameFile(FileObject x, FileObject y)
Returns true if the two given file objects represent the same file.
Iterable
list(JavaFileManager.Location location, String pkg, Set kinds, boolean recurse)
Lists all file objects matching the given criteria in the specified location.

Methods inherited from interface java.lang.AutoCloseable

close

Methods inherited from interface java.io.Closeable

close

Methods inherited from interface java.io.Flushable

flush

Methods inherited from interface javax.tools.OptionChecker

isSupportedOption

Method Details

close

public void close()
            throws IOException
Closes the file manager and releases any resources in use. Calling close() on an already closed file manager has no effect. The effect of calling other methods on a closed file manager is undefined, unless specified in the documentation of that method.
Specified by:
close in interface Closeable
close in interface AutoCloseable
Throws:
IOException - if an I/O error occurs.
See Also:
flush()

flush

public void flush()
            throws IOException
Flushes data to any resources controlled by this file manager. Flushing a closed file manager has no effect.
Specified by:
flush in interface Flushable
Throws:
IOException - if an I/O error occurs.
See Also:
close()

getClassLoader

public ClassLoader getClassLoader(JavaFileManager.Location location)
Returns the class loader that is responsible for loading class files from the specified location. For example, getClassLoader(StandardLocation.ANNOTATION_PROCESSOR_PATH) will return the class loader which is used to load annotation processors.
Parameters:
location - the location to retrieve the class loader for.
Returns:
the class loader for class files in that location, or null if the location is unknown or class loading from that location is disabled.
Throws:
SecurityException - if the class loader is not retrievable under the current security manager.
IllegalStateException - if close() has been called and the file manager can't be reopened.

getFileForInput

public FileObject getFileForInput(JavaFileManager.Location location,
                                  String pkg,
                                  String relName)
            throws IOException
Returns a file object for reading a file. If this is a source or class file, the returned instance must be a JavaFileObject. The file name is constructed as a concatenation of the location, the package name and the relative file name.

For example, for the call , assuming that the source path is set to "/home/bob/sources", the returned file object would represent the file "/home/bob/sources/gnu/classpath/util/CoolCode.java".

Parameters:
location - the base location for the file.
pkg - the package the file will be read from.
relName - the path to the file, relative to location+pkg.
Returns:
a file object or may return null if the file does not exist.
Throws:
IllegalArgumentException - if the location is unknown and unknown locations are not supported, or if the relative name is invalid.
IOException - if an I/O error occurs, or the file manager has been closed and can't be reopened.
IllegalStateException - if the file manager has been closed and can't be reopened.

getFileForOutput

public FileObject getFileForOutput(JavaFileManager.Location location,
                                   String pkg,
                                   String relName,
                                   FileObject sibling)
            throws IOException
Returns a file object for writing a file. If this is a source or class file, the returned instance must be a JavaFileObject. The file name is constructed as a concatenation of the location, the package name and the relative file name.

For example, for the call , assuming that the source output is set to "/home/bob/generated", the returned file object would represent the file "/home/bob/generated/gnu/classpath/util/GenSyms.java".

The file manager may optionally use the supplied sibling as a hint as to where to place the output file. The exact semantics of this hint are left to the implementation. As an example, the compiler places class files in the same location as the corresponding source file, if no destination is specified. To facilitate this, the source file location may be passed as a hint to the file manager.

Parameters:
location - the base location for the file.
pkg - the package in which the file will be stored.
relName - the path to the file, relative to location+pkg.
sibling - an optional hint as to where to place the output file. May be null.
Returns:
a file object.
Throws:
IllegalArgumentException - if the location is unknown and unknown locations are not supported, if the relative name is invalid or if the sibling is not known to this file manager.
IOException - if an I/O error occurs, or the file manager has been closed and can't be reopened.
IllegalStateException - if the file manager has been closed and can't be reopened.

getJavaFileForInput

public JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                          String className,
                                          JavaFileObject.Kind kind)
            throws IOException
Returns a JavaFileObject for reading a source file or class file. The file name is constructed as a concatenation of the location and the information provided by the type name and the kind of the file.

For example, for the call , assuming that the source path is set to "/home/bob/sources", the returned file object would represent the file "/home/bob/sources/gnu/classpath/util/CoolCode.java".

Parameters:
location - the base location for the file.
className - the name of the class.
kind - the kind of file, either JavaFileObject.Kind.SOURCE or JavaFileObject.Kind.CLASS.
Returns:
a file object or may return null if the file does not exist.
Throws:
IllegalArgumentException - if the location is unknown and unknown locations are not supported, or if the kind is invalid.
IOException - if an I/O error occurs, or the file manager has been closed and can't be reopened.
IllegalStateException - if the file manager has been closed and can't be reopened.

getJavaFileForOutput

public JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                           String className,
                                           JavaFileObject.Kind kind,
                                           FileObject sibling)
            throws IOException
Returns a JavaFileObject for writing a source or class file. The file name is constructed as a concatenation of the location and the information provided by the type name and the kind of the file.

For example, for the call , assuming that the class output is set to "/home/bob/build", the returned file object would represent the file "/home/bob/build/gnu/classpath/util/GenSyms.class".

The file manager may optionally use the supplied sibling as a hint as to where to place the output file. The exact semantics of this hint are left to the implementation. As an example, the compiler places class files in the same location as the corresponding source file, if no destination is specified. To facilitate this, the source file location may be passed as a hint to the file manager.

Parameters:
location - the base location for the file.
className - the name of the class.
kind - the kind of file, either JavaFileObject.Kind.SOURCE or JavaFileObject.Kind.CLASS.
sibling - an optional hint as to where to place the output file. May be null.
Returns:
a file object.
Throws:
IllegalArgumentException - if the location is unknown and unknown locations are not supported, if the kind is invalid or if the sibling is not known to this file manager.
IOException - if an I/O error occurs, or the file manager has been closed and can't be reopened.
IllegalStateException - if the file manager has been closed and can't be reopened.

handleOption

public boolean handleOption(String option,
                            Iterator remaining)
Processes one option. If the specified option is supported by this file manager, it will read any necessary arguments to the option from the iterator and then return true. Otherwise, it will return false.
Parameters:
option - the option to process.
remaining - the remaining arguments/options.
Returns:
true if the option was handled.
Throws:
IllegalArgumentException - if the option is used incorrectly.
IllegalStateException - if the file manager has been closed and can't be reopened.

hasLocation

public boolean hasLocation(JavaFileManager.Location location)
Returns true if the specified location is known to this file manager.
Parameters:
location - the location to check.
Returns:
true if the location is known.

inferBinaryName

public String inferBinaryName(JavaFileManager.Location location,
                              JavaFileObject file)
Infers a binary name for the given file object, based on its location. The returned name may not be a valid binary name, according to the Java language specification.
Parameters:
location - the location to use as a basis.
file - the file object.
Returns:
a binary name or null if the file object is not found in the given location.
Throws:
IllegalStateException - if the file manager has been closed and can't be reopened.

isSameFile

public boolean isSameFile(FileObject x,
                          FileObject y)
Returns true if the two given file objects represent the same file.
Parameters:
x - the first object.
y - the second object.
Returns:
true if x and y represent the same file.
Throws:
IllegalArgumentException - if either x or y were created by a foreign file manager and this file manager does not support such comparisons.

list

public Iterable list(JavaFileManager.Location location,
                                     String pkg,
                                     Set kinds,
                                     boolean recurse)
            throws IOException
Lists all file objects matching the given criteria in the specified location. If recurse is true, the list will include those found in subpackages. Note that a file manager may not return a null list or throw an exception if the location is unknown.
Parameters:
location - the location to search.
pkg - the name of the package to search.
kinds - the kinds of object to return.
recurse - true if subpackages should be searched.
Returns:
an Iterable over the matching file object.
Throws:
IOException - if an I/O error occurs, or the file manager has been closed and can't be reopened.
IllegalStateException - if the file manager has been closed and can't be reopened.

JavaFileManager.java -- File manager for source & class file tools. Copyright (C) 2012 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.