Module  java.compiler
软件包  javax.tools

Interface JavaFileManager

  • All Superinterfaces:
    AutoCloseableCloseableFlushableOptionChecker
    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
    另请参见:
    JavaFileObjectFileObject
    • 方法详细信息

      • 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是该文件管理器的选项, remainingremaining使用该选项的任何参数,并返回true,否则返回false。
        参数
        current - 当前选项
        remaining - 剩余选项
        结果
        如果此选项由此文件管理器处理,则为true,否则为false
        异常
        IllegalArgumentException - 如果此文件管理器的此选项被错误地使用
        IllegalStateException - 如果已经调用了 close()并且该文件管理器无法重新打开
      • hasLocation

        boolean hasLocation​(JavaFileManager.Location location)
        确定此文件管理器是否已知位置。
        参数
        location - 一个位置
        结果
        如果位置已知,则为真
      • getJavaFileForOutput

        JavaFileObject getJavaFileForOutput​(JavaFileManager.Location location,
                                            String className,
                                            JavaFileObject.Kind kind,
                                            FileObject sibling)
                                     throws IOException
        返回一个file object,用于在给定的面向对象的位置中表示指定类型的指定类的输出。

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

        参数
        location - 面向包的位置
        className - 一个类的名字
        kind - 文件的种类,必须是 SOURCECLASS之一
        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中指定的包在给定的取向包位置。

        如果返回的对象表示一个sourceclass文件,则它必须是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可以在调用此方法时将起始源文件提供为兄弟。

        如果返回的对象表示一个sourceclass文件,那么它必须是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
        从其位置输入模块的名称,如 getLocationForModulelistModuleLocations
        实现要求:
        这个实现会抛出 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
        确定给定的文件对象是否“包含在”指定的位置。

        对于面向包的位置,如果存在packageNamerelativeName的值,则文件对象将包含在该位置,以便以下任一调用将返回same文件对象:

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

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

          getLocationForModule(location, moduleName) 
        使得文件对象包含在该模块的(面向对象的)位置中。
        实现要求:
        此实现将抛出 UnsupportedOperationException
        参数
        location - 的位置
        fo - 文件对象
        结果
        该文件是否包含在该位置
        异常
        IOException - 如果确定结果有问题
        UnsupportedOperationException - 如果不支持该方法
        从以下版本开始:
        9