模块  java.compiler
软件包  javax.tools

Interface JavaFileManager

  • All Superinterfaces:
    AutoCloseable ， Closeable ， Flushable ， OptionChecker
    All Known Subinterfaces:
    StandardJavaFileManager
    所有已知实现类：
    ForwardingJavaFileManager 
    public interface JavaFileManagerextends Closeable, Flushable, OptionChecker
    用于在Java上运行的工具的文件管理器 - 编程语言源和类文件。 在此上下文中， file表示常规文件和其他数据源的抽象。

    构造新的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。

    从以下版本开始：
    1.6
    另请参见：
    JavaFileObject ， FileObject

    • 方法详细信息

      • list

        Iterable<JavaFileObject> list​(JavaFileManager.Location location,                              String packageName,                              Set<JavaFileObject.Kind> kinds,                              boolean recurse)                       throws IOException
        列出在给定的面向包的位置中与给定条件匹配的所有文件对象。 如果recurse为true，则在“subpackages”中列出文件对象。

        注意：即使此文件管理器未知给定位置，也可能不会返回null 。 此外，未知位置可能不会导致异常。

        参数
        location - 一个位置
        packageName - 包名称
        kinds - 仅返回这些类型的对象
        recurse - 如果为true则包含“子包”
        结果
        与给定条件匹配的Iterable文件对象
        异常
        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 - 一个位置
        结果
        如果位置已知，则为true

      • 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,                                              类<S> service)                                       throws IOException
        从给定位置获取特定服务类的服务加载程序。 如果位置是面向模块的位置，则服务加载器将使用该位置中找到的模块中的服务声明。 否则，使用面向包的位置创建服务加载程序，在这种情况下，使用META-INF/services的提供程序配置文件确定服务。
        实现要求：
        此实现抛出 UnsupportedOperationException 。
        参数类型
        S - 服务类
        参数
        location - 面向模块的位置
        service - 服务类的 类对象
        结果
        给定服务类的服务加载器
        异常
        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