StandardJavaFileManager (Java SE 16 & JDK 16) (original) (raw)

All Superinterfaces:

[AutoCloseable](../../../java.base/java/lang/AutoCloseable.html "interface in java.lang"), [Closeable](../../../java.base/java/io/Closeable.html "interface in java.io"), [Flushable](../../../java.base/java/io/Flushable.html "interface in java.io"), [JavaFileManager](JavaFileManager.html "interface in javax.tools"), [OptionChecker](OptionChecker.html "interface in javax.tools")

public interface StandardJavaFileManagerextends JavaFileManager

File manager based on java.io.File and java.nio.file.Path. A common way to obtain an instance of this class is usinggetStandardFileManager, 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 regularfiles,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()](FileObject.html#delete%28%29) is equivalent to [File.delete()](../../../java.base/java/io/File.html#delete%28%29),
  • the method [FileObject.getLastModified()](FileObject.html#getLastModified%28%29) is equivalent to [File.lastModified()](../../../java.base/java/io/File.html#lastModified%28%29),
  • the methods [FileObject.getCharContent(boolean)](FileObject.html#getCharContent%28boolean%29),[FileObject.openInputStream()](FileObject.html#openInputStream%28%29), and[FileObject.openReader(boolean)](FileObject.html#openReader%28boolean%29) must succeed if the following would succeed (ignoring encoding issues):

    new FileInputStream(new File(fileObject.toUri()))

  • and the methods[FileObject.openOutputStream()](FileObject.html#openOutputStream%28%29), and[FileObject.openWriter()](FileObject.html#openWriter%28%29) must succeed if the following would succeed (ignoring encoding issues):

    new FileOutputStream(new File(fileObject.toUri()))

• The URI returned from[FileObject.toUri()](FileObject.html#toUri%28%29)
  • 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.

API Note:

Some methods on this interface take a Collection<? extends Path> instead of Iterable<? extends Path>. This is to prevent the possibility of accidentally calling the method with a single Path as such an argument, because althoughPath implements Iterable<Path>, it would almost never be correct to call these methods with a single Path and have it be treated as an Iterable of its components.

Since:

1.6

• Nested Class Summary

Nested Classes
static interface
Factory to create Path objects from strings.

• Method Summary

Returns the path, if any, underlying this file object (optional operation).
Returns file objects representing the given files.
Returns file objects representing the given file names.
Returns file objects representing the given paths.
Returns file objects representing the given files.
Returns file objects representing the given paths.
Returns file objects representing the given file names.
Returns the search path associated with the given location.
Returns the search path associated with the given location.
boolean
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
Associates the given search path with the given location.
default void
Associates the given search path with the given module and location, which must be a module-oriented or output location.
default void
Associates the given search path with the given location.
default void
Specify 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](JavaFileManager.html#close%28%29), [contains](JavaFileManager.html#contains%28javax.tools.JavaFileManager.Location,javax.tools.FileObject%29), [flush](JavaFileManager.html#flush%28%29), [getClassLoader](JavaFileManager.html#getClassLoader%28javax.tools.JavaFileManager.Location%29), [getFileForInput](JavaFileManager.html#getFileForInput%28javax.tools.JavaFileManager.Location,java.lang.String,java.lang.String%29), [getFileForOutput](JavaFileManager.html#getFileForOutput%28javax.tools.JavaFileManager.Location,java.lang.String,java.lang.String,javax.tools.FileObject%29), [getJavaFileForInput](JavaFileManager.html#getJavaFileForInput%28javax.tools.JavaFileManager.Location,java.lang.String,javax.tools.JavaFileObject.Kind%29), [getJavaFileForOutput](JavaFileManager.html#getJavaFileForOutput%28javax.tools.JavaFileManager.Location,java.lang.String,javax.tools.JavaFileObject.Kind,javax.tools.FileObject%29), [getLocationForModule](JavaFileManager.html#getLocationForModule%28javax.tools.JavaFileManager.Location,java.lang.String%29), [getLocationForModule](JavaFileManager.html#getLocationForModule%28javax.tools.JavaFileManager.Location,javax.tools.JavaFileObject%29), [getServiceLoader](JavaFileManager.html#getServiceLoader%28javax.tools.JavaFileManager.Location,java.lang.Class%29), [handleOption](JavaFileManager.html#handleOption%28java.lang.String,java.util.Iterator%29), [hasLocation](JavaFileManager.html#hasLocation%28javax.tools.JavaFileManager.Location%29), [inferBinaryName](JavaFileManager.html#inferBinaryName%28javax.tools.JavaFileManager.Location,javax.tools.JavaFileObject%29), [inferModuleName](JavaFileManager.html#inferModuleName%28javax.tools.JavaFileManager.Location%29), [list](JavaFileManager.html#list%28javax.tools.JavaFileManager.Location,java.lang.String,java.util.Set,boolean%29), [listLocationsForModules](JavaFileManager.html#listLocationsForModules%28javax.tools.JavaFileManager.Location%29)

• 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:
  [isSameFile](JavaFileManager.html#isSameFile%28javax.tools.FileObject,javax.tools.FileObject%29) in interface [JavaFileManager](JavaFileManager.html "interface in javax.tools")
  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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the list of files includes a directory

  • getJavaFileObjectsFromPaths

  Returns file objects representing the given paths.
  Implementation Requirements:
  The default implementation converts each path to a file and callsgetJavaObjectsFromFiles. 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the list of paths includes a directory or if this file manager does not support any of the given paths.
  Since:
  13

  • getJavaFileObjectsFromPaths

  Returns file objects representing the given paths.
  Implementation Requirements:
  The default implementation converts each path to a file and callsgetJavaObjectsFromFiles. 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the array of files includes a directory
  [NullPointerException](../../../java.base/java/lang/NullPointerException.html "class in java.lang") - if the given array contains null elements

  • getJavaFileObjects

  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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the array of files includes a directory
  [NullPointerException](../../../java.base/java/lang/NullPointerException.html "class in java.lang") - 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - 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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the array of file names includes a directory
  [NullPointerException](../../../java.base/java/lang/NullPointerException.html "class in java.lang") - if the given array contains null elements

  • setLocation

  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 location
  files - a list of files, if null use the default search path for this location
  Throws:
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if location is an output location and files does not contain exactly one element
  [IOException](../../../java.base/java/io/IOException.html "class in java.io") - if location is an output location and does not represent an existing directory
  See Also:
  getLocation(javax.tools.JavaFileManager.Location)

  • setLocationFromPaths

  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 converts each path to a file and callsgetJavaObjectsFromFiles.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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - 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](../../../java.base/java/io/IOException.html "class in java.io") - if location is an output location andpaths does not represent an existing directory
  Since:
  9
  See Also:
  getLocation(javax.tools.JavaFileManager.Location)

  • setLocationForModule

  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 callingsetLocation orsetLocationFromPaths.
  Parameters:
  location - the location
  moduleName - the name of the module
  paths - the search path to associate with the location and module.
  Throws:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if the location is not a module-oriented or output location.
  [UnsupportedOperationException](../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if this operation is not supported by this file manager.
  [IOException](../../../java.base/java/io/IOException.html "class in java.io") - if location is an output location andpaths does not represent an existing directory
  Since:
  9
  See Also:
  setLocation(javax.tools.JavaFileManager.Location, java.lang.Iterable<? extends java.io.File>), setLocationFromPaths(javax.tools.JavaFileManager.Location, java.util.Collection<? extends java.nio.file.Path>)

  • getLocation

  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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - 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(javax.tools.JavaFileManager.Location, java.lang.Iterable<? extends java.io.File>), Path.toFile()

  • getLocationAsPaths

  Returns the search path associated with the given location.
  Implementation Requirements:
  The default implementation calls getLocation and then returns an Iterable formed by calling toPath() on each File returned from getLocation.
  Parameters:
  location - a location
  Returns:
  a list of paths or null if this location has no associated search path
  Throws:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if the search path cannot be represented as a simple series of paths.
  Since:
  9
  See Also:
  setLocationFromPaths(javax.tools.JavaFileManager.Location, java.util.Collection<? extends java.nio.file.Path>)

  • asPath

  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 underlyingPath object. In such cases, this method may be used to access that object.
  Implementation Requirements:
  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](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the file object does not have an underlying path
  [UnsupportedOperationException](../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - 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 whose getPath method 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