- All Superinterfaces:
AutoCloseable,Closeable,Flushable,JavaFileManager,OptionChecker
File manager based on
java.io.File and java.nio.file.Path.
A common way to obtain an instance of this class is using
getStandardFileManager, for example:
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();This file manager creates file objects representing regular files, zip file entries, or entries in similar file system based containers. Any file object returned from a file manager implementing this interface must observe the following behavior:DiagnosticCollector<JavaFileObject>diagnostics = newDiagnosticCollector<JavaFileObject>(); StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
- File names need not be canonical.
-
For file objects representing regular files
-
the method
FileObject.delete()is equivalent toFile.delete(), -
the method
FileObject.getLastModified()is equivalent toFile.lastModified(), -
the methods
FileObject.getCharContent(boolean),FileObject.openInputStream(), andFileObject.openReader(boolean)must succeed if the following would succeed (ignoring encoding issues):newFileInputStream(newFile(fileObject.toUri())) -
and the methods
FileObject.openOutputStream(), andFileObject.openWriter()must succeed if the following would succeed (ignoring encoding issues):newFileOutputStream(newFile(fileObject.toUri()))
-
the method
-
The URI returned from
FileObject.toUri()- must be absolute (have a schema), and
- must have a normalized path component which can be resolved without any process-specific context such as the current directory (file names must be absolute).
-
file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java -
jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!/com/vendora/LibraryClass.class
-
file:BobsApp/Test.java(the file name is relative and depend on the current directory) -
jar:lib/vendorA.jar!/com/vendora/LibraryClass.class(the first half of the path depends on the current directory, whereas the component after ! is legal) -
Test.java(this URI depends on the current directory and does not have a schema) -
jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class(the path is not normalized)
All implementations of this interface must support Path objects representing files in the default file system. It is recommended that implementations should support Path objects from any filesystem.
- API Note:
- Some methods on this interface take a
Collection<? extends Path>instead ofIterable<? extends Path>. This is to prevent the possibility of accidentally calling the method with a singlePathas such an argument, because althoughPathimplementsIterable<Path>, it would almost never be correct to call these methods with a singlePathand have it be treated as anIterableof its components. - Since:
- 1.6
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceFactory to createPathobjects from strings.Nested classes/interfaces declared in interface javax.tools.JavaFileManager
JavaFileManager.Location -
Method Summary
Modifier and TypeMethodDescriptiondefault PathasPath(FileObject file) Returns the path, if any, underlying this file object (optional operation).Iterable<? extends JavaFileObject> getJavaFileObjects(File... files) Returns file objects representing the given files.Iterable<? extends JavaFileObject> getJavaFileObjects(String... names) Returns file objects representing the given file names.default Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths) Returns file objects representing the given paths.Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files) Returns file objects representing the given files.default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> paths) Deprecated.default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Collection<? extends Path> paths) Returns file objects representing the given paths.Iterable<? extends JavaFileObject> Returns file objects representing the given file names.getLocation(JavaFileManager.Location location) Returns the search path associated with the given location.getLocationAsPaths(JavaFileManager.Location location) Returns the search path associated with the given location.booleanisSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.voidsetLocation(JavaFileManager.Location location, Iterable<? extends File> files) Associates the given search path with the given location.default voidsetLocationForModule(JavaFileManager.Location location, String moduleName, Collection<? extends Path> paths) Associates the given search path with the given module and location, which must be a module-oriented or output location.default voidsetLocationFromPaths(JavaFileManager.Location location, Collection<? extends Path> paths) Associates the given search path with the given location.default voidSpecify a factory that can be used to generate a path from a string, or series of strings.Methods declared in interface javax.tools.JavaFileManager
close, contains, flush, getClassLoader, getFileForInput, getFileForOutput, getFileForOutputForOriginatingFiles, getJavaFileForInput, getJavaFileForOutput, getJavaFileForOutputForOriginatingFiles, getLocationForModule, getLocationForModule, getServiceLoader, handleOption, hasLocation, inferBinaryName, inferModuleName, list, listLocationsForModulesMethods declared in interface javax.tools.OptionChecker
isSupportedOption
-
Method Details
-
isSameFile
Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.- Specified by:
isSameFilein interfaceJavaFileManager- Parameters:
a- a file objectb- a file object- Returns:
- true if the given file objects represent the same canonical file, zip file entry or path; false otherwise
- Throws:
IllegalArgumentException- if either of the arguments were created with another file manager implementation
-
getJavaFileObjectsFromFiles
Returns file objects representing the given files.- Parameters:
files- a list of files- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the list of files includes a directory
-
getJavaFileObjectsFromPaths
default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Collection<? extends Path> paths) Returns file objects representing the given paths.- Implementation Requirements:
- The default implementation lazily converts each path to a file and calls
getJavaFileObjectsFromFiles.IllegalArgumentExceptionwill be thrown if any of the paths cannot be converted to a file at the point the conversion happens. - Parameters:
paths- a list of paths- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the list of paths includes a directory or if this file manager does not support any of the given paths- Since:
- 13
-
getJavaFileObjectsFromPaths
@Deprecated(since="13") default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> paths) Deprecated.usegetJavaFileObjectsFromPaths(Collection)instead, to prevent the possibility of accidentally calling the method with a singlePathas such an argument. AlthoughPathimplementsIterable<Path>, it would almost never be correct to pass a singlePathand have it be treated as anIterableof its components.Returns file objects representing the given paths.- Implementation Requirements:
- The default implementation lazily converts each path to a file and calls
getJavaFileObjectsFromPaths.IllegalArgumentExceptionwill be thrown if any of the paths cannot be converted to a file at the point the conversion happens. - Parameters:
paths- a list of paths- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the list of paths includes a directory or if this file manager does not support any of the given paths.- Since:
- 9
-
getJavaFileObjects
Returns file objects representing the given files. Convenience method equivalent to:getJavaFileObjectsFromFiles(Arrays.asList(files))- Parameters:
files- an array of files- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the array of files includes a directory or if this file manager does not support any of the given pathsNullPointerException- if the given array contains null elements
-
getJavaFileObjects
Returns file objects representing the given paths. Convenience method equivalent to:getJavaFileObjectsFromPaths(Arrays.asList(paths))- Implementation Requirements:
- The default implementation will only throw
NullPointerExceptionif getJavaFileObjectsFromPaths(Collection) throws it. - Parameters:
paths- an array of paths- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the array of files includes a directory or if this file manager does not support any of the given pathsNullPointerException- if the given array contains null elements- Since:
- 9
-
getJavaFileObjectsFromStrings
Returns file objects representing the given file names.- Parameters:
names- a list of file names- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the list of file names includes a directory
-
getJavaFileObjects
Returns file objects representing the given file names. Convenience method equivalent to:getJavaFileObjectsFromStrings(Arrays.asList(names))- Parameters:
names- a list of file names- Returns:
- a list of file objects
- Throws:
IllegalArgumentException- if the array of file names includes a directoryNullPointerException- if the given array contains null elements
-
setLocation
void setLocation(JavaFileManager.Location location, Iterable<? extends File> files) throws IOException Associates the given search path with the given location. Any previous value will be discarded. If the location is a module-oriented or output location, any module-specific associations set up by setLocationForModule will be cancelled.- Parameters:
location- a locationfiles- a list of files, ifnulluse the default search path for this location- Throws:
IllegalArgumentException- iflocationis an output location andfilesdoes not contain exactly one elementIOException- iflocationis an output location and does not represent an existing directory- See Also:
-
setLocationFromPaths
default void setLocationFromPaths(JavaFileManager.Location location, Collection<? extends Path> paths) throws IOException Associates the given search path with the given location. Any previous value will be discarded. If the location is a module-oriented or output location, any module-specific associations set up by setLocationForModule will be cancelled.- Implementation Requirements:
- The default implementation lazily converts each path to a file and calls
setLocation.IllegalArgumentExceptionwill be thrown if any of the paths cannot be converted to a file at the point the conversion happens. - Parameters:
location- a locationpaths- a list of paths, ifnulluse the default search path for this location- Throws:
IllegalArgumentException- iflocationis an output location andpathsdoes not contain exactly one element or if this file manager does not support any of the given pathsIOException- iflocationis an output location andpathsdoes not represent an existing directory- Since:
- 9
- See Also:
-
setLocationForModule
default void setLocationForModule(JavaFileManager.Location location, String moduleName, Collection<? extends Path> paths) throws IOException Associates the given search path with the given module and location, which must be a module-oriented or output location. Any previous value will be discarded. This overrides any default association derived from the search path associated with the location itself. All such module-specific associations will be cancelled if a new search path is associated with the location by calling setLocation or setLocationFromPaths.- Implementation Requirements:
- The default implementation throws
UnsupportedOperationException. - Parameters:
location- the locationmoduleName- the name of the modulepaths- the search path to associate with the location and module.- Throws:
IllegalStateException- if the location is not a module-oriented or output location.UnsupportedOperationException- if this operation is not supported by this file manager.IOException- iflocationis an output location andpathsdoes not represent an existing directory- Since:
- 9
- See Also:
-
getLocation
Returns the search path associated with the given location.- Parameters:
location- a location- Returns:
- a list of files or
nullif this location has no associated search path - Throws:
IllegalStateException- if any element of the search path cannot be converted to a File, or if the search path cannot be represented as a simple series of files.- See Also:
-
getLocationAsPaths
Returns the search path associated with the given location.- Implementation Requirements:
- The default implementation calls
getLocationand then returns anIterableformed by callingtoPath()on eachFilereturned fromgetLocation. - Parameters:
location- a location- Returns:
- a list of paths or
nullif this location has no associated search path - Throws:
IllegalStateException- if the search path cannot be represented as a simple series of paths.- Since:
- 9
- See Also:
-
asPath
Returns the path, if any, underlying this file object (optional operation). File objects derived from aFileSystem, including the default file system, typically have a corresponding underlyingPathobject. In such cases, this method may be used to access that object.- Implementation Requirements:
- The default implementation throws
UnsupportedOperationExceptionfor all files. - Parameters:
file- a file object- Returns:
- a path representing the same underlying file system artifact
- Throws:
IllegalArgumentException- if the file object does not have an underlying pathUnsupportedOperationException- if the operation is not supported by this file manager- Since:
- 9
-
setPathFactory
Specify a factory that can be used to generate a path from a string, or series of strings. If this method is not called, a factory whosegetPathmethod is equivalent to callingjava.nio.file.Paths.get(first, more)will be used.- Implementation Requirements:
- The default implementation of this method ignores the factory that is provided.
- Parameters:
f- the factory- Since:
- 9
-
getJavaFileObjectsFromPaths(Collection)instead, to prevent the possibility of accidentally calling the method with a singlePathas such an argument.