Module java.base
Package java.nio.file

Interface Path

所有超级接口:
Comparable<Path>, Iterable<Path>, Watchable
public interface Path extends Comparable<Path>, Iterable<Path>, Watchable
一个可用于定位文件系统中文件的对象。通常代表一个系统相关的文件路径。

Path表示一个层次结构路径，由一系列目录和文件名元素组成，这些元素由特殊的分隔符或定界符分隔。一个根组件，用于标识文件系统层次结构，也可能存在。距离目录层次结构根部最远的名称元素是文件或目录的名称。其他名称元素是目录名称。一个Path可以表示一个根，一个根和一系列名称，或者仅仅是一个或多个名称元素。如果Path仅由一个空名称元素组成，则被视为一个空路径。使用空路径访问文件等同于访问文件系统的默认目录。Path定义了getFileName、getParent、getRoot和subpath方法，用于访问路径组件或其名称元素的子序列。

除了访问路径的组件外，Path还定义了resolve和resolveSibling方法来组合路径。relativize方法可用于构建两个路径之间的相对路径。路径可以比较，并使用startsWith和endsWith方法相互测试。

此接口扩展了Watchable接口，以便可以使用路径定位的目录注册到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方法从java.io.File对象表示的抽象路径名获取Path。生成的Path可用于操作与java.io.File对象相同的文件。此外，toFile方法可用于从Path的String表示形式构造File。

并发性

此接口的实现是不可变的，可安全地供多个并发线程使用。

自版本:
1.7

  • Method Details

    • of

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

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

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

          Path dir = ...
    Path path = dir.resolve("file");
      参数:
      first - 路径字符串或路径字符串的初始部分
      more - 要连接以形成路径字符串的附加字符串
      返回:
      结果Path
      抛出:
      InvalidPathException - 如果路径字符串无法转换为Path
      自版本:
      11
      参见:

    • of

      static Path of(URI uri)
      返回通过转换URI获得的Path。

      此方法遍历已安装的提供程序，以定位由给定URI的URI scheme标识的提供程序。 URI方案将不考虑大小写进行比较。如果找到提供程序，则会调用其getPath方法来转换URI。

      对于由URI方案“file”标识的默认提供程序，给定的URI具有非空路径组件和未定义的查询和片段组件。权限组件是否存在取决于平台。返回的Path与默认文件系统相关联。

      默认提供程序提供类似于File类的往返保证。对于给定的Path p，只要原始Path，URI和新的Path都是在（可能是不同的调用中）同一个Java虚拟机中创建的，就保证

      Path.of(p.toUri()).equals( p.toAbsolutePath())
      。其他提供程序是否提供任何保证是特定于提供程序的，因此未指定。
      参数:
      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参数是要返回的名称元素的索引。在目录层次结构中，距离根最近的元素的索引为0。距离根最远的元素的索引为count-1。

      参数:
      index - 元素的索引
      返回:
      名称元素
      抛出:
      IllegalArgumentException - 如果index为负数，index大于或等于元素数量，或此路径没有名称元素

    • subpath

      Path subpath(int beginIndex, int endIndex)
      返回此路径名称元素的子序列作为Path对象。

      beginIndex和endIndex参数指定名称元素的子序列。在目录层次结构中，距离根最近的名称具有索引0。距离根最远的名称具有索引count-1。返回的Path对象具有从beginIndex开始并延伸到索引endIndex-1的名称元素。

      参数:
      beginIndex - 第一个元素的索引（包括）
      endIndex - 最后一个元素的索引（不包括）
      返回:
      表示此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/bar”开头。它不以“f”或“fo”开头。
      实现要求:
      对于此路径，默认实现等效于： 
          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”和“bar”结尾。它不以“r”或“/bar”结尾。请注意，不考虑尾部分隔符，因此在Path“foo/bar”上使用String“bar/”调用此方法将返回true。
      实现要求:
      默认实现等效于此路径的: 
          endsWith(getFileSystem().getPath(other));
      参数:
      other - 给定的路径字符串
      返回:
      如果此路径以给定路径结尾，则返回true; 否则返回false
      抛出:
      InvalidPathException - 如果路径字符串无法转换为路径。

    • normalize

      Path normalize()
      返回一个消除冗余名称元素的路径。

      此方法的精确定义取决于实现，但通常它从此路径派生一个不包含冗余名称元素的路径。在许多文件系统中，"."和".."是用于表示当前目录和父目录的特殊名称。在这种文件系统中，所有"."的出现都被视为冗余的。如果".."前面是非".."名称，则两个名称都被视为冗余（识别此类名称的过程重复进行，直到不再适用为止）。

      此方法不访问文件系统；路径可能无法定位到存在的文件。从路径中消除".."和前面的名称可能导致定位到与原始路径不同的文件。当前面的名称是符号链接时可能会出现这种情况。

      返回:
      结果路径或此路径（如果不包含冗余名称元素）；如果此路径没有根组件且所有名称元素都是冗余的，则返回空路径
      参见:

    • resolve

      Path resolve(Path other)
      将给定路径解析为此路径。

      如果other参数是一个绝对路径，则此方法直接返回other。如果other是一个空路径，则此方法直接返回此路径。否则，此方法将此路径视为目录，并将给定路径解析为此路径。在最简单的情况下，给定路径没有根组件，在这种情况下，此方法将给定路径与此路径连接起来，并返回一个结果路径，该路径以给定路径结尾。如果给定路径具有根组件，则解析高度依赖于实现，因此未指定。

      参数:
      other - 要解析为此路径的路径
      返回:
      结果路径
      参见:

    • resolve

      default Path resolve(String other)
      将给定路径字符串转换为Path，并按照resolve方法指定的方式解析到此Path。例如，假设名称分隔符是"/"，路径表示为"foo/bar"，然后使用路径字符串"gus"调用此方法将导致Path为"foo/bar/gus"。
      实现要求:
      默认实现等效于此路径的: 
          resolve(getFileSystem().getPath(other));
      参数:
      other - 要解析为此路径的路径字符串
      返回:
      结果路径
      抛出:
      InvalidPathException - 如果路径字符串无法转换为路径。
      参见:

    • resolveSibling

      default Path resolveSibling(Path other)
      将给定路径解析为此路径的父路径。这在需要用另一个文件名替换文件名时很有用。例如，假设名称分隔符是"/"，路径表示为"dir1/dir2/foo"，然后使用Path "bar"调用此方法将导致Path "dir1/dir2/bar"。如果此路径没有父路径，或other是绝对的，则此方法返回other。如果other是一个空路径，则此方法返回此路径的父路径，或者如果此路径没有父路径，则返回空路径。
      实现要求:
      默认实现等效于此路径的: 
          (getParent() == null) ? other : getParent().resolve(other);
      除非other == null，否则将抛出NullPointerException。
      参数:
      other - 要解析为此路径的父路径
      返回:
      结果路径
      参见:

    • resolveSibling

      default Path resolveSibling(String other)
      将给定路径字符串转换为Path，并按照resolveSibling方法指定的方式解析到此路径的父路径。
      实现要求:
      默认实现等效于此路径的: 
          resolveSibling(getFileSystem().getPath(other));
      参数:
      other - 要解析为此路径的父路径的路径字符串
      返回:
      结果路径
      抛出:
      InvalidPathException - 如果路径字符串无法转换为路径。
      参见:

    • relativize

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

      相对化是解析的逆过程。此方法尝试构造一个相对路径，当解析到此路径时，会得到一个定位到与给定路径相同文件的路径。例如，在UNIX上，如果此路径为"/a/b"，给定路径为"/a/b/c/d"，则结果的相对路径将是"c/d"。如果此路径和给定路径都没有根组件，则可以构造相对路径。如果两个路径中只有一个具有根组件，则无法构造相对路径。如果两个路径都具有根组件，则是否可以构造相对路径取决于实现。如果此路径和给定路径相等，则返回一个空路径。

      对于任意两个规范化路径p和q，其中q没有根组件，

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

      当支持符号链接时，当解析后的路径相对于此路径产生一个路径，该路径可用于定位与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）路径，则UNC服务器名称可能被编码在生成的URI的权限组件中。对于默认提供程序，如果文件存在，并且可以确定文件是目录，则生成的URI将以斜杠结尾。

      默认提供程序为File类提供类似的往返保证。对于给定的Path p，只要原始Path，URI和新Path都是在（可能是不同的调用中）同一个Java虚拟机中创建的，就保证

      Path.of(p.toUri()).equals(p .toAbsolutePath())
      。其他提供程序是否提供任何保证是特定于提供程序的，因此未指定。

      当构造文件系统以访问文件内容作为文件系统时，如果返回的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
      返回现有文件的真实路径。

      此方法的精确定义取决于实现，但通常源自此路径，一个定位与此路径相同文件的absolute路径，但名称元素表示目录和文件的实际名称。例如，在文件系统上文件名比较不区分大小写时，名称元素表示其实际大小写的名称。此外，结果路径已删除冗余名称元素。

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

      可以使用options数组指示如何处理符号链接。默认情况下，符号链接将解析为其最终目标。如果存在选项NOFOLLOW_LINKS，则此方法不会解析符号链接。一些实现允许特殊名称（如“..”）引用父目录。在推导真实路径时，如果“..”（或等效项）前面跟随非“..”名称，则实现通常会导致两个名称都被删除。当不解析符号链接且前面的名称是符号链接时，只有在保证结果路径将定位与此路径相同文件时，才会删除名称。

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

    • toFile

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

      如果通过调用File的toPath方法创建此路径，则不能保证此方法返回的File对象与原始File相等。

      实现要求：
      对于此路径，默认实现等效于： 
          new File(toString());
      如果创建此Path的FileSystem是默认文件系统；否则将抛出UnsupportedOperationException。
      返回：
      表示此路径的File对象
      抛出：
      UnsupportedOperationException - 如果此Path未与默认提供程序关联

    • register

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

      在此版本中，此路径定位存在的目录。将目录注册到监视服务，以便可以监视目录中的条目。events参数是要注册的事件，可能包含以下事件：

      这些事件的context是此路径定位的目录和创建、删除或修改的目录条目之间的相对路径。

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

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

      如果通过符号链接将文件注册到监视服务，则在注册后监视是否继续依赖符号链接的存在是实现特定的。

      指定者:
      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
      注册此路径指定的文件到监视服务。

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

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

      使用示例: 假设我们希望注册一个目录以获取条目创建、删除和修改事件：

          Path dir = ...
    WatchService watcher = ...

    WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);
      指定者:
      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()
      返回此路径的名称元素的迭代器。

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

      指定者:
      iterator 在接口 Iterable<Path>中
      实现要求:
      默认实现返回一个 Iterator<Path>，对于此路径，遍历由 getName(index) 返回的 Path，其中 index 的范围从零到 getNameCount() - 1，包括边界。
      返回:
      此路径的名称元素的迭代器

    • compareTo

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

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

      指定者:
      compareTo 在接口 Comparable<Path>中
      参数:
      other - 与此路径进行比较的路径。
      返回:
      如果参数与此路径 相等，则返回零；如果此路径在字典顺序上小于参数，则返回小于零的值；如果此路径在字典顺序上大于参数，则返回大于零的值
      抛出:
      ClassCastException - 如果路径与不同提供程序关联

    • equals

      boolean equals(Object other)
      测试此路径与给定对象的相等性。

      如果给定对象不是路径，或者是与不同 FileSystem 关联的路径，则此方法返回 false。

      两个路径是否相等取决于文件系统实现。在某些情况下，路径是在不考虑大小写的情况下进行比较的，而在其他情况下是区分大小写的。此方法不访问文件系统，也不需要文件存在。在需要时，可以使用 isSameFile 方法来检查两个路径是否定位到相同的文件。

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

      覆盖:
      equals 在类 Object中
      参数:
      other - 要与此对象进行比较的对象
      返回:
      如果给定对象是与此 Path 相同的 Path，则返回 true
      参见:

    • hashCode

      int hashCode()
      为此路径计算哈希码。

      哈希码基于路径的组件，并满足 Object.hashCode 方法的一般合同。

      覆盖:
      hashCode 在类 Object中
      返回:
      此路径的哈希码值
      参见:

    • toString

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

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

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

      覆盖:
      toString 在类 Object中
      返回:
      此路径的字符串表示形式