Module java.compiler

软件包 javax.tools

Interface JavaFileManager

All Superinterfaces:

AutoCloseable ， Closeable ， Flushable ， OptionChecker

All Known Subinterfaces:

StandardJavaFileManager

所有已知实现类：

ForwardingJavaFileManager

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

用于Java编程语言源和类文件的工具的文件管理器。 在这种情况下， 文件意味着抽象普通文件和其他数据源。

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

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

Discussion: this means that the names "java/lang.package-info", "java/lang/package-info", "java.lang.package-info", are valid and equivalent. Compare to binary name as defined in The Java™ Language Specification, section 13.1 "The Form of a Binary".

姓名的情况很重要。 所有名称应视为区分大小写。 例如，某些文件系统具有不区分大小写，区分大小写的文件名。 表示这些文件的文件对象应该注意使用File.getCanonicalFile()或类似的方法来保护大小写。 如果系统不区分大小写，文件对象必须使用其他方式来保护大小写。

Relative names ：这个接口中的一些方法使用相对名称。 相对名称是以“/”分隔的路径段的非空，非空序列。 '' 或'..'是无效的路径段。 有效的相对名称必须与“无路径”规则RFC 3986第3.3节匹配。 非正式地，这应该是真的：

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

此接口中的所有方法可能会抛出SecurityException异常。

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

实施说明：这个要求的结果是，输出到JarOutputStream的一个微不足道的实现不是一个充分的实现。 也就是说，而不是直接创建返回JarOutputStream的JavaFileObject，内容必须缓存直到关闭，然后写入JarOutputStream。

除非明确允许，如果给定一个null参数，则该接口中的所有方法都可能会抛出NullPointerException null 。

从以下版本开始：

1.6

另请参见：

JavaFileObject ， FileObject

Nested Class Summary

Nested Classes

Modifier and Type	接口	描述
static interface	JavaFileManager.Location	文件对象的位置接口。

方法摘要

Modifier and Type	方法	描述
void	close()	释放此文件管理器直接或间接打开的任何资源。
default boolean	contains(JavaFileManager.Location location, FileObject fo)	确定给定的文件对象是否“包含在”指定的位置。
void	flush()	刷新此文件管理器直接或间接打开输出的任何资源。
ClassLoader	getClassLoader(JavaFileManager.Location location)	返回一个类加载器，用于从给定的面向包的位置加载插件。
FileObject	getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)	返回file object用于表示指定的输入relative name中指定的包在给定的取向包位置。
FileObject	getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)	返回file object用于表示指定的输出relative name中指定的包在给定的位置。
JavaFileObject	getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)	返回一个file object，用于在给定的面向包的位置中表示指定类型的指定类的输入。
JavaFileObject	getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)	返回一个file object，用于表示给定面向对象的位置中指定类型的指定类的输出。
default JavaFileManager.Location	getLocationForModule(JavaFileManager.Location location, String moduleName)	在位置中获取命名模块的位置，该位置可以是面向模块的位置或输出位置。
default JavaFileManager.Location	getLocationForModule(JavaFileManager.Location location, JavaFileObject fo)	获取包含要在一个位置找到的特定文件的模块的位置，该位置可以是面向模块的位置或输出位置。
default <S> ServiceLoader<S>	getServiceLoader(JavaFileManager.Location location, Class<S> service)	从给定位置获取特定服务类的服务加载程序。
boolean	handleOption(String current, Iterator<String> remaining)	处理一个选项
boolean	hasLocation(JavaFileManager.Location location)	确定此文件管理器是否已知位置。
String	inferBinaryName(JavaFileManager.Location location, JavaFileObject file)	基于面向包的位置来触发文件对象的二进制名称。
default String	inferModuleName(JavaFileManager.Location location)	从 getLocationForModule或 listModuleLocations返回，从其位置输入模块的名称。
boolean	isSameFile(FileObject a, FileObject b)	比较两个文件对象，如果它们代表相同的底层对象，则返回true。
Iterable<JavaFileObject>	list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)	列出与给定的面向对象位置匹配的所有文件对象。
default Iterable<Set<JavaFileManager.Location>>	listLocationsForModules(JavaFileManager.Location location)	列出面向模块的位置或输出位置中所有模块的位置。

Methods inherited from interface javax.tools.OptionChecker

isSupportedOption

方法详细信息

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

返回一个类加载器，用于从给定的面向包的位置加载插件。 例如，要加载注解处理器，编译器将请求ANNOTATION_PROCESSOR_PATH位置的类加载器。

参数

location - 一个位置

结果

给定位置的类加载器; 或null如果从给定位置加载插件已禁用或位置未知

异常

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

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

IllegalArgumentException - 如果位置是面向模块的位置

list

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

列出与给定的面向对象位置匹配的所有文件对象。 如果recurse为真，则在“子包”中列出文件对象。

注意：即使给定的位置对于该文件管理器是未知的，也可能不会返回null 。 而且，未知的位置可能不会引起异常。

参数

location - 一个位置

packageName - 一个包名

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

recurse - 如果真的包括“子包”

结果

符合给定条件的文件对象的迭代

异常

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

IllegalArgumentException - 如果位置是面向模块的位置

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

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)

基于面向包的位置来触发文件对象的二进制名称。 根据The Java™ Language Specification，返回的二进制名称可能不是有效的二进制名称。

参数

location - 一个位置

file - 一个文件对象

结果

二进制名称或 null在给定位置找不到文件对象

异常

IllegalArgumentException - 如果位置是面向模块的位置

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

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)

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

参数

a - 一个文件对象

b - 一个文件对象

结果

如果给定的文件对象代表相同的底层对象，则为true

异常

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

handleOption

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

处理一个选项 如果current是该文件管理器的选项， remaining从remaining使用该选项的任何参数，并返回true，否则返回false。

参数

current - 当前选项

remaining - 剩余选项

结果

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

异常

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

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

hasLocation

boolean hasLocation(JavaFileManager.Location location)

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

参数

location - 一个位置

结果

如果位置已知，则为真

getJavaFileForInput

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

返回一个file object，用于在给定的面向包的位置中表示指定类型的指定类的输入。

参数

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

返回一个file object，用于在给定的面向对象的位置中表示指定类型的指定类的输出。

可选地，该文件管理器可以将兄弟姐妹视为提示放置输出的位置。 这个提示的确切语义是未指定的。 例如，JDK编译器javac将将类文件放置在与源文件源相同的目录中，除非提供了一个类文件输出目录。 为了方便这种行为，javac可以在调用此方法时将起始源文件提供为兄弟。

参数

location - 面向包的位置

className - 一个类的名字

kind - 文件的种类，必须是 SOURCE或 CLASS之一

sibling - 用作放置提示的文件对象; 可能是null

结果

用于输出的文件对象

异常

IllegalArgumentException - 如果此文件管理器不知道同级，或者该文件管理器不知道该位置，并且文件管理器不支持未知位置，或者该类型无效，或者该位置不是输出位置

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

IllegalStateException - close()已被调用，此文件管理器无法重新打开

getFileForInput

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

返回file object用于表示指定的输入relative name中指定的包在给定的取向包位置。

如果返回的对象表示一个source或class文件，则它必须是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

返回file object用于表示指定的输出relative name中指定的包在给定的位置。

可选地，该文件管理器可以将兄弟姐妹视为提示放置输出的位置。 这个提示的确切语义是未指定的。 例如，JDK编译器javac将将类文件放置在与源文件源相同的目录中，除非提供了一个类文件输出目录。 为了方便这种行为，javac可以在调用此方法时将起始源文件提供为兄弟。

如果返回的对象表示一个source或class文件，那么它必须是JavaFileObject的一个实例。

非法地，此方法返回的文件对象位于位置，包名称和相对名称的连接中，或者位于兄弟参数旁边。 参见getFileForInput的一个例子。

参数

location - 输出位置

packageName - 包名称

relativeName - 相对名称

sibling - 用作放置提示的文件对象; 可能是null

结果

一个文件对象

异常

IllegalArgumentException - 如果此文件管理器不知道同级，或者该文件管理器不知道该位置，并且文件管理器不支持未知位置，或者如果 relativeName无效，或者该位置不是输出位置

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

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

flush

void flush()
    throws IOException

刷新此文件管理器直接或间接打开输出的任何资源。 冲洗一个封闭的文件管理器没有任何效果。

Specified by:

flush接口 Flushable

异常

IOException - 如果发生I / O错误

另请参见：

close()

close

void close()
    throws IOException

释放此文件管理器直接或间接打开的任何资源。 这可能会使此文件管理器无用，并且对此对象或通过此对象获取的任何对象的方法的后续调用的影响是未定义的，除非明确允许。 但是，关闭已经关闭的文件管理器没有任何效果。

Specified by:

close在接口 AutoCloseable

Specified by:

close接口 Closeable

异常

IOException - 如果发生I / O错误

另请参见：

flush()

getLocationForModule

default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location,
                                                      String moduleName)
                                               throws IOException

在位置中获取命名模块的位置，该位置可以是面向模块的位置或输出位置。 如果给定位置是输出位置，则结果将是输出位置，或者它将是面向包的位置。

实现要求：

此实现将抛出 UnsupportedOperationException 。

参数

location - 面向模块的位置

moduleName - 要找到的模块的名称

结果

命名模块的位置

异常

IOException - 如果发生I / O错误

UnsupportedOperationException - 如果此文件管理器不支持此操作

IllegalArgumentException - 如果位置既不是输出位置也不是面向模块的位置

从以下版本开始：

9

getLocationForModule

default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location,
                                                      JavaFileObject fo)
                                               throws IOException

获取包含要在一个位置找到的特定文件的模块的位置，该位置可以是面向模块的位置或输出位置。 如果给定位置是输出位置，则结果将是输出位置，或者它将是面向包的位置。

实现要求：

此实现将抛出 UnsupportedOperationException 。

参数

location - 面向模块的位置

fo - 该文件

结果

该模块包含该文件

异常

IOException - 如果发生I / O错误

UnsupportedOperationException - 如果此文件管理器不支持此操作

IllegalArgumentException - 如果位置既不是输出位置也不是面向模块的位置

从以下版本开始：

9

getServiceLoader

default <S> ServiceLoader<S> getServiceLoader(JavaFileManager.Location location,
                                              Class<S> service)
                                       throws IOException

从给定位置获取特定服务类的服务加载程序。 如果位置是面向模块的位置，则服务加载器将使用该位置中找到的模块中的服务声明。 否则，使用面向包的位置创建服务加载程序，在这种情况下，使用META-INF/services的提供程序配置文件确定服务。

实现要求：

此实现抛出 UnsupportedOperationException 。

参数类型

S - 服务类

参数

location - 面向模块的位置

service - 服务类的 Class对象

结果

用于给定服务类的服务加载器

异常

IOException - 如果发生I / O错误

UnsupportedOperationException - 如果此文件管理器不支持此操作

从以下版本开始：

9

inferModuleName

default String inferModuleName(JavaFileManager.Location location)
                        throws IOException

从其位置输入模块的名称，如 getLocationForModule或 listModuleLocations 。

实现要求：

这个实现会抛出 UnsupportedOperationException 。

参数

location - 表示模块的面向封装的位置

结果

模块的名称

异常

IOException - 如果发生I / O错误

UnsupportedOperationException - 如果此文件管理器不支持此操作

IllegalArgumentException - 如果位置不是此文件管理器已知的位置

从以下版本开始：

9

listLocationsForModules

default Iterable<Set<JavaFileManager.Location>> listLocationsForModules(JavaFileManager.Location location)
                                                                 throws IOException

列出面向模块的位置或输出位置中所有模块的位置。 如果给定的位置是输出，返回的位置将是输出位置，或者它将是面向包的位置。

实现要求：

此实现将抛出 UnsupportedOperationException 。

参数

location - 用于列出模块的面向模块的位置

结果

一系列位置包含模块

异常

IOException - 如果发生I / O错误

UnsupportedOperationException - 如果此文件管理器不支持此操作

IllegalArgumentException - 如果位置不是面向模块的位置

从以下版本开始：

9

contains

default boolean contains(JavaFileManager.Location location,
                         FileObject fo)
                  throws IOException

确定给定的文件对象是否“包含在”指定的位置。

对于面向包的位置，如果存在packageName和relativeName的值，则文件对象将包含在该位置，以便以下任一调用将返回same文件对象：

  getFileForInput(location, packageName, relativeName)
     getFileForOutput(location, packageName, relativeName, null) 

对于面向模块的位置，如果存在可以通过调用获得的模块，则文件对象包含在该位置中：

  getLocationForModule(location, moduleName) 

使得文件对象包含在该模块的（面向对象的）位置中。

实现要求：

此实现将抛出 UnsupportedOperationException 。

参数

location - 的位置

fo - 文件对象

结果

该文件是否包含在该位置

异常

IOException - 如果确定结果有问题

UnsupportedOperationException - 如果不支持该方法

从以下版本开始：

9