Module java.compiler
Package javax.tools

Interface JavaFileManager

所有超接口:
AutoCloseable, Closeable, Flushable, OptionChecker
所有已知子接口:
StandardJavaFileManager
所有已知实现类:
ForwardingJavaFileManager
public interface JavaFileManager extends Closeable, Flushable, OptionChecker
用于操作Java编程语言源文件和类文件的文件管理器。在这个上下文中，文件表示常规文件和其他数据源的抽象。

在构造新的JavaFileObjects时，文件管理器必须确定在哪里创建它们。例如，如果文件管理器管理文件系统上的常规文件，那么在创建或查找文件时，它很可能会有一个当前/工作目录用作默认位置。可以向文件管理器提供一些提示，告诉它在哪里创建文件。任何文件管理器都可以选择忽略这些提示。

此接口中的一些方法使用类名。这些类名必须以完全限定的类和接口名称的Java虚拟机内部形式给出。为方便起见，'.'和'/'是可以互换的。内部形式在《Java虚拟机规范》的第四章中定义。

讨论: 这意味着名称"java/lang.package-info"、"java/lang/package-info"、"java.lang.package-info"是有效的且等效的。与《Java语言规范》第13.1节"二进制形式"中定义的二进制名称进行比较。

名称的大小写是重要的。所有名称应被视为区分大小写。例如，一些文件系统具有不区分大小写但区分大小写的文件名。表示这些文件的文件对象应通过使用File.getCanonicalFile()或类似手段来保留大小写。如果系统不区分大小写，文件对象必须使用其他方法来保留大小写。

相对名称: 此接口中的一些方法使用相对名称。相对名称是由'/'分隔的非空的非空序列的路径段。'.'或'..'是无效的路径段。有效的相对名称必须符合RFC 3986的"path-rootless"规则。非正式地，应该是这样的:

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

此接口中的所有方法都可能抛出SecurityException。

此接口的对象不需要支持多线程访问，即不需要同步。但是，它必须支持对由此对象创建的不同文件对象的并发访问。

实现注意事项: 此要求的一个后果是，对于直接输出到JarOutputStream的平凡实现是不够的。也就是说，而不是创建直接返回JarOutputStream的JavaFileObject，内容必须被缓存直到关闭，然后写入JarOutputStream。

除非明确允许，否则此接口中的所有方法如果给定null参数可能会抛出NullPointerException。

自版本:
1.6
外部规范
另请参阅:

  • Method Details

    • getClassLoader

      ClassLoader getClassLoader(JavaFileManager.Location location)
      返回用于从给定面向包的位置加载插件的类加载器。例如，为了加载注解处理器，编译器将请求ANNOTATION_PROCESSOR_PATH位置的类加载器。
      参数:
      location - 位置
      返回:
      给定位置的类加载器；如果禁用从给定位置加载插件或位置未知，则返回null
      抛出:
      SecurityException - 如果无法在当前安全上下文中创建类加载器
      IllegalStateException - 如果已调用close()并且无法重新打开此文件管理器
      IllegalArgumentException - 如果位置是面向模块的位置

    • list

      Iterable<JavaFileObject> list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) throws IOException
      列出在给定面向包的位置中匹配给定条件的所有文件对象。如果recurse为true，则列出"子包"中的文件对象。

      注意: 即使给定位置对此文件管理器未知，它也可能不返回null。此外，未知位置可能不会导致异常。

      参数:
      location - 位置
      packageName - 包名
      kinds - 仅返回这些种类的对象
      recurse - 如果为true，则包括"子包"
      返回:
      与给定条件匹配的文件对象的Iterable
      抛出:
      IOException - 如果发生I/O错误，或者已调用close()并且无法重新打开此文件管理器
      IllegalArgumentException - 如果位置是面向模块的位置
      IllegalStateException - 如果已调用close()并且无法重新打开此文件管理器

    • inferBinaryName

      String inferBinaryName(JavaFileManager.Location location, JavaFileObject file)
      根据面向包的位置推断文件对象的二进制名称。返回的二进制名称可能不符合《Java语言规范》的有效二进制名称。
      参数:
      location - 位置
      file - 文件对象
      返回:
      如果在给定位置找不到文件对象，则返回二进制名称或null
      抛出:
      IllegalArgumentException - 如果位置是面向模块的位置
      IllegalStateException - 如果已调用close()并且无法重新打开此文件管理器

    • isSameFile

      boolean isSameFile(FileObject a, FileObject b)
      比较两个文件对象，如果它们表示相同的底层对象，则返回true。
      参数:
      a - 文件对象a
      b - 文件对象b
      返回:
      如果给定的文件对象表示相同的底层对象，则返回true
      抛出:
      IllegalArgumentException - 如果任一参数是使用另一个文件管理器创建的，并且此文件管理器不支持外部文件对象

    • handleOption

      boolean handleOption(String current, Iterator<String> remaining)
      处理一个选项。如果current是此文件管理器的选项，则将从remaining中消耗该选项的任何参数并返回true，否则返回false。
      参数:
      current - 当前选项
      remaining - 剩余选项
      返回:
      如果此选项由此文件管理器处理，则返回true，否则返回false
      抛出:
      IllegalArgumentException - 如果此文件管理器的选项使用不正确
      IllegalStateException - 如果已调用close()并且无法重新打开此文件管理器

    • hasLocation

      boolean hasLocation(JavaFileManager.Location location)
      确定此文件管理器是否知道位置。
      参数:
      location - 位置
      返回:
      如果位置已知，则返回true

    • getJavaFileForInput

      JavaFileObject getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) throws IOException
      为在给定包定位位置中的指定类的指定类型表示的输入返回一个文件对象。
      参数:
      location - 位置
      className - 类的名称
      kind - 文件类型，必须是SOURCE或CLASS之一
      返回:
      一个文件对象，如果文件不存在可能返回null
      抛出:
      IllegalArgumentException - 如果此文件管理器不知道位置并且文件管理器不支持未知位置，或者类型无效，或者位置是面向模块的位置
      IOException - 如果发生I/O错误，或者已调用close()并且无法重新打开此文件管理器
      IllegalStateException - 如果已调用close()并且无法重新打开此文件管理器

    • getJavaFileForOutput

      JavaFileObject getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) throws IOException
      为在给定包定位位置中的指定类的指定类型表示的输出返回一个文件对象。

      可选地，此文件管理器可能将兄弟文件作为提示用于放置输出。此提示的确切语义未指定。例如，JDK编译器javac将类文件放置在与源文件相同的目录中，除非提供了类文件输出目录。为了促进此行为，当调用此方法时，javac可能会将原始源文件作为兄弟文件提供。

      参数:
      location - 包定位位置
      className - 类的名称
      kind - 文件类型，必须是SOURCE或CLASS之一
      sibling - 用作放置提示的文件对象；可能为null
      返回:
      用于输出的文件对象
      抛出:
      IllegalArgumentException - 如果此文件管理器不知道兄弟文件，或者位置不为此文件管理器所知，且文件管理器不支持未知位置，或者类型无效，或者位置不是输出位置
      IOException - 如果发生I/O错误，或者已调用close()并且无法重新打开此文件管理器
      IllegalStateException - close()已被调用，且无法重新打开此文件管理器

    • getJavaFileForOutputForOriginatingFiles

      default JavaFileObject getJavaFileForOutputForOriginatingFiles(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject... originatingFiles) throws IOException
      为在给定包定位位置中的指定类的指定类型表示的输出返回一个文件对象。

      提供的originatingFiles表示以某种方式用于创建此方法创建的文件内容的文件。请参阅Filer.createSourceFile(java.lang.CharSequence, javax.lang.model.element.Element...)中的originatingElements。Elements.getFileObjectOf(javax.lang.model.element.Element)可用于将Element转换为FileObject。

      实现要求:
      默认实现将使用originatingFiles的第一个元素（如果有）作为sibling调用getJavaFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, javax.tools.JavaFileObject.Kind, javax.tools.FileObject)。
      参数:
      location - 包定位位置
      className - 类的名称
      kind - 文件类型，必须是SOURCE或CLASS之一
      originatingFiles - 有助于创建此新创建文件的文件；null等效于空的originatingFiles，表示没有已知的原始文件
      返回:
      用于输出的文件对象
      抛出:
      IllegalArgumentException - 如果此文件管理器不知道兄弟文件，或者位置不为此文件管理器所知，且文件管理器不支持未知位置，或者类型无效，或者位置不是输出位置
      IOException - 如果发生I/O错误，或者已调用close()并且无法重新打开此文件管理器
      IllegalStateException - close()已被调用，且无法重新打开此文件管理器
      自:
      18
      参见:

    • getFileForInput

      FileObject getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) throws IOException
      为在给定包定位位置中的指定包中表示的相对名称的输入返回一个文件对象。

      如果返回的对象表示源或类文件，则它必须是JavaFileObject的实例。

      非正式地，此方法返回的文件对象位于位置、包名称和相对名称的连接处。例如，要在SOURCE_PATH位置中的包“com.sun.tools.javac”中定位属性文件“resources/compiler.properties”，可以这样调用此方法：

      getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

      如果在Windows上执行调用，并且将SOURCE_PATH设置为"C:\Documents and Settings\UncleBob\src\share\classes"，则有效结果将是表示文件"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"的文件对象。

      参数:
      location - 一个面向包的位置
      packageName - 包名
      relativeName - 相对名称
      返回:
      一个文件对象，如果文件不存在可能返回null
      抛出:
      IllegalArgumentException - 如果该位置未知于此文件管理器且文件管理器不支持未知位置，或者如果relativeName无效，或者如果该位置是面向模块的位置
      IOException - 如果发生I/O错误，或者如果已调用close()且此文件管理器无法重新打开
      IllegalStateException - 如果已调用close()且此文件管理器无法重新打开

    • getFileForOutput

      FileObject getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) throws IOException
      返回一个用于表示给定位置中指定包中的文件对象的输出，代表相对名称。

      可选地，此文件管理器可能将兄弟文件作为放置输出的提示。此提示的确切语义未指定。例如，JDK编译器javac将类文件放置在与源文件相同的目录中，除非提供了类文件输出目录。为了促进此行为，当调用此方法时，javac可能会将源文件作为兄弟文件提供。

      如果返回的对象表示源或类文件，则必须是JavaFileObject的实例。

      非正式地，此方法返回的文件对象位于位置、包名和相对名称的连接处，或者位于兄弟参数旁边。有关示例，请参见getFileForInput。

      参数:
      location - 输出位置
      packageName - 包名
      relativeName - 相对名称
      sibling - 用作放置提示的文件对象；可能为null
      返回:
      一个文件对象
      抛出:
      IllegalArgumentException - 如果兄弟文件未知于此文件管理器，或者如果该位置未知于此文件管理器且文件管理器不支持未知位置，或者如果relativeName无效，或者如果该位置不是输出位置
      IOException - 如果发生I/O错误，或者如果已调用close()且此文件管理器无法重新打开
      IllegalStateException - 如果已调用close()且此文件管理器无法重新打开

    • getFileForOutputForOriginatingFiles

      default FileObject getFileForOutputForOriginatingFiles(JavaFileManager.Location location, String packageName, String relativeName, FileObject... originatingFiles) throws IOException
      返回一个用于表示给定位置中指定包中的文件对象的输出，代表相对名称。

      提供的originatingFiles表示以某种未指定的方式用于创建此方法创建的文件内容的文件。请参见Filer.createResource(javax.tools.JavaFileManager.Location, java.lang.CharSequence, java.lang.CharSequence, javax.lang.model.element.Element...)中的originatingElements。可以使用Elements.getFileObjectOf(javax.lang.model.element.Element)将Element转换为FileObject。

      如果返回的对象表示源或类文件，则必须是JavaFileObject的实例。

      非正式地，此方法返回的文件对象位于位置、包名和相对名称的连接处，或者位于从originatingFiles推断的位置。有关示例，请参见getFileForInput。

      实现要求:
      默认实现使用originatingFiles的第一个元素（如果有）作为sibling调用getFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, java.lang.String, javax.tools.FileObject)。
      参数:
      location - 输出位置
      packageName - 包名
      relativeName - 相对名称
      originatingFiles - 有助于创建此新创建文件的文件；null等效于空的originatingFiles，表示没有已知的原始文件
      返回:
      一个文件对象
      抛出:
      IllegalArgumentException - 如果兄弟文件未知于此文件管理器，或者如果该位置未知于此文件管理器且文件管理器不支持未知位置，或者如果relativeName无效，或者如果该位置不是输出位置
      IOException - 如果发生I/O错误，或者如果已调用close()且此文件管理器无法重新打开
      IllegalStateException - 如果已调用close()且此文件管理器无法重新打开
      自:
      18
      参见:

    • flush

      void flush() throws IOException
      刷新由此文件管理器直接或间接打开的任何输出资源。刷新已关闭的文件管理器不会产生任何效果。
      指定者:
      flush 在接口 Flushable
      抛出:
      IOException - 如果发生I/O错误
      参见:

    • close

      void close() throws IOException
      释放由此文件管理器直接或间接打开的任何资源。这可能使得此文件管理器无效，并且对此对象或通过此对象获得的任何对象的后续调用的效果未定义，除非明确允许。但是，关闭已经关闭的文件管理器不会产生任何效果。
      指定者:
      close 在接口 AutoCloseable
      指定者:
      close 在接口 Closeable
      抛出:
      IOException - 如果发生I/O错误
      参见:

    • getLocationForModule

      default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location, String moduleName) throws IOException
      获取一个位置，用于在位置内查找命名模块，该位置可以是面向模块的位置或输出位置。如果给定位置是输出位置，则结果将是输出位置，否则将是面向包的位置。
      实现要求:
      此实现会抛出UnsupportedOperationException。
      参数:
      location - 面向模块的位置
      moduleName - 要查找的模块的名称
      返回:
      命名模块的位置
      抛出:
      IOException - 如果发生I/O错误
      UnsupportedOperationException - 如果此操作不受此文件管理器支持
      IllegalArgumentException - 如果该位置既不是输出位置也不是面向模块的位置
      自:
      9

    • getLocationForModule

      default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location, JavaFileObject fo) throws IOException
      获取包含要在位置内查找的特定文件的模块的位置，该位置可以是面向模块的位置或输出位置。如果给定位置是输出位置，则结果将是输出位置，否则将是面向包的位置。
      实现要求:
      此实现会抛出 UnsupportedOperationException 异常。
      参数:
      location - 模块定位
      fo - 文件
      返回:
      包含文件的模块
      抛出:
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此操作不受此文件管理器支持
      IllegalArgumentException - 如果位置既不是输出位置也不是模块定位
      自 JDK 版本:
      9

    • getServiceLoader

      default <S> ServiceLoader<S> getServiceLoader(JavaFileManager.Location location, Class<S> service) throws IOException
      从给定位置获取特定服务类的服务加载器。如果位置是模块定位，则服务加载器将使用该位置中找到的模块中的服务声明。否则，将使用基于包的位置创建服务加载器，在这种情况下，服务将使用 META-INF/services 中的提供者配置文件确定。
      实现要求:
      此实现会抛出 UnsupportedOperationException 异常。
      类型参数:
      S - 服务类
      参数:
      location - 模块定位
      service - 服务类的 Class 对象
      返回:
      给定服务类的服务加载器
      抛出:
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此操作不受此文件管理器支持
      自 JDK 版本:
      9

    • inferModuleName

      default String inferModuleName(JavaFileManager.Location location) throws IOException
      从其位置推断模块的名称，该位置由 getLocationForModule 或 listModuleLocations 返回。
      实现要求:
      此实现会抛出 UnsupportedOperationException 异常。
      参数:
      location - 表示模块的基于包的位置
      返回:
      模块的名称
      抛出:
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此操作不受此文件管理器支持
      IllegalArgumentException - 如果位置不是此文件管理器已知的位置之一
      自 JDK 版本:
      9

    • listLocationsForModules

      default Iterable<Set<JavaFileManager.Location>> listLocationsForModules(JavaFileManager.Location location) throws IOException
      列出模块定位或输出位置中所有模块的位置。返回的位置将是输出位置（如果给定位置是输出位置），或者将是基于包的位置。
      实现要求:
      此实现会抛出 UnsupportedOperationException 异常。
      参数:
      location - 要列出模块的模块定位
      返回:
      一系列包含模块的位置集合
      抛出:
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此操作不受此文件管理器支持
      IllegalArgumentException - 如果位置不是模块定位
      自 JDK 版本:
      9

    • contains

      default boolean contains(JavaFileManager.Location location, FileObject fo) throws IOException
      确定给定文件对象是否“包含在”指定位置中。

      对于基于包的位置，如果存在 packageName 和 relativeName 的值，使得以下任一调用返回 相同 文件对象，则文件对象包含在该位置中：

      getFileForInput(location, packageName, relativeName)
getFileForOutput(location, packageName, relativeName, null)

      对于模块定位，如果存在可以通过以下调用获得的模块，则文件对象包含在该位置中：

      getLocationForModule(location, moduleName)
      使得文件对象包含在该模块的（基于包的）位置中。
      实现要求:
      此实现会抛出 UnsupportedOperationException 异常。
      参数:
      location - 位置
      fo - 文件对象
      返回:
      文件是否包含在位置中
      抛出:
      IOException - 如果确定结果时出现问题
      UnsupportedOperationException - 如果不支持该方法
      自 JDK 版本:
      9