模块 java.compiler
包 javax.tools

接口 JavaFileManager

所有父级接口：
AutoCloseable , Closeable , Flushable , OptionChecker
所有已知的子接口：
StandardJavaFileManager
所有已知的实现类：
ForwardingJavaFileManager
public interface JavaFileManager extends Closeable , Flushable , OptionChecker
用于在 Java 编程语言源文件和类文件上运行的工具的文件管理器。在此上下文中，file 表示常规文件和其他数据源的抽象。

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

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

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

名字的大小写很重要。所有名称都应区分大小写。例如，某些文件系统具有不区分大小写、区分大小写的文件名。代表此类文件的文件对象应注意使用 File.getCanonicalFile() 或类似方式来保留大小写。如果系统不区分大小写，则文件对象必须使用其他方式来保留大小写。

Relative names: 此接口中的某些方法使用相对名称。相对名称是由“/”分隔的非空、非空路径段序列。 '.'或 '..' 是无效的路径段。有效的相对名称必须匹配 RFC 3986 的“无根路径”规则，第 3.3 节。非正式地，这应该是真的：

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

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

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

Implementation note: 此要求的结果是输出到 JarOutputStream 的简单实现不足以实现。也就是说，不是创建直接返回 JarOutputStream 的 JavaFileObject，而是必须缓存内容直到关闭，然后写入 JarOutputStream。

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

自从：
1.6
参见：

  • 方法详情

    • 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 为真，则列出“子包”中的文件对象。

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

      参数：
      location - 一个位置
      packageName - 包名
      kinds - 仅返回这些类型的对象
      recurse - 如果为真，则包含“子包”
      返回：
      符合给定条件的文件对象的 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 - 文件对象
      b - 文件对象
      返回：
      如果给定的文件对象表示相同的底层对象，则为真
      抛出：
      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 - 一个位置
      返回：
      如果位置已知则为真

    • 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 s 转换为 FileObject s。

      实现要求：
      默认实现使用 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
      为输入返回一个 文件对象，代表给定面向包位置的指定包中的指定 相对名称。

      如果返回的对象表示 source 或 类 文件，则它必须是 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 可能会在调用此方法时将原始源文件作为同级文件提供。

      如果返回的对象表示 source 或 类 文件，则它必须是 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 s 转换为 FileObject s。

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

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

      实现要求：
      默认实现使用 originatingFiles 的第一个元素调用 getFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, java.lang.String, javax.tools.FileObject) ，如果有的话，作为 sibling。
      参数：
      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 - 如果位置既不是输出位置也不是面向模块的位置
      自从：
      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 - 如果此文件管理器不支持此操作
      自从：
      9

    • inferModuleName

      default String  inferModuleName(JavaFileManager.Location  location) throws IOException
      从 getLocationForModule 或 listModuleLocations 返回的位置推断模块的名称。
      实现要求：
      此实现抛出 UnsupportedOperationException 。
      参数：
      location - 代表模块的面向包的位置
      返回：
      模块的名称
      抛出：
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此文件管理器不支持此操作
      IllegalArgumentException - 如果此文件管理器不知道该位置
      自从：
      9

    • listLocationsForModules

      default Iterable <Set <JavaFileManager.Location >> listLocationsForModules(JavaFileManager.Location  location) throws IOException
      列出面向模块的位置或输出位置中所有模块的位置。如果给定位置是输出，则返回的位置将是输出位置，否则它将是面向包的位置。
      实现要求：
      此实现抛出 UnsupportedOperationException 。
      参数：
      location - 列出模块的面向模块的位置
      返回：
      一系列包含模块的位置集
      抛出：
      IOException - 如果发生 I/O 错误
      UnsupportedOperationException - 如果此文件管理器不支持此操作
      IllegalArgumentException - 如果位置不是面向模块的位置
      自从：
      9

    • contains

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

      对于面向包的位置，如果存在值，则文件对象包含在该位置中packageName和relativeName这样，以下任一调用都会返回 same 文件对象：

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

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

      getLocationForModule(location, moduleName)
      这样文件对象就包含在该模块的（面向包的）位置中。
      实现要求：
      此实现抛出 UnsupportedOperationException 。
      参数：
      location - 位置
      fo - 文件对象
      返回：
      该文件是否包含在该位置
      抛出：
      IOException - 如果确定结果有问题
      UnsupportedOperationException - 如果不支持该方法
      自从：
      9