OpenJDK 27 · javax.tools.StandardJavaFileManager · APIdia, the JavaDoc alternative

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();
  DiagnosticCollector<JavaFileObject> diagnostics =
      new DiagnosticCollector<JavaFileObject>();
  StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);

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:

File names need not be canonical.
For file objects representing regular files
- the method FileObject#delete() is equivalent to File#delete(),
- the method FileObject#getLastModified() is equivalent to File#lastModified(),
- the methods FileObject#getCharContent(boolean), FileObject#openInputStream(), and FileObject#openReader(boolean) must succeed if the following would succeed (ignoring encoding issues):
  new FileInputStream(new File(fileObject.toUri()))
```
new FileInputStream(new File(fileObject.toUri()))
```
- and the methods FileObject#openOutputStream(), and FileObject#openWriter() must succeed if the following would succeed (ignoring encoding issues):
  new FileOutputStream(new File(fileObject.toUri()))
```
new FileOutputStream(new File(fileObject.toUri()))
```
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).

According to these rules, the following URIs, for example, are allowed:

file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java
jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!/com/vendora/LibraryClass.class

Whereas these are not (reason in parentheses):

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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	StandardJavaFileManager.PathFactory Factory to create `Path` objects from strings.

Method Summary

Modifier and Type	Method and Description
private static <T> Collection<T>	asCollection(Iterable<T> iterable)
private static Iterable<File>	asFiles(final Iterable<? extends Path> paths)
public default Path	Returns: a path representing the same underlying file system artifact asPath(FileObject a file object file) Returns the path, if any, underlying this file object (optional operation).
private static Iterable<Path>	asPaths(final Iterable<? extends File> files)
public Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjects(File... an array of files files) Returns file objects representing the given files.
public default Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjects(Path... an array of paths paths) Returns file objects representing the given paths.
public Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjects(String... a list of file names names) Returns file objects representing the given file names.
public Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjectsFromFiles(Iterable<? extends File> a list of files files) Returns file objects representing the given files.
public default Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjectsFromPaths(Collection<? extends Path> a list of paths paths) Returns file objects representing the given paths.
public default Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjectsFromPaths(Iterable<? extends Path> a list of paths paths) Deprecated since 13. use `getJavaFileObjectsFromPaths(Collection)` instead, to prevent the possibility of accidentally calling the method with a single `Path` as such an argument. Returns file objects representing the given paths.
public Iterable<? extends JavaFileObject>	Returns: a list of file objects getJavaFileObjectsFromStrings(Iterable<String> a list of file names names) Returns file objects representing the given file names.
public Iterable<? extends File>	Returns: a list of files or `null` if this location has no associated search path getLocation(JavaFileManager.Location a location location) Returns the search path associated with the given location.
public default Iterable<? extends Path>	Returns: a list of paths or `null` if this location has no associated search path getLocationAsPaths(JavaFileManager.Location a location location) Returns the search path associated with the given location.
public boolean	Returns: true if the given file objects represent the same canonical file, zip file entry or path; false otherwise isSameFile(FileObject a file object a, FileObject a file object b) Redeclares javax.tools.JavaFileManager.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.
public void	setLocation(JavaFileManager.Location a location location, Iterable<? extends File> a list of files, if `null` use the default search path for this location files) Associates the given search path with the given location.
public default void	setLocationForModule(JavaFileManager.Location the location location, String the name of the module moduleName, Collection<? extends Path> the search path to associate with the location and module. paths) Associates the given search path with the given module and location, which must be a module-oriented or output location.
public default void	setLocationFromPaths(JavaFileManager.Location a location location, Collection<? extends Path> a list of paths, if `null` use the default search path for this location paths) Associates the given search path with the given location.
public default void	setPathFactory(StandardJavaFileManager.PathFactory the factory f) Specify a factory that can be used to generate a path from a string, or series of strings.

Method Detail

asCollection	back to summary
private static <T> Collection<T> asCollection(Iterable<T> iterable)

asFiles	back to summary
private static Iterable<File> asFiles(final Iterable<? extends Path> paths)

asPath back to summary

asPath	back to summary
public default Path asPath(FileObject file) Returns the path, if any, underlying this file object (optional operation). File objects derived from a `FileSystem`, including the default file system, typically have a corresponding underlying `Path` object. In such cases, this method may be used to access that object. Implementation Specification The default implementation throws `UnsupportedOperationException` for all files. Parameters file:FileObject a file object Returns:Path a path representing the same underlying file system artifact Exceptions IllegalArgumentException: if the file object does not have an underlying path UnsupportedOperationException: if the operation is not supported by this file manager Since 9

public default Path asPath(FileObject file)

Returns the path, if any, underlying this file object (optional operation). File objects derived from a FileSystem, including the default file system, typically have a corresponding underlying Path object. In such cases, this method may be used to access that object.

Implementation Specification

The default implementation throws UnsupportedOperationException for all files.

Parameters

file:FileObject: a file object

Returns:Path

a path representing the same underlying file system artifact

Exceptions

IllegalArgumentException:: if the file object does not have an underlying path
UnsupportedOperationException:: if the operation is not supported by this file manager

Since

asPaths	back to summary
private static Iterable<Path> asPaths(final Iterable<? extends File> files)

getJavaFileObjects back to summary

getJavaFileObjects	back to summary
public Iterable<? extends JavaFileObject> getJavaFileObjects(File... files) Returns file objects representing the given files. Convenience method equivalent to: `getJavaFileObjectsFromFiles(Arrays.asList(files))` getJavaFileObjectsFromFiles(Arrays.asList(files)) Parameters files:File[] an array of files Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the array of files includes a directory or if this file manager does not support any of the given paths NullPointerException: if the given array contains null elements

public Iterable<? extends JavaFileObject> getJavaFileObjects(File... files)

Returns file objects representing the given files. Convenience method equivalent to:

getJavaFileObjectsFromFiles(Arrays.asList(files))

Parameters

files:File[]: an array of files

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the array of files includes a directory or if this file manager does not support any of the given paths
NullPointerException:: if the given array contains null elements

getJavaFileObjects back to summary

getJavaFileObjects	back to summary
public default Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths) Returns file objects representing the given paths. Convenience method equivalent to: `getJavaFileObjectsFromPaths(Arrays.asList(paths))` getJavaFileObjectsFromPaths(Arrays.asList(paths)) Implementation Specification The default implementation will only throw `NullPointerException` if getJavaFileObjectsFromPaths(Collection) throws it. Parameters paths:Path[] an array of paths Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the array of files includes a directory or if this file manager does not support any of the given paths NullPointerException: if the given array contains null elements Since 9

public default Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths)

Returns file objects representing the given paths. Convenience method equivalent to:

getJavaFileObjectsFromPaths(Arrays.asList(paths))

Implementation Specification

The default implementation will only throw NullPointerException if getJavaFileObjectsFromPaths(Collection) throws it.

Parameters

paths:Path[]: an array of paths

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the array of files includes a directory or if this file manager does not support any of the given paths
NullPointerException:: if the given array contains null elements

Since

getJavaFileObjects back to summary

getJavaFileObjects	back to summary
public Iterable<? extends JavaFileObject> getJavaFileObjects(String... names) Returns file objects representing the given file names. Convenience method equivalent to: `getJavaFileObjectsFromStrings(Arrays.asList(names))` getJavaFileObjectsFromStrings(Arrays.asList(names)) Parameters names:String[] a list of file names Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the array of file names includes a directory NullPointerException: if the given array contains null elements

public Iterable<? extends JavaFileObject> getJavaFileObjects(String... names)

Returns file objects representing the given file names. Convenience method equivalent to:

getJavaFileObjectsFromStrings(Arrays.asList(names))

Parameters

names:String[]: a list of file names

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the array of file names includes a directory
NullPointerException:: if the given array contains null elements

getJavaFileObjectsFromFiles	back to summary
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files) Returns file objects representing the given files. Parameters files:Iterable<? extends File> a list of files Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the list of files includes a directory

getJavaFileObjectsFromFiles

back to summary

public Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files)

Returns file objects representing the given files.

Parameters

files:Iterable<? extends File>: a list of files

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the list of files includes a directory

getJavaFileObjectsFromPaths back to summary

getJavaFileObjectsFromPaths	back to summary
public default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Collection<? extends Path> paths) Returns file objects representing the given paths. Implementation Specification The default implementation lazily converts each path to a file and calls `getJavaFileObjectsFromFiles`. `IllegalArgumentException` will be thrown if any of the paths cannot be converted to a file at the point the conversion happens. Parameters paths:Collection<? extends Path> a list of paths Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the list of paths includes a directory or if this file manager does not support any of the given paths Since 13

public default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Collection<? extends Path> paths)

Returns file objects representing the given paths.

Implementation Specification

The default implementation lazily converts each path to a file and calls getJavaFileObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file at the point the conversion happens.

Parameters

paths:Collection<? extends Path>: a list of paths

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the list of paths includes a directory or if this file manager does not support any of the given paths

Since

getJavaFileObjectsFromPaths back to summary

getJavaFileObjectsFromPaths	back to summary
public default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> paths) Deprecated since 13. use `getJavaFileObjectsFromPaths(Collection)` instead, to prevent the possibility of accidentally calling the method with a single `Path` as such an argument. Although `Path` implements `Iterable<Path>`, it would almost never be correct to pass a single `Path` and have it be treated as an `Iterable` of its components. Returns file objects representing the given paths. Implementation Specification The default implementation lazily converts each path to a file and calls `getJavaFileObjectsFromPaths`. `IllegalArgumentException` will be thrown if any of the paths cannot be converted to a file at the point the conversion happens. Parameters paths:Iterable<? extends Path> a list of paths Returns:Iterable<? extends JavaFileObject> a list of file objects Annotations @Deprecated since:13 Exceptions IllegalArgumentException: if the list of paths includes a directory or if this file manager does not support any of the given paths. Since 9

public default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> paths)

Deprecated

since 13.

use getJavaFileObjectsFromPaths(Collection) instead, to prevent the possibility of accidentally calling the method with a single Path as such an argument. Although Path implements Iterable<Path>, it would almost never be correct to pass a single Path and have it be treated as an Iterable of its components.

Returns file objects representing the given paths.

Implementation Specification

The default implementation lazily converts each path to a file and calls getJavaFileObjectsFromPaths. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file at the point the conversion happens.

Parameters

paths:Iterable<? extends Path>: a list of paths

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Annotations

@Deprecated
since:13

Exceptions

IllegalArgumentException:: if the list of paths includes a directory or if this file manager does not support any of the given paths.

Since

getJavaFileObjectsFromStrings	back to summary
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> names) Returns file objects representing the given file names. Parameters names:Iterable<String> a list of file names Returns:Iterable<? extends JavaFileObject> a list of file objects Exceptions IllegalArgumentException: if the list of file names includes a directory

getJavaFileObjectsFromStrings

back to summary

public Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> names)

Returns file objects representing the given file names.

Parameters

names:Iterable<String>: a list of file names

Returns:Iterable<? extends JavaFileObject>

a list of file objects

Exceptions

IllegalArgumentException:: if the list of file names includes a directory

getLocation back to summary

getLocation	back to summary
public Iterable<? extends File> getLocation(JavaFileManager.Location location) Returns the search path associated with the given location. Parameters location:JavaFileManager.Location a location Returns:Iterable<? extends File> a list of files or `null` if this location has no associated search path Exceptions 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 `setLocation`, `Path#toFile`

public Iterable<? extends File> getLocation(JavaFileManager.Location location)

Returns the search path associated with the given location.

Parameters

location:JavaFileManager.Location: a location

Returns:Iterable<? extends File>

a list of files or null if this location has no associated search path

Exceptions

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

setLocation, Path#toFile

getLocationAsPaths back to summary

getLocationAsPaths	back to summary
public default Iterable<? extends Path> getLocationAsPaths(JavaFileManager.Location location) Returns the search path associated with the given location. Implementation Specification The default implementation calls `getLocation` and then returns an `Iterable` formed by calling `toPath()` on each `File` returned from `getLocation`. Parameters location:JavaFileManager.Location a location Returns:Iterable<? extends Path> a list of paths or `null` if this location has no associated search path Exceptions IllegalStateException: if the search path cannot be represented as a simple series of paths. Since 9 See Also `setLocationFromPaths`

public default Iterable<? extends Path> getLocationAsPaths(JavaFileManager.Location location)

Returns the search path associated with the given location.

Implementation Specification

The default implementation calls getLocation and then returns an Iterable formed by calling toPath() on each File returned from getLocation.

Parameters

location:JavaFileManager.Location: a location

Returns:Iterable<? extends Path>

a list of paths or null if this location has no associated search path

Exceptions

IllegalStateException:: if the search path cannot be represented as a simple series of paths.

Since

See Also

setLocationFromPaths

isSameFile	back to summary
public boolean isSameFile(FileObject a, FileObject b) Redeclares javax.tools.JavaFileManager.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. Parameters a:FileObject a file object b:FileObject a file object Returns:boolean true if the given file objects represent the same canonical file, zip file entry or path; false otherwise Annotations @Override Exceptions IllegalArgumentException: if either of the arguments were created with another file manager implementation

isSameFile

back to summary

public boolean isSameFile(FileObject a, FileObject b)

Redeclares javax.tools.JavaFileManager.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.

Parameters

a:FileObject: a file object
b:FileObject: a file object

Returns:boolean

true if the given file objects represent the same canonical file, zip file entry or path; false otherwise

Annotations

@Override

Exceptions

IllegalArgumentException:: if either of the arguments were created with another file manager implementation

setLocation back to summary

setLocation	back to summary
public 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:JavaFileManager.Location a location files:Iterable<? extends File> a list of files, if `null` use the default search path for this location Exceptions IOException: if `location` is an output location and does not represent an existing directory IllegalArgumentException: if `location` is an output location and `files` does not contain exactly one element See Also `getLocation`

public 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:JavaFileManager.Location: a location
files:Iterable<? extends File>: a list of files, if null use the default search path for this location

Exceptions

IOException:: if location is an output location and does not represent an existing directory
IllegalArgumentException:: if location is an output location and files does not contain exactly one element

See Also

getLocation

setLocationForModule back to summary

setLocationForModule	back to summary
public 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 Specification The default implementation throws `UnsupportedOperationException`. Parameters location:JavaFileManager.Location the location moduleName:String the name of the module paths:Collection<? extends Path> the search path to associate with the location and module. Exceptions IOException: if `location` is an output location and `paths` does not represent an existing directory IllegalStateException: if the location is not a module-oriented or output location. UnsupportedOperationException: if this operation is not supported by this file manager. Since 9 See Also `setLocation`, `setLocationFromPaths`

public 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 Specification

The default implementation throws UnsupportedOperationException.

Parameters

location:JavaFileManager.Location: the location
moduleName:String: the name of the module
paths:Collection<? extends Path>: the search path to associate with the location and module.

Exceptions

IOException:: if location is an output location and paths does not represent an existing directory
IllegalStateException:: if the location is not a module-oriented or output location.
UnsupportedOperationException:: if this operation is not supported by this file manager.

Since

See Also

setLocation, setLocationFromPaths

setLocationFromPaths back to summary

setLocationFromPaths	back to summary
public 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 Specification The default implementation lazily converts each path to a file and calls `setLocation`. `IllegalArgumentException` will be thrown if any of the paths cannot be converted to a file at the point the conversion happens. Parameters location:JavaFileManager.Location a location paths:Collection<? extends Path> a list of paths, if `null` use the default search path for this location Exceptions IOException: if `location` is an output location and `paths` does not represent an existing directory IllegalArgumentException: if `location` is an output location and `paths` does not contain exactly one element or if this file manager does not support any of the given paths Since 9 See Also `getLocation`

public default void setLocationFromPaths(JavaFileManager.Location location, Collection<? extends Path> paths) throws IOException

Implementation Specification

The default implementation lazily converts each path to a file and calls setLocation. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file at the point the conversion happens.

Parameters

location:JavaFileManager.Location: a location
paths:Collection<? extends Path>: a list of paths, if null use the default search path for this location

Exceptions

IOException:: if location is an output location and paths does not represent an existing directory
IllegalArgumentException:: if location is an output location and paths does not contain exactly one element or if this file manager does not support any of the given paths

Since

See Also

getLocation

setPathFactory back to summary

setPathFactory	back to summary
public default void setPathFactory(StandardJavaFileManager.PathFactory f) 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 whose `getPath` method is equivalent to calling `java.nio.file.Paths.get(first, more)` will be used. Implementation Specification The default implementation of this method ignores the factory that is provided. Parameters f:StandardJavaFileManager.PathFactory the factory Since 9

public default void setPathFactory(StandardJavaFileManager.PathFactory f)

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 whose getPath method is equivalent to calling java.nio.file.Paths.get(first, more) will be used.

Implementation Specification

The default implementation of this method ignores the factory that is provided.

Parameters

f:StandardJavaFileManager.PathFactory: the factory

Since

public Interface StandardJavaFileManager

Nested and Inner Type Summary

Method Summary

Method Detail

public Interface StandardJavaFileManager.PathFactory

Method Summary

Method Detail