JavaFileManager (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
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
| 嵌套类摘要 | |
|---|---|
static interface |
JavaFileManager.Location
文件对象位置的接口。 |
| 从接口 javax.tools.OptionChecker 继承的方法 |
|---|
isSupportedOption |
| 方法详细信息 |
|---|
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或CLASSsibling- 用作位置提示的文件对象，可以为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
- 刷新此文件管理器直接或间接为输出打开的所有资源。刷新已关闭的文件管理器没有任何效果。
- 抛出：
IOException- 如果发生 I/O 错误- 另请参见：
close()
close
void close()
throws IOException
- 释放此文件管理器直接或间接打开的所有资源。这会使得此文件管理器无效，除非明确允许，否则对此对象上的方法或通过此对象获取的所有对象进行后续调用都将导致不确定的结果。但是，关闭已经关闭的文件管理器没有任何效果。
- 抛出：
IOException- 如果发生 I/O 错误- 另请参见：
flush()
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。
版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。