compact3

javax.annotation.processing

Interface Filer

public interface Filer

此接口支持通过注释处理器创建新文件。以这种方式创建的文件将被称为实现此接口的注释处理工具，从而更好地实现了管理它们的工具。源文件和类文件创建后，将 close方法被调用用来写文件的内容 OutputStream Writer或在以后的 round of processing由工具 considered for processing。三种文件类型：源文件、类文件和辅助资源文件。

有两个支撑位置（逻辑文件系统内的子树）在新创建的文件是放在：一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。

在一般情况下，处理器不能故意试图覆盖没有由一些处理器产生的现有文件。一个Filer可能拒绝尝试打开对应的现有类型、文件java.lang.Object。同样，注释的处理工具者不得有意配置工具，发现处理器将覆盖现有的文件，不生成。

处理器可以显示源代码或类文件包括@Generated注释生成。

注意有些改写文件可以通过使用一个装饰式模式取得的效果。而不是修改一个类，类的设计是这样的，无论是它的父类的子类的类注释处理或产生的标注处理产生。如果生成子类，父类可以被设计为使用工厂而不是公共构造函数，这样只有子类的实例将提交给父类的客户端。

从以下版本开始：

一点六

方法摘要

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