Module  java.compiler
软件包  javax.annotation.processing

Interface Filer


  • public interface Filer
    该接口支持通过注释处理器创建新文件。 以这种方式创建的文件将通过实现此界面的注释处理工具知道，更好地使工具能够管理它们。 这样创建的源和类文件将由27072964482488的工具在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的类型元素应作为创建方法调用的一部分传递，如： 
          filer.createSourceFile("GeneratedFromUserSource",
                             eltUtils.getTypeElement("UserSource"));
    如果没有原始元素，则不需要通过。 该信息可以在增量环境中使用，以确定需要重新运行处理器或删除生成的文件。 非增量环境可以忽略始发元素信息。

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

    一般来说，处理器不得有意试图覆盖某些处理器未生成的现有文件。 A 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" 。

        可选模块名称前缀为类型名称或包名称，并使用“ / ”字符分隔。 例如，为了创建用于类型源文件a.B在模块foo ，使用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是 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是 moduleAndPkg
        IllegalArgumentException - 如果 relativeName不是相对的