模块  java.base
软件包  java.nio.file

Interface Path

  • All Superinterfaces:
    Comparable<Path>Iterable<Path>Watchable

    public interface Path
    extends Comparable<Path>, Iterable<Path>, Watchable
    可用于在文件系统中查找文件的对象。 它通常表示系统相关的文件路径。

    Path表示分层的路径,由一系列由特殊分隔符或分隔符分隔的目录和文件名元素组成。 还可以存在标识文件系统层次结构的根组件 距目录层次结构根目录最远的name元素是文件或目录的名称。 其他名称元素是目录名称。 Path可以表示根,根和一系列名称,或者只是一个或多个名称元素。 如果Path仅包含一个为空的名称元素,则将其视为空路径 使用空路径访问文件等同于访问文件系统的默认目录。 Path定义getFileNamegetParentgetRoot ,和subpath方法来访问路径部件或它的名称元素的子序列。

    除了访问路径的组件之外, Path还定义了用于组合路径的resolveresolveSibling方法。 relativize方法,可用于构造两个路径之间的相对路径。 路径可以是compared ,并使用startsWithendsWith方法相互测试。

    此接口扩展了Watchable接口,以便路径所在的目录可以是registered其中包含WatchService和目录中的条目。

    警告:此接口仅供那些开发自定义文件系统实现的人员实现。 可以在将来的版本中将方法添加到此接口。

    访问文件

    路径可以与Files类一起使用,以对文件,目录和其他类型的文件进行操作。 例如,假设我们想要BufferedReader从文件“ access.log ”中读取文本。 该文件位于相对于当前工作目录的目录“ logs ”中,并且是UTF-8编码的。

      Path path = FileSystems.getDefault().getPath("logs", "access.log");
         BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8); 

    互通性

    与默认值provider关联的路径通常可与java.io.File类互操作。 其他提供程序创建的路径不可能与java.io.File表示的抽象路径名互操作。 toPath方法可以被用于获得Path从由A表示的抽象路径名java.io.File对象。 生成的Path可用于在与java.io.File对象相同的文件上java.io.File 此外, toFile方法是有用的构建FileString一个的表示Path

    并发

    此接口的实现是不可变的,并且可供多个并发线程使用。

    从以下版本开始:
    1.7
    • 方法详细信息

      • of

        static Path of​(String first,
                       String... more)
        通过转换路径字符串或连接时形成路径字符串的字符串序列,返回Path 如果more未指定任何元素,则first参数的值是要转换的路径字符串。 如果more指定了一个或多个元素,那么每个非空字符串(包括first )将被视为一系列名称元素,并且将其连接以形成路径字符串。 有关字符串如何加入的详细信息是提供者特定的,但通常它们将使用name-separator作为分隔符进行连接。 例如,如果名称分隔符为“ / ”并且调用了getPath("/foo","bar","gus") ,则路径字符串"/foo/bar/gus"将转换为Path 一个Path占空路径如果返回first空字符串和more不包含任何非空字符串。

        Path通过调用获得getPath的方法default FileSystem

        请注意,虽然此方法非常方便,但使用它将意味着对默认值FileSystem的假定引用,并限制调用代码的实用程序。 因此,它不应该用于灵活重用的库代码中。 更灵活的替代方法是使用现有的Path实例作为锚点,例如:

           Path dir = ... Path path = dir.resolve("file");  
        参数
        first - 路径字符串或路径字符串的初始部分
        more - 要连接以形成路径字符串的其他字符串
        结果
        结果 Path
        异常
        InvalidPathException - 如果路径字符串无法转换为 Path
        从以下版本开始:
        11
        另请参见:
        FileSystem.getPath(java.lang.String, java.lang.String...)
      • of

        static Path of​(URI uri)
        通过转换URI返回Path

        此方法遍历installed提供程序,以找到由给定URI的URI scheme标识的提供程序。 在不考虑大小写的情况下比较URI方案。 如果找到提供程序,则调用其getPath方法来转换URI。

        在由URI方案“file”标识的默认提供者的情况下,给定URI具有非空路径组件,以及未定义的查询和片段组件。 是否存在授权组件是特定于平台的。 返回的Pathdefault文件系统关联。

        默认提供程序为File类提供类似的往返保证。 对于给定的Path p ,保证

        Path.of( p . toUri ()).equals( p . toAbsolutePath ())
        只要原Path ,该URI ,新Path都在(可能是不同的调用)相同的Java虚拟机创建。 其他提供商是否提供任何保证是特定于提供商的,因此未指定。
        参数
        uri - 要转换的URI
        结果
        结果 Path
        异常
        IllegalArgumentException - 如果uri参数的前提条件不成立。 URI的格式是特定于提供者的。
        FileSystemNotFoundException - 由URI标识的文件系统不存在且无法自动创建,或者未安装由URI的方案组件标识的提供程序
        SecurityException - 如果安装了安全管理器,它将拒绝访问文件系统的未指定权限
        从以下版本开始:
        11
      • getFileSystem

        FileSystem getFileSystem()
        返回创建此对象的文件系统。
        结果
        创建此对象的文件系统
      • isAbsolute

        boolean isAbsolute()
        判断此路径是否绝对。

        绝对路径是完整的,因为它不需要与其他路径信息组合以便定位文件。

        结果
        true当且仅当此路径是绝对路径时
      • getRoot

        Path getRoot()
        返回此路径的根组分作为 Path对象,或 null如果该路径不具有根组件。
        结果
        表示此路径的根组件的路径,或 null
      • getFileName

        Path getFileName()
        返回此路径表示为Path对象的文件或目录的名称。 文件名是目录层次结构中根目录的最远元素。
        结果
        表示文件或目录名称的路径,如果此路径具有零个元素, null
      • getParent

        Path getParent()
        返回父路径 ,如果此路径没有父路径 ,则返回null

        此路径对象的父级包含此路径的根组件(如果有),以及路径中的每个元素(目录层次结构中除根目录之外的最远) 此方法不访问文件系统; 路径或其父级可能不存在。 此外,此方法不会消除诸如“。”之类的特殊名称。 和“......”可以在某些实现中使用。 例如,在UNIX上,父级“ /a/b/c ”是“ /a/b ”,父级"x/y/. “是” x/y “。此方法可以与normalize方法一起使用,以消除冗余名称,适用于类似shell的导航的情况需要。

        如果此路径具有多个元素且没有根组件,则此方法等效于评估表达式:

         subpath(0, getNameCount()-1);
         
        结果
        表示路径父级的路径
      • getNameCount

        int getNameCount()
        返回路径中的名称元素数。
        结果
        路径中的元素数,如果此路径仅表示根组件, 0
      • getName

        Path getName​(int index)
        Path对象的形式返回此路径的名称元素。

        index参数是要返回的name元素的索引。 最接近目录层次结构中的根的元素具有索引0 距离最远的元素的索引为count -1

        参数
        index - 元素的索引
        结果
        名称元素
        异常
        IllegalArgumentException - 如果 index为负数,则 index大于或等于元素数,或者此路径的名称元素为零
      • subpath

        Path subpath​(int beginIndex,
                     int endIndex)
        返回一个相对Path ,它是此路径的name元素的子序列。

        beginIndexendIndex参数指定名称元素的子序列。 最接近目录层次结构中的根的名称具有索引0 距离最远的名称的索引为count -1 返回的Path对象具有名称元素,该元素从beginIndex开始并扩展到索引endIndex-1处的元素。

        参数
        beginIndex - 第一个元素的索引,包括
        endIndex - 最后一个元素的索引,不包括
        结果
        一个新的 Path对象,它是此 Path名称元素的子 Path
        异常
        IllegalArgumentException - 如果beginIndex为负数,或大于或等于元素数。 如果endIndex小于或等于beginIndex ,或大于元素数。
      • startsWith

        boolean startsWith​(Path other)
        测试此路径是否以给定路径开头。

        这条道路给定的路径开始后 ,如果这个路径的根组件给定的路径的根组件开始 ,这条路径具有相同名称元素作为给定的路径开始。 如果给定路径具有比此路径更多的名称元素,则返回false

        此路径的根组件是否以给定路径的根组件开头是特定于文件系统的。 如果此路径没有根组件且给定路径具有根组件,则此路径不会以给定路径开头。

        如果给定路径与此路径的其他FileSystem相关联,则返回false

        参数
        other - 给定路径
        结果
        true如果此路径以给定路径开头; 否则false
      • startsWith

        default boolean startsWith​(String other)
        测试此路径是否以Path ,通过转换给定的路径字符串构造,完全按照startsWith(Path)方法指定的方式。 例如,在UNIX上,路径“ foo/bar ”以“ foo ”和“ foo/barfoo/bar 它不以“ f ”或“ fofo
        实现要求:
        此路径的默认实现等效于:
           startsWith(getFileSystem().getPath(other));  
        参数
        other - 给定的路径字符串
        结果
        true如果此路径以给定路径开头; 否则false
        异常
        InvalidPathException - 如果路径字符串无法转换为路径。
      • endsWith

        boolean endsWith​(Path other)
        测试此路径是否以给定路径结束。

        如果给定路径具有N个元素,并且没有根组件,并且此路径具有N个或更多元素,则如果每个路径的最后N个元素(从距离根最远的元素开始)相等,则此路径以给定路径结束。

        如果给定路径具有根组件,则如果此路径的根组件以给定路径的根组件结束 ,并且两条路径的相应元素相等,则此路径以给定路径结束 此路径的根组件是否以给定路径的根组件结尾是特定于文件系统的。 如果此路径没有根组件且给定路径具有根组件,则此路径不会以给定路径结束。

        如果给定路径与此路径的其他FileSystem关联,则返回false

        参数
        other - 给定路径
        结果
        true如果此路径以给定路径结束; 否则false
      • endsWith

        default boolean endsWith​(String other)
        测试此路径是否以Path ,通过转换给定的路径字符串构造,完全按照endsWith(Path)方法指定的方式。 例如,在UNIX上,路径“ foo/bar ”以“ foo/bar ”和“ barbar 它不以“ r ”或“ /bar/bar 需要注意的是,后隔板不考虑,所以调用的是这种方法Pathfoo/bar ”与Stringbar/ ”返回true
        实现要求:
        此路径的默认实现等效于:
           endsWith(getFileSystem().getPath(other));  
        参数
        other - 给定的路径字符串
        结果
        true如果此路径以给定路径结束; 否则false
        异常
        InvalidPathException - 如果路径字符串无法转换为路径。
      • normalize

        Path normalize()
        返回此路径的路径,其中删除了冗余名称元素。

        此方法的精确定义取决于实现,但通常它源自此路径,即不包含冗余名称元素的路径。 在许多文件系统中,“ . ”和“ .. ”是用于指示当前目录和父目录的特殊名称。 在这种文件系统中,所有出现的“ . ”都被认为是多余的。 如果“ .. ”之前是非“ .. ”名称,则这两个名称都被视为冗余(识别此类名称的过程将重复,直至不再适用)。

        此方法不访问文件系统; 路径可能找不到存在的文件。 从路径中.... ”和前一个名称可能会导致找到与原始路径不同的文件的路径。 当前面的名称是符号链接时,可能会出现这种情况。

        结果
        生成的路径或路径,如果它不包含冗余的名称元素; 如果此路径没有根组件且所有名称元素都是冗余的,则返回空路径
        另请参见:
        getParent()toRealPath(java.nio.file.LinkOption...)
      • resolve

        Path resolve​(Path other)
        根据此路径解析给定路径。

        如果other参数是absolute路径,则此方法other返回other 如果other空路径,则此方法other会返回此路径。 否则,此方法将此路径视为目录,并针对此路径解析给定路径。 在最简单的情况下,给定的路径不具有root部件,在这种情况下该方法加入给定的路径向此路径,并返回所得到的路径ends与给定的路径。 在给定路径具有根组件的情况下,解决方案高度依赖于实现,因此未指定。

        参数
        other - 针对此路径解析的路径
        结果
        由此产生的路径
        另请参见:
        relativize(java.nio.file.Path)
      • resolve

        default Path resolve​(String other)
        一个给定的路径字符串转换为Path并解析它针对此Path在完全按规定的方式resolve方法。 例如,假设名称分隔符为“ / ”,路径表示“ foo/bar ”,则使用路径字符串“ gus ”调用此方法将导致Pathfoo/bar/gus ”。
        实现要求:
        此路径的默认实现等效于:
           resolve(getFileSystem().getPath(other));  
        参数
        other - 要针对此路径解析的路径字符串
        结果
        由此产生的路径
        异常
        InvalidPathException - 如果路径字符串无法转换为路径。
        另请参见:
        FileSystem.getPath(java.lang.String, java.lang.String...)
      • resolveSibling

        default Path resolveSibling​(Path other)
        根据此路径的路径解析给定路径parent 在需要用其他文件名替换文件名的情况下,这很有用。 例如,假设名称分隔符为“ / ”,路径表示“ dir1/dir2/foo ”,则使用Pathbar ”调用此方法将生成Pathdir1/dir2/bar ”。 如果此路径没有父路径,或otherabsolute ,则此方法返回other 如果other是空路径,则此方法返回此路径的父路径,或者此路径没有父路径,即空路径。
        实现要求:
        此路径的默认实现等效于:
           (getParent() == null) ? other : getParent().resolve(other);  
        除非other == null ,在这种情况下抛出NullPointerException
        参数
        other - 针对此路径的父级解析的路径
        结果
        由此产生的路径
        另请参见:
        resolve(Path)
      • resolveSibling

        default Path resolveSibling​(String other)
        将给定的路径字符串转换为 Path并按照 resolveSibling方法指定的方式将其解析为此路径的 parent路径。
        实现要求:
        此路径的默认实现等效于:
           resolveSibling(getFileSystem().getPath(other));  
        参数
        other - 要针对此路径的父级解析的路径字符串
        结果
        由此产生的路径
        异常
        InvalidPathException - 如果路径字符串无法转换为路径。
        另请参见:
        FileSystem.getPath(java.lang.String, java.lang.String...)
      • relativize

        Path relativize​(Path other)
        构造此路径与给定路径之间的相对路径。

        相对论是resolution的逆。 此方法尝试构造一个relative路径,该路径在resolved针对此路径时,生成一个路径,该路径定位与给定路径相同的文件。 例如,在UNIX上,如果此路径为"/a/b"且给定路径为"/a/b/c/d"则生成的相对路径为"c/d" 如果此路径和给定路径没有root组件,则可以构造相对路径。 如果只有一个路径具有根组件,则无法构建相对路径。 如果两个路径都具有根组件,那么如果可以构造相对路径,则它是依赖于实现的。 如果此路径和给定路径为equal则返回空路径

        对于任何两个normalized路径pq ,其中q没有根组件,

        p .relativize( p .resolve( q )).equals( q )

        当支持符号链接时,那么当针对此路径解析时,生成的路径是否会产生可用于定位same文件的路径,因为other是依赖于实现的。 例如,如果此路径为"/a/b"且给定路径为"/a/x"则生成的相对路径可能为"../x" 如果"b"是符号链接,则依赖于实现,如果"a/b/../x"将找到与"/a/x"相同的文件。

        参数
        other - 针对此路径进行相对化的路径
        结果
        生成的相对路径,如果两条路径相等则为空路径
        异常
        IllegalArgumentException - 如果 other不是可以针对此路径进行相对化的 Path
      • toUri

        URI toUri()
        返回表示此路径的URI。

        此方法构造一个绝对值URI ,其scheme等于标识提供程序的URI方案。 方案特定部分的确切形式是高度依赖提供者的。

        对于默认提供程序,URI是分层的,具有绝对的path组件。 查询和片段组件未定义。 是否定义了权限组件是依赖于实现的。 不保证URI可用于构造java.io.File 特别是,如果此路径表示通用命名约定(UNC)路径,则可以在生成的URI的权限组件中编码UNC服务器名称。 对于默认提供程序,并且文件存在,并且可以确定该文件是目录,则生成的URI将以斜杠结束。

        默认提供程序为File类提供类似的往返保证。 对于给定的Path p ,可以保证

        Path.of ( p .toUri()).equals( p . toAbsolutePath ())
        只要原Path ,该URI ,新Path都在(可能是不同的调用)相同的Java虚拟机创建。 其他提供商是否提供任何保证是特定于提供商的,因此未指定。

        当构造文件系统以作为文件系统访问文件的内容时,如果返回的URI表示文件系统中的给定路径,或者它表示编码封闭文件系统的URI的复合 URI,则它是高度特定于实现的。 。 此版本中未定义复合URI的格式; 可以在将来的版本中添加这样的方案。

        结果
        表示此路径的URI
        异常
        IOError - 如果发生I / O错误,获取绝对路径,或者构造文件系统以访问文件内容作为文件系统,则无法获取封闭文件系统的URI
        SecurityException - 如果是默认提供程序,并且安装了安全管理器,则 toAbsolutePath方法将引发安全性异常。
      • toAbsolutePath

        Path toAbsolutePath()
        返回表示此路径的绝对路径的Path对象。

        如果此路径已经是absolute则此方法只返回此路径。 否则,此方法通常通过针对文件系统缺省目录解析路径,以依赖于实现的方式解析路径。 根据实现,如果文件系统不可访问,此方法可能会抛出I / O错误。

        结果
        表示绝对路径的 Path对象
        异常
        IOError - 如果发生I / O错误
        SecurityException - 如果是默认提供程序,则安装了安全管理器,并且此路径不是绝对路径,则调用安全管理器的 checkPropertyAccess方法来检查对系统属性的访问权限 user.dir
      • toRealPath

        Path toRealPath​(LinkOption... options)
                 throws IOException
        返回现有文件的实际路径。

        此方法的精确定义取决于实现,但通常它是从此路径派生的,该路径将same文件定位为此路径,但使用名称元素表示目录和文件的实际名称。 例如,在文件系统上的文件名比较不区分大小写的情况下,名称元素表示实际情况下的名称。 此外,生成的路径已删除冗余名称元素。

        如果此路径是相对的,则首先获取其绝对路径,就像通过调用toAbsolutePath方法一样。

        options数组可用于指示如何处理符号链接。 默认情况下,符号链接将解析为其最终目标。 如果存在选项NOFOLLOW_LINKS ,则此方法不解析符号链接。 某些实现允许使用诸如“ .. ”之类的特殊名称来引用父目录。 在派生实际路径时 ,“ .. ”(或等效物)前面有非“ .. ”名称,那么实现通常会导致两个名称都被删除。 当不解析符号链接且前面的名称是符号链接时,只有在保证结果路径将找到与此路径相同的文件时才会删除名称。

        参数
        options - 指示如何处理符号链接的选项
        结果
        绝对路径表示此对象定位的文件的 实际路径
        异常
        IOException - 如果文件不存在或发生I / O错误
        SecurityException - 如果是默认提供程序,并且安装了安全管理器,则会调用其 checkRead方法来检查对该文件的读取访问权限,并且此路径不是绝对路径,将调用其 checkPropertyAccess方法来检查对系统属性的访问权限 user.dir
      • toFile

        default File toFile()
        返回表示此路径的File对象。 如果此Path与默认提供程序关联,则此方法等效于返回使用此路径的String表示构造的File对象。

        如果这个路径是通过调用创建File toPath方法那么就不能保证File通过这个方法返回的对象是equal原来的File

        实现要求:
        此路径的默认实现等效于:
           new File(toString());  
        如果FileSystem这创造了这个Path是默认的文件系统; 否则会抛出UnsupportedOperationException
        结果
        表示此路径的 File对象
        异常
        UnsupportedOperationException - 如果此 Path未与默认提供程序关联
      • register

        WatchKey register​(WatchService watcher,
                          WatchEvent.Kind<?>[] events,
                          WatchEvent.Modifier... modifiers)
                   throws IOException
        使用监视服务注册此路径所在的文件。

        在此版本中,此路径定位存在的目录。 该目录已向监视服务注册,以便可以监视目录中的条目。 events参数是要注册的事件,可能包含以下事件:

        这些事件的context是此路径所在目录与查找创建,删除或修改的目录条目的路径之间的相对路径。

        事件集可能包括枚举StandardWatchEventKinds未定义的其他实现特定事件

        modifiers参数指定限定目录注册方式的修饰符 此版本未定义任何标准修饰符。 它可能包含特定于实现的修饰符。

        如果通过符号链接向监视服务注册文件,则如果监视在注册后继续依赖于符号链接的存在,则它是特定于实现的。

        Specified by:
        register在界面 Watchable
        参数
        watcher - 要将此对象注册到的监视服务
        events - 应为其注册此对象的事件
        modifiers - 修改对象注册方式的修饰符(如果有)
        结果
        表示使用给定监视服务注册此对象的键
        异常
        UnsupportedOperationException - 如果指定了不支持的事件或修饰符
        IllegalArgumentException - 如果指定了无效的事件或修饰符组合
        ClosedWatchServiceException - 如果监视服务已关闭
        NotDirectoryException - 如果文件已注册以观察目录中的条目且该文件不是目录 (可选的特定异常)
        IOException - 如果发生I / O错误
        SecurityException - 如果是默认提供程序,并且安装了安全管理器,则会调用 checkRead方法来检查对该文件的读取权限。
      • register

        default WatchKey register​(WatchService watcher,
                                  WatchEvent.Kind<?>... events)
                           throws IOException
        使用监视服务注册此路径所在的文件。

        调用此方法的行为与调用完全相同

          watchable.register(watcher, events, new WatchEvent.Modifier[0]); 

        用法示例:假设我们希望为条目创建,删除和修改事件注册目录:

          Path dir = ...
             WatchService watcher = ...
        
             WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY); 
        Specified by:
        register接口 Watchable
        实现要求:
        此路径的默认实现等效于:
           register(watcher, events, new WatchEvent.Modifier[0]);  
        参数
        watcher - 要将此对象注册到的监视服务
        events - 应为其注册此对象的事件
        结果
        表示使用给定监视服务注册此对象的键
        异常
        UnsupportedOperationException - 如果指定了不支持的事件
        IllegalArgumentException - 如果指定了无效的事件组合
        ClosedWatchServiceException - 如果关闭了监视服务
        NotDirectoryException - 如果文件已注册以查看目录中的条目且该文件不是目录 (可选的特定异常)
        IOException - 如果发生I / O错误
        SecurityException - 如果是默认提供程序,并且安装了安全管理器,则会调用 checkRead方法来检查对该文件的读取权限。
      • iterator

        default Iterator<Path> iterator()
        返回此路径的name元素的迭代器。

        迭代器返回的第一个元素表示最接近目录层次结构中的根的name元素,第二个元素是下一个最接近的元素,依此类推。 返回的最后一个元素是此路径表示的文件或目录的名称。 迭代器不返回root组件(如果存在)。

        Specified by:
        iterator在界面 Iterable<Path>
        实现要求:
        默认实现返回 Iterator<Path> ,对于此路径,它遍历由 Path返回的 getName(index) ,其中 index范围为0到 getNameCount() - 1 (包括0和 getNameCount() - 1 )。
        结果
        这个路径的名称元素上的迭代器。
      • compareTo

        int compareTo​(Path other)
        按字典顺序比较两条抽象路径。 此方法定义的排序是特定于提供程序的,对于默认提供程序,特定于平台。 此方法不访问文件系统,也不需要存在任何文件。

        此方法不能用于比较与不同文件系统提供程序关联的路径。

        Specified by:
        compareTo在界面 Comparable<Path>
        参数
        other - 与此路径比较的路径。
        结果
        如果参数为 equal到此路径,则为零;如果此路径按字典顺序小于参数,则为小于零;如果此路径在词典上大于参数,则为大于零的值
        异常
        ClassCastException - 如果路径与不同的提供者相关联
      • equals

        boolean equals​(Object other)
        测试此路径是否与给定对象相等。

        如果给定对象不是Path,或者是与其他FileSystem关联的Path,则此方法返回false

        两条路径是否相等取决于文件系统的实现。 在某些情况下,路径的比较与案例无关,而其他情况则区分大小写。 此方法不访问文件系统,并且不需要存在该文件。 如果需要,可以使用isSameFile方法检查两个路径是否找到同一文件。

        该方法满足Object.equals方法的一般合同。

        重写:
        equals在类 Object
        参数
        other - 要与此对象进行比较的对象
        结果
        true当且仅当给定对象是 Path与此 Path相同
        另请参见:
        Object.hashCode()HashMap
      • toString

        String toString()
        返回此路径的字符串表示形式。

        如果通过使用getPath方法转换路径字符串来创建此路径,则此方法返回的路径字符串可能与用于创建路径的原始字符串不同。

        返回的路径字符串使用默认名称separator来分隔路径中的名称。

        重写:
        toString ,类 Object
        结果
        the string representation of this path