compact3

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文件）。 例如，如果注释处理器尝试创建源文件（ GeneratedFromUserSource ，以响应处理

  @Generate
  public class UserSource {}
 

UserSource的类型元素应作为创建方法调用的一部分传递，如：

      filer.createSourceFile("GeneratedFromUserSource",
                             eltUtils.getTypeElement("UserSource"));
 

如果没有原始元素，则不需要通过。 该信息可以在增量环境中使用，以确定需要重新运行处理器或删除生成的文件。 非增量环境可以忽略始发元素信息。

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

一般来说，处理器不得有意试图覆盖某些处理器未生成的现有文件。 A Filer可能会拒绝尝试打开与现有类型相对应的文件，如java.lang.Object 。 同样，注释处理工具的调用者也不得故意地配置工具，使得发现的处理器将尝试覆盖未生成的现有文件。

处理器可以指示由包括所产生的源或类文件@Generated注释。

请注意，可以通过使用装饰器样式来实现覆盖文件的一些效果。 不是直接修改类，而是设计类，以便通过注释处理生成其超类，或者通过注释处理生成类的子类。 如果生成子类，则可以将父类设计为使用工厂而不是公共构造函数，以便仅将子类实例提供给父类的客户端。

从以下版本开始：

1.6

方法摘要

Modifier and Type	Method and Description
JavaFileObject	createClassFile(CharSequence name, Element... originatingElements) 创建一个新的类文件，并返回一个对象以允许写入它。
FileObject	createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) 创建一个新的辅助资源文件进行写入并返回一个文件对象。
JavaFileObject	createSourceFile(CharSequence name, Element... originatingElements) 创建一个新的源文件并返回一个对象以允许写入它。
FileObject	getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) 返回一个读取现有资源的对象。

方法详细信息

createSourceFile

JavaFileObject createSourceFile(CharSequence name,
                                Element... originatingElements)
                         throws IOException

创建一个新的源文件并返回一个对象以允许写入它。 文件的名称和路径（相对于root output location for source files ）基于要在该文件中声明的类型。 如果声明了多个类型，则应使用主体顶级类型（例如公共类型）的名称。 还可以创建源文件来保存有关包的信息，包括包注释。 要创建一个命名包的源文件， name是包的名称，后跟".package-info" ; 要创建一个未命名的包的源文件，请使用"package-info" 。

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

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

参数

name - 在此文件中声明的主体类型的规范（完全限定）名称或包信息文件后跟 ".package-info"的包名称

originatingElements - 与此文件创建有关的类型或包元素可能会被删除或 null

结果

一个 JavaFileObject写新的源文件

异常

FilerException - 如果已经创建了相同的路径名，则已经创建了相同的类型，或者该名称对于类型无效

IOException - 如果无法创建文件

createClassFile

JavaFileObject createClassFile(CharSequence name,
                               Element... originatingElements)
                        throws IOException

创建一个新的类文件，并返回一个对象以允许写入它。 文件的名称和路径（相对于root output location for class files ）基于正在写入的类型的名称。 也可以创建一个类文件来保存有关包的信息，包括包注释。 要创建一个命名包的类文件， name是包的名称后跟".package-info" ; 不支持为未命名的包创建类文件。

为了避免后续的错误，类文件的内容应与用于此运行的source version兼容 。

参数

name - 要编写的类型的二进制名称或包信息文件后跟 ".package-info"的包名称

originatingElements - 与此文件创建有关的类型或包元素可能会被删除或 null

结果

一个 JavaFileObject写新的类文件

异常

FilerException - 如果已经创建了相同的路径名，则已经创建了相同的类型，或者该名称对于类型无效

IOException - 如果无法创建文件

createResource

FileObject createResource(JavaFileManager.Location location,
                          CharSequence pkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                   throws IOException

创建一个新的辅助资源文件进行写入并返回一个文件对象。 该文件可能与新创建的源文件，新创建的二进制文件或其他支持的位置一起定位。 该位置CLASS_OUTPUT和SOURCE_OUTPUT必须得到支持。 该资源可能相对于某些包（源和类文件）以及相对路径名来命名。 在宽松的意义上说，新文件的全名是串接location ， pkg和relativeName 。

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

参数

location - 新文件的位置

pkg - 相对于该文件应该命名的包，或空字符串（如果没有）

relativeName - 文件的最终路径名组件

originatingElements - 与此文件创建有关的类型或包元素可能会被删除或 null

结果

一个 FileObject写新的资源

异常

IOException - 如果无法创建该文件

FilerException - 如果已经创建了相同的路径名

IllegalArgumentException - 对于不受支持的位置

IllegalArgumentException - 如果 relativeName不是相对的

getResource

FileObject getResource(JavaFileManager.Location location,
                       CharSequence pkg,
                       CharSequence relativeName)
                throws IOException

返回一个读取现有资源的对象。 该位置CLASS_OUTPUT和SOURCE_OUTPUT必须得到支持。

参数

location - 文件的位置

pkg - 应该搜索文件的包，或者没有空字符串

relativeName - 文件的最终路径名组件

结果

一个读取文件的对象

异常

FilerException - 如果相同的路径名已经被打开来写入

IOException - 如果文件无法打开

IllegalArgumentException - 对于不受支持的位置

IllegalArgumentException - if relativeName is not relative