Module java.compiler
Package 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

All Methods Instance Methods Abstract Methods Default Methods
`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.
`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)` 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, getModuleLocation, getModuleLocation, getServiceLoader, handleOption, hasLocation, inferBinaryName, inferModuleName, list, listModuleLocations`

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