javax.annotation.processing
接口 Filer

public interface Filer

此接口支持通过注释处理器创建新文件。以这种方式创建的文件对于实现此接口的注释处理工具将是已知的，这比启用工具来管理它们更好。在对用来编写文件内容的 Writer 或 OutputStream 调用 close 方法之后，以这种方式创建的源文件和类文件被认为将由管理它们的工具处理。有三类文件要加以区分：源文件、类文件和辅助资源文件。

新创建的文件被放置在两个不同的受支持位置（逻辑文件系统中的子树）：一个用于新的源文件，一个用于新的类文件。（这可以在工具的命令行上指定，例如，使用 -s 和 -d 之类的标志。）新的源文件和类文件的实际位置在工具的特定运行时刻可能是不同的，也可能是相同的。资源文件可以在其中一个位置上创建。用来读取和写入资源的方法采用了一个相对名称参数。相对名称是用 '/' 分隔的、非 null、非空的路径段序列；'.' 和 '..' 都是无效的路径段。有效的相对名称必须符合 RFC 3986 的第 3.3 节的“无根路径”规则。

文件创建方法带有可变数量的参数，以允许提供原始元素 作为工具基础设施的提示，从而更好地管理依赖关系。原始元素是造成注释处理器试图创建新文件的类型或包（表示 package-info 文件）。例如，如果注释处理器试图创建一个源文件 GeneratedFromUserSource 以响应处理

@Generate
public class UserSource {}
 

那么 UserSource 的类型元素应该作为创建方法调用的一部分传入，如下所示：

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

如果没有原始元素，则什么都不需要传递。此信息可以在增量环境中使用，以确定是需要重新运行处理器还是移除生成的文件。非增量环境可以忽略原始元素信息。

在每次运行注释处理工具期间，具有给定路径名的文件只能被创建一次。如果该文件在第一次试图创建它之前就已经存在，则将删除原有的内容。在运行期间，任何试图创建相同文件的后续尝试都将抛出 FilerException，试图针对相同的类型名称和相同的包名称创建类文件和源文件也将如此。工具的初始输入被认为是由第 0 个 round 创建的；因此，试图创建一个与那些输入之一对应的源文件或类文件将导致 FilerException。

通常，处理器不得有意尝试重写不是由某个处理器生成的现有文件。Filer 可能拒绝尝试打开与现有类型对应的文件，如 java.lang.Object。同样，注释处理工具的调用者不得有意配置该工具，使得已发现的处理器将尝试重写尚未生成的现有文件。

处理器可以通过包含 @Generated 注释来指示生成源文件或类文件。

注意，重写文件的某些效果可通过使用装饰 风格模式来实现。类被设计为其超类由注释处理生成，或者其子类由注释处理生成，而不是直接修改该类。如果生成子类，则父类可以被设计为使用工厂而不是公共构造方法，这样只有子类实例被呈现给父类的客户端。

从以下版本开始：

1.6

方法摘要

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

创建一个新的源文件，并返回一个对象以允许写入它。文件的名称和路径（相对于 源文件的根目录输出位置）基于该文件中声明的类型。如果声明的类型不止一个，则应该使用主要顶层类型的名称（例如，声明为 public 的那个）。还可以创建源文件来保存有关某个包的信息，包括包注释。要为指定包创建源文件，可以用 name 作为包名称，后跟 ".package-info"；要为未指定的包创建源文件，可以使用 "package-info"。

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

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

参数：

name - 将在此文件中声明的主要类型的规范（完全限定）名称；对于包信息文件，则是后跟 ".package-info" 的包名称

originatingElements - 与此文件的创建有因果关联的类型或包元素，该参数可以省略或者为 null

返回：

写入新源文件的 JavaFileObject

抛出：

FilerException - 如果创建了相同的路径名，创建了相同的类型，或者名称对于某一类型无效

IOException - 如果无法创建文件

createClassFile

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

创建一个新的类文件，并返回一个对象以允许写入它。文件的名称和路径（相对于 类文件的根目录输出位置）基于将写入的类型名称。还可以创建类文件来保存有关某个包的信息，包括包注释。要为指定包创建类文件，可以用 name 作为包名称，后跟 ".package-info"；为未指定的包创建类文件不受支持。

为了避免后续错误，类文件的内容应该与将用于此运行的源版本兼容。

参数：

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 - 如果 relativeName 不是相对名称