Module java.compiler
Package javax.tools

Interface JavaFileManager

All Superinterfaces:
AutoCloseable, Closeable, Flushable, OptionChecker
All Known Subinterfaces:
StandardJavaFileManager
All Known Implementing Classes:
ForwardingJavaFileManager
public interface JavaFileManager extends Closeable, Flushable, OptionChecker
File manager for tools operating on Java programming language source and class files. In this context, file means an abstraction of regular files and other sources of data.

When constructing new JavaFileObjects, the file manager must determine where to create them. For example, if a file manager manages regular files on a file system, it would most likely have a current/working directory to use as default location when creating or finding files. A number of hints can be provided to a file manager as to where to create files. Any file manager might choose to ignore these hints.

Some methods in this interface use class names. Such class names must be given in the Java Virtual Machine internal form of fully qualified class and interface names. For convenience '.' and '/' are interchangeable. The internal form is defined in chapter four of The Java Virtual Machine Specification.

Discussion: this means that the names "java/lang.package-info", "java/lang/package-info", "java.lang.package-info", are valid and equivalent. Compare to binary name as defined in The Java Language Specification, section 13.1 "The Form of a Binary".

The case of names is significant. All names should be treated as case-sensitive. For example, some file systems have case-insensitive, case-aware file names. File objects representing such files should take care to preserve case by using File.getCanonicalFile() or similar means. If the system is not case-aware, file objects must use other means to preserve case.

Relative names: some methods in this interface use relative names. A relative name is a non-null, non-empty sequence of path segments separated by '/'. '.' or '..' are invalid path segments. A valid relative name must match the "path-rootless" rule of RFC 3986, section 3.3. Informally, this should be true: 

  URI.create(relativeName).normalize().getPath().equals(relativeName)

All methods in this interface might throw a SecurityException.

An object of this interface is not required to support multi-threaded access, that is, be synchronized. However, it must support concurrent access to different file objects created by this object.

Implementation note: a consequence of this requirement is that a trivial implementation of output to a JarOutputStream is not a sufficient implementation. That is, rather than creating a JavaFileObject that returns the JarOutputStream directly, the contents must be cached until closed and then written to the JarOutputStream.

Unless explicitly allowed, all methods in this interface might throw a NullPointerException if given a null argument.

Since:
1.6
See Also:
JavaFileObject, FileObject

  • Method Details

    • getClassLoader

      ClassLoader getClassLoader​(JavaFileManager.Location location)
      Returns a class loader for loading plug-ins from the given package-oriented location. For example, to load annotation processors, a compiler will request a class loader for the ANNOTATION_PROCESSOR_PATH location.
      Parameters:
      location - a location
      Returns:
      a class loader for the given location; or null if loading plug-ins from the given location is disabled or if the location is not known
      Throws:
      SecurityException - if a class loader can not be created in the current security context
      IllegalStateException - if close() has been called and this file manager cannot be reopened
      IllegalArgumentException - if the location is a module-oriented location

    • list

      Iterable<JavaFileObject> list​(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) throws IOException
      Lists all file objects matching the given criteria in the given package-oriented location. List file objects in "subpackages" if recurse is true.

      Note: even if the given location is unknown to this file manager, it may not return null. Also, an unknown location may not cause an exception.

      Parameters:
      location - a location
      packageName - a package name
      kinds - return objects only of these kinds
      recurse - if true include "subpackages"
      Returns:
      an Iterable of file objects matching the given criteria
      Throws:
      IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
      IllegalArgumentException - if the location is a module-oriented location
      IllegalStateException - if close() has been called and this file manager cannot be reopened

    • inferBinaryName

      String inferBinaryName​(JavaFileManager.Location location,