javax.tools

Interface StandardJavaFileManager

All Superinterfaces:

AutoCloseable, Closeable, Flushable, JavaFileManager, OptionChecker

public interface StandardJavaFileManager
extends JavaFileManager

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()))

  • and the methods FileObject.openOutputStream(), and FileObject.openWriter() must succeed if the following would succeed (ignoring encoding issues):

    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.

Since:

1.6

Nested Class Summary

Nested classes/interfaces inherited from interface javax.tools.JavaFileManager

JavaFileManager.Location

Method Summary

Modifier and Type	Method and Description
default Path	asPath(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.
default Iterable<? extends JavaFileObject>	getJavaFileObjects(Path... paths) Returns file objects representing the given paths.
Iterable<? extends JavaFileObject>	getJavaFileObjects(String... names) Returns file objects representing the given file names.
Iterable<? extends JavaFileObject>	getJavaFileObjectsFromFiles(Iterable<? extends File> files) Returns file objects representing the given files.
default Iterable<? extends JavaFileObject>	getJavaFileObjectsFromPaths(Iterable<? extends Path> paths) Returns file objects representing the given paths.
Iterable<? extends JavaFileObject>	getJavaFileObjectsFromStrings(Iterable<String> names) Returns file objects representing the given file names.
Iterable<? extends File>	getLocation(JavaFileManager.Location location) Returns the search path associated with the given location.
default Iterable<? extends Path>	getLocationAsPaths(JavaFileManager.Location location) Returns the search path associated with the given location.
boolean	isSameFile(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.
void	setLocation(JavaFileManager.Location location, Iterable<? extends File> files) Associates the given search path with the given location.
default void	setLocationFromPaths(JavaFileManager.Location location, Iterable<? extends Path> paths) Associates the given search path with the given location.

Methods inherited from interface javax.tools.JavaFileManager

close, flush, getClassLoader, getFileForInput, getFileForOutput, getJavaFileForInput, getJavaFileForOutput, handleOption, hasLocation, inferBinaryName, list

Methods inherited from interface javax.tools.OptionChecker

isSupportedOption

Method Detail

isSameFile

boolean isSameFile(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.

Specified by:

isSameFile in interface JavaFileManager

Parameters:

a - a file object

b - 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

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

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(Iterable<? extends Path> paths)

Returns file objects representing the given paths.

The default implementation converts each path to a file and calls getJavaObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file.

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

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

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

NullPointerException - if the given array contains null elements

getJavaFileObjects

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

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

     getJavaFileObjectsFromPaths(Arrays.asList(paths))
 

Parameters:

paths - an array of paths

Returns:

a list of file objects

Throws:

IllegalArgumentException - if the array of files includes a directory

NullPointerException - if the given array contains null elements

Since:

9

getJavaFileObjectsFromStrings

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

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

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

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 directory

NullPointerException - 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.

Parameters:

location - a location

files - a list of files, if null use the default search path for this location

Throws:

IllegalArgumentException - if location is an output location and files does not contain exactly one element

IOException - if location is an output location and does not represent an existing directory

See Also:

getLocation(javax.tools.JavaFileManager.Location)

setLocationFromPaths

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

Associates the given search path with the given location. Any previous value will be discarded.

The default implementation converts each path to a file and calls getJavaObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file.

Parameters:

location - a location

paths - a list of paths, if null use the default search path for this location

Throws:

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

IOException - if location is an output location and paths does not represent an existing directory

Since:

9

See Also:

getLocation(javax.tools.JavaFileManager.Location)

getLocation

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

Returns the search path associated with the given location.

Parameters:

location - a location

Returns:

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

Throws:

IllegalStateException - if any element of the search path cannot be converted to a File.

See Also:

setLocation(javax.tools.JavaFileManager.Location, java.lang.Iterable<? extends java.io.File>), Path.toFile()

getLocationAsPaths

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

Returns the search path associated with the given location.

Parameters:

location - a location

Returns:

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

Since:

9

See Also:

setLocationFromPaths(javax.tools.JavaFileManager.Location, java.lang.Iterable<? extends java.nio.file.Path>)

asPath

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.

The default implementation throws UnsupportedOperationException for 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 path

UnsupportedOperationException - if the operation is not supported by this file manager

Since:

9