javax.tools
接口 JavaFileManager

所有超级接口：

Closeable, Flushable, OptionChecker

所有已知子接口：

StandardJavaFileManager

所有已知实现类：

ForwardingJavaFileManager

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

在 Java™ 编程语言源和类文件之上进行操作的工具的文件管理器。在这里，文件 是指常规文件和其他数据源的抽象。

构建新的 JavaFileObject 时，文件管理器必须确定创建它们的位置。例如，如果文件管理器在文件系统上管理常规文件，那么在创建或查找文件时，此文件管理器很可能将当前/工作目录作为默认位置使用。可以向文件管理器提供许多关于在何处创建文件的提示。文件管理器可以选择忽略这些提示。

此接口中的某些方法使用类名称。这种类名称必须以完全限定类和接口名称的 Java Virtual Machine 内部形式给定。为了方便起见，'.' 和 '/' 可以互换使用。在 Java Virtual Machine Specification 第四章中定义了内部形式。

讨论：这意味着名称 "java/lang.package-info"、"java/lang/package-info"、"java.lang.package-info" 有效并且相等。比较 Java Language Specification (JLS) 第 13.1 节 "The Form of a Binary" 中定义的二进制名称。

名称的大小写很重要。所有名称都应该区分大小写。例如，某些文件系统的文件名称大小写不敏感 (case-insensitive)、但可区分大小写 (case-aware)。表示此类文件的文件对象应该通过使用 File.getCanonicalFile() 或类似方法来保存大小写形式。如果系统不可区分大小写，那么文件对象必须使用其他方法来保存大小写。

相对名称：此接口中的某些方法使用相对名称。相对名称是指用 '/' 分隔的路径段的非 null、非空序列。'.' 或 '..' 为无效路径段。有效的相对名称必须符合 RFC 3986 的第 3.3 节的“无根路径”规则。非正式情况下，下式应该为 true：

  URI.create(relativeName).normalize().getPath().equals(relativeName)

此接口中的所有方法都可能抛出 SecurityException。

不要求此接口的对象支持多线程访问，也就是说，此接口中的对象是同步的。但是，它必须支持对此对象创建的不同文件对象的并发访问。

实现注意事项： 此要求使得对 JarOutputStream 的输出的普通实现将不够充分。也就是说，不是创建直接返回 JarOutputStream 的 JavaFileObject，而是在关闭前必须缓存内容，然后将内容写入 JarOutputStream。

除非明确允许，否则只要给定 null 参数，此接口中的所有方法都将抛出 NullPointerException。

从以下版本开始：

1.6

另请参见：

JavaFileObject, FileObject

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

获取可从给定位置加载插件的类加载器。例如，要加载注释处理器，编译器将请求 ANNOTATION_PROCESSOR_PATH 位置的类加载器。

参数：

location - 位置

返回：

给定位置的类加载器；如果不能从给定位置加载插件或位置未知，则返回 null

抛出：

SecurityException - 如果在当前安全上下文中不能创建类加载器

IllegalStateException - 如果已经调用了 close() 并且不能重新打开此文件管理器

list

Iterable<JavaFileObject> list(JavaFileManager.Location location,
                              String packageName,
                              Set<JavaFileObject.Kind> kinds,
                              boolean recurse)
                              throws IOException

列出给定位置处符合给定标准的所有文件对象。如果 recurse 为 true，则列出“子包”中的文件对象。

注：即使给定位置对于此文件管理器是未知的，此方法也不会返回 null。未知位置也不会导致异常。

参数：

location - 位置

packageName - 包名称

kinds - 只返回这些类型的对象

recurse - 如果为 true，则包含“子包”

返回：

符合给定标准的文件对象的 Iterable

抛出：

IOException - 如果发生 I/O 错误，或者已经调用了 close() 并且无法重新打开此文件管理器

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)

根据位置推断文件对象的二进制名称。返回的二进制名称可能不是有效的 JLS 二进制名称。

参数：

location - 位置

file - 文件对象

返回：

二进制名称；如果在给定位置没有找到文件对象，则返回 null

抛出：

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)

比较两个文件对象，如果它们表示相同的底层对象，则返回 true。

参数：

a - 文件对象

b - 文件对象

返回：

如果给定的文件对象表示相同的底层对象，则返回 true

抛出：

IllegalArgumentException - 如果其中一个参数是用另一个文件管理器创建的，并且此文件管理器不支持外部文件对象

handleOption

boolean handleOption(String current,
                     Iterator<String> remaining)

处理一个选项。如果 current 是此文件管理器的一个选项，则它将通过 remaining 获得该选项的所有参数并返回 true，否则返回 false。

参数：

current - 当前选项

remaining - 剩余选项

返回：

如果由此文件管理器处理此选项，则返回 true，否则返回 false

抛出：

IllegalArgumentException - 如果错误地使用了此文件管理器的选项

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

hasLocation

boolean hasLocation(JavaFileManager.Location location)

确定此文件管理器是否已知某位置。

参数：

location - 位置

返回：

如果已知该位置，则返回 true

getJavaFileForInput

JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                   String className,
                                   JavaFileObject.Kind kind)
                                   throws IOException

获取输入的文件对象，它表示给定位置处指定类型的指定类。

参数：

location - 位置

className - 类的名称

kind - 文件的类型，必须是 SOURCE 或 CLASS

返回：

一个文件对象；如果文件不存在，则可能返回 null

抛出：

IllegalArgumentException - 如果位置对于此文件管理器未知并且该文件管理器不支持未知位置，或者类型无效

IOException - 如果发生 I/O 错误，或者已经调用了 close() 并且无法重新打开此文件管理器

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

getJavaFileForOutput

JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                    String className,
                                    JavaFileObject.Kind kind,
                                    FileObject sibling)
                                    throws IOException

获取输出的文件对象，它表示给定位置处指定类型的指定类。

此文件管理器可以将 sibling 视为对放置输出位置的提示（可选）。没有指定此提示的确切语义。除非提供了类文件输出目录，否则 Sun 的编译器（例如 javac）将把类文件放到与原始源文件相同的目录下。要实现此行为，调用此方法时 javac 可以提供原始源文件作为 sibling。

参数：

location - 位置

className - 类的名称

kind - 文件的类型，必须是 SOURCE 或 CLASS

sibling - 用作位置提示的文件对象，可以为 null

返回：

输出的文件对象

抛出：

IllegalArgumentException - 如果 sibling 对于此文件管理器是未知的，或者位置对于此文件管理器是未知的并且该文件管理器不支持未知位置，或者类型无效

IOException - 如果发生 I/O 错误，或者已经调用了 close() 并且无法重新打开此文件管理器

IllegalStateException - 已经调用了 close() 并且无法重新打开此文件管理器

getFileForInput

FileObject getFileForInput(JavaFileManager.Location location,
                           String packageName,
                           String relativeName)
                           throws IOException

获取输入的文件对象，它表示给定位置处指定包中的指定相对名称。

如果返回的对象表示源或类文件，则它必须是 JavaFileObject 的一个实例。

非严格意义上来讲，在位置、包名称和相对名称的串联中查找此方法返回的文件对象。例如，要在 SOURCE_PATH 位置处的 "com.sun.tools.javac" 包中查找属性文件 "resources/compiler.properties"，将调用此方法，如下：

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

如果在 Windows 上执行该调用，其中 SOURCE_PATH 设置为 "C:\Documents and Settings\UncleBob\src\share\classes"，那么有效的结果将是表示文件 "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties" 的文件对象。

参数：

location - 位置

packageName - 包名称

relativeName - 相对名称

返回：

文件对象；如果文件不存在，则可能返回 null

抛出：

IllegalArgumentException - 如果位置对于此文件管理器是未知的并且该文件管理器不支持未知位置，或者 relativeName 无效

IOException - 如果发生 I/O 错误，或者已经调用了 close() 并且无法重新打开此文件管理器

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

getFileForOutput

FileObject getFileForOutput(JavaFileManager.Location location,
                            String packageName,
                            String relativeName,
                            FileObject sibling)
                            throws IOException

获取输出的文件对象，它表示给定位置处指定包中的指定相对名称。

此文件管理器可能将 sibling 视为对放置输出位置的提示（可选）。没有指定此提示的确切语义。除非提供了类文件输出目录，否则 Sun 的编译器（例如 javac）将把类文件放到与原始源文件相同的目录下。要实现此行为，调用此方法时 javac 可以提供原始源文件作为 sibling。

如果返回的对象表示源或类文件，则它必须是 JavaFileObject 的一个实例。

非正式情况下，在位置、包名称和相对名称的串联或 sibling 参数的同级元素中查找此方法返回的文件对象。有关示例，请参阅 getFileForInput。

参数：

location - 位置

packageName - 包名称

relativeName - 相对名称

sibling - 用作位置提示的文件对象；可以为 null

返回：

文件对象

抛出：

IllegalArgumentException - 如果 sibling 对于此文件管理器是未知的，或者位置对于此文件管理器是未知的并且该文件管理器不支持未知位置，或者 relativeName 无效

IOException - 如果发生 I/O 错误，或者已经调用了 close() 并且无法重新打开此文件管理器

IllegalStateException - 如果已经调用了 close() 并且无法重新打开此文件管理器

flush

void flush()
           throws IOException

刷新此文件管理器直接或间接为输出打开的所有资源。刷新已关闭的文件管理器没有任何效果。

指定者：

接口 Flushable 中的 flush

抛出：

IOException - 如果发生 I/O 错误

另请参见：

close()

close

void close()
           throws IOException

释放此文件管理器直接或间接打开的所有资源。这会使得此文件管理器无效，除非明确允许，否则对此对象上的方法或通过此对象获取的所有对象进行后续调用都将导致不确定的结果。但是，关闭已经关闭的文件管理器没有任何效果。

指定者：

接口 Closeable 中的 close

抛出：

IOException - 如果发生 I/O 错误

另请参见：

flush()

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。