模块  java.compiler
软件包  javax.annotation.processing

Interface Filer

  • public interface Filer
    此接口支持注释处理器创建新文件。 以这种方式创建的文件将为实现此接口的注释处理工具所知，从而更好地使工具能够管理它们。 所以创建将源代码和类文件considered for processing该工具在随后round of processing后close方法被调用的Writer或OutputStream用来写文件的内容。 区分三种文件：源文件，类文件和辅助资源文件。

    有两个不同的支持位置（逻辑文件系统中的子树），其中放置了新创建的文件：一个用于new source files ，另一个用于new class files 。 （这些可能在工具的命令行中指定，例如，使用诸如-s和-d 。）新源文件和新类文件的实际位置在工具的特定运行中可能是也可能不同。 可以在任一位置创建资源文件。 读取和写入资源的方法采用相对名称参数。 相对名称是由空的非空的非空路径段序列，由'/' ; '.'和'..'是无效的路径段。 有效的相对名称必须与“路径无根”规则RFC 3986 ，第3.3节相匹配。

    文件创建方法采用可变数量的参数，以允许将原始元素作为提示提供给工具基础结构，以更好地管理依赖关系。 原始元素是类型或包（代表package-info文件）或模块（代表module-info文件），它们导致注释处理器尝试创建新文件。 例如，如果注释处理器尝试创建源文件GeneratedFromUserSource以响应处理 

      @Generate  public class UserSource {}
    UserSource的type元素应作为创建方法调用的一部分传递，如： 
          filer.createSourceFile("GeneratedFromUserSource",                             eltUtils.getTypeElement("UserSource"));
    如果没有原始元素，则不需要传递任何元素。 此信息可用于增量环境，以确定是否需要重新运行处理器或删除生成的文件。 非增量环境可能会忽略原始元素信息。

    在每次运行注释处理工具期间，可以仅创建具有给定路径名的文件一次。 如果该文件在首次尝试创建之前已存在，则将删除旧内容。 在运行期间创建相同文件的任何后续尝试都将抛出FilerException ，同时尝试为同一类型名称或相同包名创建类文件和源文件。 该工具的initial inputs被认为是由第0轮创建的; 因此，尝试创建与其中一个输入相对应的源文件或类文件将导致FilerException 。

    通常，处理器不得故意尝试覆盖某些处理器未生成的现有文件。 Filer可能会拒绝尝试打开与现有类型相对应的文件，如java.lang.Object 。 同样，注释处理工具的调用者不得故意配置该工具，以便发现的处理器将尝试覆盖未生成的现有文件。

    如果配置了环境以便可以访问该类型，则处理器可以通过包含javax.annotation.Generated注释来指示生成源文件或类文件。

    API Note:
    通过使用装饰器风格的模式可以实现覆盖文件的一些效果。 不是直接修改类，而是设计类以使其超类由注释处理生成，或者类的子类由注释处理生成。 如果生成了子类，则可以将父类设计为使用工厂而不是公共构造函数，以便只将子类实例呈现给父类的客户端。
    从以下版本开始：
    1.6

    • 方法详细信息

      • createSourceFile

        JavaFileObject createSourceFile​(CharSequence name,                                Element... originatingElements)                         throws IOException
        创建一个新的源文件并返回一个对象以允许写入它。 可以创建类型或包的源文件。 文件的名称和路径（相对于root output location for source files ）基于要在该文件中声明的项目的名称以及项目的指定模块（如果有）。 如果在单个文件（即单个编译单元）中声明了多个类型，则文件名应对应于主要顶级类型的名称（例如，公共名称）。

        还可以创建源文件以保存有关包的信息，包括包注释。 要为命名包创建源文件，请将name参数作为包的名称，后跟".package-info" ; 要为未命名的包创建源文件，请使用"package-info" 。

        可选模块名称以类型名称或包名称为前缀，并使用“ / ”字符分隔。 例如，要在模块foo为类型a.B创建源文件，请使用name参数"foo/a.B" 。

        如果没有给出显式模块前缀并且环境中支持模块，则推断出合适的模块。 如果无法推断出合适的模块，则抛出FilerException 。 实现可以使用关于注释处理工具的配置的信息作为推断的一部分。

        不支持在命名模块中或为命名模块中的未命名包创建源文件。

        API Note:
        使用特定charset来编码文件的内容，一个OutputStreamWriter与所选择的字符集可以从所创建的OutputStream从返回的对象。 如果返回的对象中的Writer直接用于写入，则其字符集由实现确定。 注释处理工具可以具有-encoding标志或用于指定此标志的类似选项; 否则，它通常是平台的默认编码。

        为避免后续错误，源文件的内容应与此次运行使用的source version兼容。

        Implementation Note:
        在参考实现中，如果注释处理工具正在处理单个模块M ，则M被用作在没有显式模块前缀的情况下创建的文件的模块。 如果该工具正在处理多个模块，并且Elements.getPackageElement(package-of(name))返回一个包，则拥有返回包的模块将用作目标模块。 如果使用上述规则无法确定目标模块，则可以使用单独的选项。
        参数
        name - 在此文件中声明的主体类型的规范（完全限定）名称或包名称，后跟包含信息文件的 ".package-info"
        originatingElements - 与此文件的创建有因果关联的类型或包或模块元素可能被省略或 null
        结果
        一个 JavaFileObject写入新的源文件
        异常
        FilerException - 如果已创建相同的路径名，则已创建相同的类型，否则该名称对于请求创建的实体无效，如果无法确定目标模块，目标模块是否可写，或者当环境不支持模块时指定模块。
        IOException - 如果无法创建文件
        See The Java™ Language Specification:
        7.3编译单位

      • createClassFile

        JavaFileObject createClassFile​(CharSequence name,                               Element... originatingElements)                        throws IOException
        创建一个新的类文件，并返回一个允许写入它的对象。 可以创建类型或包的类文件。 文件的名称和路径（相对于root output location for class files ）基于要声明的项目的名称以及项目的指定模块（如果有）。

        还可以创建类文件来保存有关包的信息，包括包注释。 要为命名包创建类文件，请将name参数作为包的名称，后跟".package-info" ; 不支持为未命名的包创建类文件。

        可选模块名称以类型名称或包名称为前缀，并使用“ / ”字符分隔。 例如，要在模块foo为类型a.B创建类文件，请使用name参数"foo/a.B" 。

        如果没有给出显式模块前缀并且环境中支持模块，则推断出合适的模块。 如果无法推断出合适的模块，则抛出FilerException 。 实现可以使用关于注释处理工具的配置的信息作为推断的一部分。

        不支持在命名模块中为未命名的包创建类文件。

        API Note:
        为避免后续错误，类文件的内容应与此运行使用的 source version兼容。
        Implementation Note:
        在参考实现中，如果注释处理工具正在处理单个模块M ，则M被用作在没有显式模块前缀的情况下创建的文件的模块。 如果该工具正在处理多个模块，并且Elements.getPackageElement(package-of(name))返回一个包，则拥有返回包的模块将用作目标模块。 如果使用上述规则无法确定目标模块，则可以使用单独的选项。
        参数
        name - 正在写入的类型的二进制名称或包名称，后跟包含信息文件的 ".package-info"
        originatingElements - 与此文件的创建有因果关联的类型或包或模块元素可能被省略或 null
        结果
        一个 JavaFileObject写入新的类文件
        异常
        FilerException - 如果已创建相同的路径名，则已创建相同的类型，名称对于类型无效，如果无法确定目标模块，目标模块是否不可写，或者何时指定了模块环境不支持模块。
        IOException - 如果无法创建文件

      • createResource

        FileObject createResource​(JavaFileManager.Location location,                          CharSequence moduleAndPkg,                          CharSequence relativeName,                          Element... originatingElements)                   throws IOException
        创建用于写入的新辅助资源文件，并为其返回文件对象。 该文件可以与新创建的源文件，新创建的二进制文件或其他支持的位置一起定位。 必须支持位置CLASS_OUTPUT和SOURCE_OUTPUT 。 资源可以相对于某个模块和/或包（如源文件和类文件）命名，并从那里通过相对路径名来命名。 在宽松的意义上说，新文件的全名是串接location ， moduleAndPkg和relativeName 。 如果moduleAndPkg包含一个“ / ”字样，“前的前缀/ ”字就是模块名与“后的后缀/ ”字是软件包的名称。 包后缀可能为空。 如果moduleAndPkg不包含“ / ”字符，则整个参数将被解释为包名称。

        如果给定位置既不是module oriented location ，也不是output location containing multiple modules ，并且给出了显式模块前缀，则抛出FilerException 。

        如果给定位置是面向模块的位置，或者是包含多个模块的输出位置，并且没有给出显式模块前缀，则推断出合适的模块。 如果无法推断出合适的模块，则抛出FilerException 。 实现可以使用关于注释处理工具的配置的信息作为推断的一部分。

        通过此方法创建的文件不会注册用于注释处理，即使文件的完整路径名对应于新源文件或新类文件的完整路径名也是如此。

        Implementation Note:
        在参考实现中，如果注释处理工具正在处理单个模块M ，则M被用作在没有显式模块前缀的情况下创建的文件的模块。 如果该工具正在处理多个模块，并且Elements.getPackageElement(package-of(name))返回一个包，则拥有返回包的模块将用作目标模块。 如果使用上述规则无法确定目标模块，则可以使用单独的选项。
        参数
        location - 新文件的位置
        moduleAndPkg - 应该命名文件的模块和/或包，如果没有，则为空字符串
        relativeName - 文件的最终路径名组件
        originatingElements - 与此文件的创建因果关联的类型或包或模块元素可能被省略或 null
        结果
        一个 FileObject来编写新资源
        异常
        IOException - 如果无法创建文件
        FilerException - 如果已创建相同的路径名，如果无法确定目标模块，或者目标模块不可写，或者指定了显式目标模块且该位置不支持它。
        IllegalArgumentException - 对于不受支持的位置
        IllegalArgumentException - 如果 moduleAndPkg
        IllegalArgumentException - 如果 relativeName不是相对的

      • getResource

        FileObject getResource​(JavaFileManager.Location location,                       CharSequence moduleAndPkg,                       CharSequence relativeName)                throws IOException
        返回用于读取现有资源的对象。 必须支持位置CLASS_OUTPUT和SOURCE_OUTPUT 。

        如果moduleAndPkg包含一个“ / ”字样，“前的前缀/ ”字就是模块名与“后的后缀/ ”字是软件包的名称。 包后缀可能为空; 但是，如果存在模块名称，则它必须是非空的。 如果moduleAndPkg不包含“ / ”字符，则整个参数将被解释为包名称。

        如果给定位置既不是module oriented location ，也不是output location containing multiple modules ，并且给出了显式模块前缀，则抛出FilerException 。

        如果给定位置是面向模块的位置，或者是包含多个模块的输出位置，并且没有给出显式模块前缀，则推断出合适的模块。 如果无法推断出合适的模块，则抛出FilerException 。 实现可以使用关于注释处理工具的配置的信息作为推断的一部分。

        Implementation Note:
        在参考实现中，如果注释处理工具正在处理单个模块M ，则M被用作用于在没有显式模块前缀的情况下读取的文件的模块。 如果该工具正在处理多个模块，并且Elements.getPackageElement(package-of(name))返回一个包，则拥有返回包的模块将用作源模块。 如果使用上述规则无法确定目标模块，则可以使用单独的选项。
        参数
        location - 文件的位置
        moduleAndPkg - 应搜索文件的模块和/或包，如果没有，则为空字符串
        relativeName - 文件的最终路径名组件
        结果
        一个读取文件的对象
        异常
        FilerException - 如果已经打开了相同的路径名进行写入，如果无法确定源模块，或者目标模块不可写，或者指定了显式目标模块且该位置不支持它。
        IOException - 如果无法打开文件
        IllegalArgumentException - 对于不受支持的位置
        IllegalArgumentException - 如果 moduleAndPkg
        IllegalArgumentException - 如果 relativeName不是相对的