Method Summary

Method Details

• of

  static Path of(String first,String... more)

  Returns aPath by converting a path string, or a sequence of strings that when joined form a path string. Ifmore does not specify any elements then the value of thefirst parameter is the path string to convert. Ifmore specifies one or more elements then each non-empty string, includingfirst, is considered to be a sequence of name elements and is joined to form a path string. The details as to how the Strings are joined is provider specific but typically they will be joined using thename-separator as the separator. For example, if the name separator is "/" andgetPath("/foo","bar","gus") is invoked, then the path string"/foo/bar/gus" is converted to aPath. APath representing an empty path is returned iffirst is the empty string andmore does not contain any non-empty strings.

  ThePath is obtained by invoking thegetPath method of thedefaultFileSystem.

  Note that while this method is very convenient, using it will imply an assumed reference to the defaultFileSystem and limit the utility of the calling code. Hence it should not be used in library code intended for flexible reuse. A more flexible alternative is to use an existingPath instance as an anchor, such as:

  Copy

      Path dir = ...    Path path = dir.resolve("file");

  Parameters:

  first - the path string or initial part of the path string

  more - additional strings to be joined to form the path string

  Returns:

  the resultingPath

  Throws:

  InvalidPathException - if the path string cannot be converted to aPath

  Since:

  11

  See Also:

  • FileSystem.getPath(java.lang.String, java.lang.String...)

• of

  static Path of(URI uri)

  Returns aPath by converting a URI.

  This method iterates over theinstalled providers to locate the provider that is identified by the URIscheme of the given URI. URI schemes are compared without regard to case. If the provider is found then itsgetPath method is invoked to convert the URI.

  In the case of the default provider, identified by the URI scheme "file", the given URI has a non-empty path component, and undefined query and fragment components. Whether the authority component may be present is platform specific. The returnedPath is associated with thedefault file system.

  The default provider provides a similarround-trip guarantee to theFile class. For a givenPathp it is guaranteed that

  Path.of(p.toUri()).equals(p.toAbsolutePath())

  so long as the originalPath, theURI, and the new Path are all created in (possibly different invocations of) the same Java virtual machine. Whether other providers make any guarantees is provider specific and therefore unspecified.

  Parameters:

  uri - the URI to convert

  Returns:

  the resultingPath

  Throws:

  IllegalArgumentException - if preconditions on theuri parameter do not hold. The format of the URI is provider specific.

  FileSystemNotFoundException - The file system, identified by the URI, does not exist and cannot be created automatically, or the provider identified by the URI's scheme component is not installed

  Since:

  11

• getFileSystem

  FileSystem getFileSystem()

  Returns the file system that created this object.

  Returns:

  the file system that created this object

• isAbsolute

  boolean isAbsolute()

  Tells whether or not this path is absolute.

  An absolute path is complete in that it doesn't need to be combined with other path information in order to locate a file.

  Returns:

  true if, and only if, this path is absolute

• getRoot

  Path getRoot()

  Returns the root component of this path as aPath object, ornull if this path does not have a root component.

  Returns:

  a path representing the root component of this path, ornull

• getFileName

  Path getFileName()

  Returns the name of the file or directory denoted by this path as aPath object. The file name is thefarthest element from the root in the directory hierarchy.

  Returns:

  a path representing the name of the file or directory, ornull if this path has zero elements

• getParent

  Path getParent()

  Returns theparent path, ornull if this path does not have a parent.

  The parent of this path object consists of this path's root component, if any, and each element in the path except for thefarthest from the root in the directory hierarchy. This method does not access the file system; the path or its parent may not exist. Furthermore, this method does not eliminate special names such as "." and ".." that may be used in some implementations. On UNIX for example, the parent of "/a/b/c" is "/a/b", and the parent of"x/y/." is "x/y". This method may be used with thenormalize method, to eliminate redundant names, for cases whereshell-like navigation is required.

  If this path has more than one element, and no root component, then this method is equivalent to evaluating the expression:

  Copy

      subpath(0, getNameCount()-1);

  Returns:

  a path representing the path's parent

• getNameCount

  int getNameCount()

  Returns the number of name elements in the path.

  Returns:

  the number of elements in the path, or0 if this path only represents a root component

• getName

  Path getName(int index)

  Returns a name element of this path as aPath object.

  Theindex parameter is the index of the name element to return. The element that isclosest to the root in the directory hierarchy has index0. The element that isfarthest from the root has indexcount-1.

  Parameters:

  index - the index of the element

  Returns:

  the name element

  Throws:

  IllegalArgumentException - ifindex is negative,index is greater than or equal to the number of elements, or this path has zero name elements

• subpath

  Path subpath(int beginIndex, int endIndex)

  Returns a relativePath that is a subsequence of the name elements of this path.

  ThebeginIndex andendIndex parameters specify the subsequence of name elements. The name that isclosest to the root in the directory hierarchy has index0. The name that isfarthest from the root has indexcount-1. The returnedPath object has the name elements that begin atbeginIndex and extend to the element at index endIndex-1.

  Parameters:

  beginIndex - the index of the first element, inclusive

  endIndex - the index of the last element, exclusive

  Returns:

  a newPath object that is a subsequence of the name elements in thisPath

  Throws:

  IllegalArgumentException - ifbeginIndex is negative, or greater than or equal to the number of elements. IfendIndex is less than or equal tobeginIndex, or larger than the number of elements.

• startsWith

  boolean startsWith(Path other)

  Tests if this path starts with the given path.

  This pathstarts with the given path if this path's root componentstarts with the root component of the given path, and this path starts with the same name elements as the given path. If the given path has more name elements than this path thenfalse is returned.

  Whether or not the root component of this path starts with the root component of the given path is file system specific. If this path does not have a root component and the given path has a root component then this path does not start with the given path.

  If the given path is associated with a differentFileSystem to this path thenfalse is returned.

  Parameters:

  other - the given path

  Returns:

  true if this path starts with the given path; otherwisefalse

• startsWith

  default boolean startsWith(String other)

  Tests if this path starts with aPath, constructed by converting the given path string, in exactly the manner specified by thestartsWith(Path) method. On UNIX for example, the path "foo/bar" starts with "foo" and "foo/bar". It does not start with "f" or "fo".

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      startsWith(getFileSystem().getPath(other));

  Parameters:

  other - the given path string

  Returns:

  true if this path starts with the given path; otherwisefalse

  Throws:

  InvalidPathException - If the path string cannot be converted to a Path.

• endsWith

  boolean endsWith(Path other)

  Tests if this path ends with the given path.

  If the given path hasN elements, and no root component, and this path hasN or more elements, then this path ends with the given path if the lastN elements of each path, starting at the element farthest from the root, are equal.

  If the given path has a root component then this path ends with the given path if the root component of this pathends with the root component of the given path, and the corresponding elements of both paths are equal. Whether or not the root component of this path ends with the root component of the given path is file system specific. If this path does not have a root component and the given path has a root component then this path does not end with the given path.

  If the given path is associated with a differentFileSystem to this path thenfalse is returned.

  Parameters:

  other - the given path

  Returns:

  true if this path ends with the given path; otherwisefalse

• endsWith

  default boolean endsWith(String other)

  Tests if this path ends with aPath, constructed by converting the given path string, in exactly the manner specified by theendsWith(Path) method. On UNIX for example, the path "foo/bar" ends with "foo/bar" and "bar". It does not end with "r" or "/bar". Note that trailing separators are not taken into account, and so invoking this method on the Path "foo/bar" with theString "bar/" returnstrue.

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      endsWith(getFileSystem().getPath(other));

  Parameters:

  other - the given path string

  Returns:

  true if this path ends with the given path; otherwisefalse

  Throws:

  InvalidPathException - If the path string cannot be converted to a Path.

• normalize

  Path normalize()

  Returns a path that is this path with redundant name elements eliminated.

  The precise definition of this method is implementation dependent but in general it derives from this path, a path that does not containredundant name elements. In many file systems, the "." and ".." are special names used to indicate the current directory and parent directory. In such file systems all occurrences of "." are considered redundant. If a ".." is preceded by a non-".." name then both names are considered redundant (the process to identify such names is repeated until it is no longer applicable).

  This method does not access the file system; the path may not locate a file that exists. Eliminating ".." and a preceding name from a path may result in the path that locates a different file than the original path. This can arise when the preceding name is a symbolic link.

  Returns:

  the resulting path or this path if it does not contain redundant name elements; an empty path is returned if this path does not have a root component and all name elements are redundant

  See Also:

  • getParent()
  • toRealPath(java.nio.file.LinkOption...)

• resolve

  Path resolve(Path other)

  Resolve the given path against this path.

  If theother parameter is anabsolute path then this method trivially returnsother. Ifother is anempty path then this method trivially returns this path. Otherwise this method considers this path to be a directory and resolves the given path against this path. In the simplest case, the given path does not have aroot component, in which case this methodjoins the given path to this path and returns a resulting path thatends with the given path. Where the given path has a root component then resolution is highly implementation dependent and therefore unspecified.

  Parameters:

  other - the path to resolve against this path

  Returns:

  the resulting path

  See Also:

  • relativize(java.nio.file.Path)

• resolve

  default Path resolve(String other)

  Converts a given path string to aPath and resolves it against thisPath in exactly the manner specified by theresolve method. For example, suppose that the name separator is "/" and a path represents "foo/bar", then invoking this method with the path string "gus" will result in thePath "foo/bar/gus".

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      resolve(getFileSystem().getPath(other));

  Parameters:

  other - the path string to resolve against this path

  Returns:

  the resulting path

  Throws:

  InvalidPathException - if the path string cannot be converted to a Path.

  See Also:

  • FileSystem.getPath(java.lang.String, java.lang.String...)

• resolve

  default Path resolve(Path first,Path... more)

  Resolves a path against this path, and then iteratively resolves any additional paths.

  This method resolvesfirst against thisPath as if by callingresolve(Path). Ifmore has one or more elements then it resolves the first element against the result, then iteratively resolves all subsequent elements. This method returns the result from the final resolve.

  Implementation Requirements:

  The default implementation is equivalent to the result obtained with:

  Copy

      Path result = resolve(first);    for (Path p : more) {        result = result.resolve(p);    }

  Parameters:

  first - the first path to resolve against this path

  more - additional paths to iteratively resolve

  Returns:

  the resulting path

  Since:

  22

  See Also:

  • resolve(Path)

• resolve

  default Path resolve(String first,String... more)

  Converts a path string to a path, resolves that path against this path, and then iteratively performs the same procedure for any additional path strings.

  This method convertsfirst to aPath and resolves thatPath against thisPath as if by callingresolve(String). Ifmore has one or more elements then it converts the first element to a path, resolves that path against the result, then iteratively converts and resolves all subsequent elements. This method returns the result from the final resolve.

  Implementation Requirements:

  The default implementation is equivalent to the result obtained with:

  Copy

  Path result = resolve(first);for (String s : more) {    result = result.resolve(s);}

  Parameters:

  first - the first path string to convert to a path and resolve against this path

  more - additional path strings to be iteratively converted to paths and resolved

  Returns:

  the resulting path

  Throws:

  InvalidPathException - if a path string cannot be converted to a Path.

  Since:

  22

  See Also:

  • resolve(Path,Path...)
  • resolve(String)

• resolveSibling

  default Path resolveSibling(Path other)

  Resolves the given path against this path'sparent path. This is useful where a file name needs to bereplaced with another file name. For example, suppose that the name separator is "/" and a path represents "dir1/dir2/foo", then invoking this method with thePath "bar" will result in the Path "dir1/dir2/bar". If this path does not have a parent path, orother isabsolute, then this method returnsother. Ifother is an empty path then this method returns this path's parent, or where this path doesn't have a parent, the empty path.

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      (getParent() == null) ? other : getParent().resolve(other);

  unlessother == null, in which case aNullPointerException is thrown.

  Parameters:

  other - the path to resolve against this path's parent

  Returns:

  the resulting path

  See Also:

  • resolve(Path)

• resolveSibling

  default Path resolveSibling(String other)

  Converts a given path string to aPath and resolves it against this path'sparent path in exactly the manner specified by theresolveSibling method.

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      resolveSibling(getFileSystem().getPath(other));

  Parameters:

  other - the path string to resolve against this path's parent

  Returns:

  the resulting path

  Throws:

  InvalidPathException - if the path string cannot be converted to a Path.

  See Also:

  • FileSystem.getPath(java.lang.String, java.lang.String...)

• relativize

  Path relativize(Path other)

  Constructs a relative path between this path and a given path.

  Relativization is the inverse ofresolution. This method attempts to construct arelative path that whenresolved against this path, yields a path that locates the same file as the given path. For example, on UNIX, if this path is"/a/b" and the given path is"/a/b/c/d" then the resulting relative path would be"c/d". Where this path and the given path do not have aroot component, then a relative path can be constructed. A relative path cannot be constructed if only one of the paths have a root component. Where both paths have a root component then it is implementation dependent if a relative path can be constructed. If this path and the given path areequal then anempty path is returned.

  For any twonormalized pathsp andq, whereq does not have a root component,

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

  When symbolic links are supported, then whether the resulting path, when resolved against this path, yields a path that can be used to locate thesame file asother is implementation dependent. For example, if this path is"/a/b" and the given path is"/a/x" then the resulting relative path may be "../x". If"b" is a symbolic link then is implementation dependent if"a/b/../x" would locate the same file as"/a/x".

  Parameters:

  other - the path to relativize against this path

  Returns:

  the resulting relative path, or an empty path if both paths are equal

  Throws:

  IllegalArgumentException - ifother is not aPath that can be relativized against this path

• toUri

  URI toUri()

  Returns a URI to represent this path.

  This method constructs an absoluteURI with ascheme equal to the URI scheme that identifies the provider. The exact form of the scheme specific part is highly provider dependent.

  In the case of the default provider, the URI is hierarchical with apath component that is absolute. The query and fragment components are undefined. Whether the authority component is defined or not is implementation dependent. There is no guarantee that theURI may be used to construct ajava.io.File. In particular, if this path represents a Universal Naming Convention (UNC) path, then the UNC server name may be encoded in the authority component of the resulting URI. In the case of the default provider, and the file exists, and it can be determined that the file is a directory, then the resultingURI will end with a slash.

  The default provider provides a similarround-trip guarantee to theFile class. For a givenPathp it is guaranteed that

  Path.of(p.toUri()).equals(p.toAbsolutePath())

  so long as the originalPath, theURI, and the new Path are all created in (possibly different invocations of) the same Java virtual machine. Whether other providers make any guarantees is provider specific and therefore unspecified.

  When a file system is constructed to access the contents of a file as a file system then it is highly implementation specific if the returned URI represents the given path in the file system or it represents acompound URI that encodes the URI of the enclosing file system. A format for compound URIs is not defined in this release; such a scheme may be added in a future release.

  Returns:

  the URI representing this path

  Throws:

  IOError - if an I/O error occurs obtaining the absolute path, or where a file system is constructed to access the contents of a file as a file system, and the URI of the enclosing file system cannot be obtained

• toAbsolutePath

  Path toAbsolutePath()

  Returns aPath object representing the absolute path of this path.

  If this path is alreadyabsolute then this method simply returns this path. Otherwise, this method resolves the path in an implementation dependent manner, typically by resolving the path against a file system default directory. Depending on the implementation, this method may throw an I/O error if the file system is not accessible.

  Returns:

  aPath object representing the absolute path

  Throws:

  IOError - if an I/O error occurs

• toRealPath

  Path toRealPath(LinkOption... options) throwsIOException

  Returns thereal path of an existing file.

  The precise definition of this method is implementation dependent but in general it derives from this path, anabsolute path that locates thesame file as this path, but with name elements that represent the actual name of the directories and the file. For example, where filename comparisons on a file system are case insensitive then the name elements represent the names in their actual case. Additionally, the resulting path has redundant name elements removed.

  If this path is relative then its absolute path is first obtained, as if by invoking thetoAbsolutePath method.

  Theoptions array may be used to indicate how symbolic links are handled. By default, symbolic links are resolved to their final target. If the optionNOFOLLOW_LINKS is present then this method does not resolve symbolic links. Some implementations allow special names such as ".." to refer to the parent directory. When deriving thereal path, and a ".." (or equivalent) is preceded by a non-".." name then an implementation will typically cause both names to be removed. When not resolving symbolic links and the preceding name is a symbolic link then the names are only removed if it is guaranteed that the resulting path will locate the same file as this path.

  Parameters:

  options - options indicating how symbolic links are handled

  Returns:

  an absolute path represent thereal path of the file located by this object

  Throws:

  IOException - if the file does not exist or an I/O error occurs

• toFile

  default File toFile()

  Returns aFile object representing this path. Where this Path is associated with the default provider, then this method is equivalent to returning aFile object constructed with theString representation of this path.

  If this path was created by invoking theFiletoPath method then there is no guarantee that the File object returned by this method isequal to the originalFile.

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

      new File(toString());

  if theFileSystem which created thisPath is the default file system; otherwise anUnsupportedOperationException is thrown.

  Returns:

  aFile object representing this path

  Throws:

  UnsupportedOperationException - if thisPath is not associated with the default provider

• register

  WatchKey register(WatchService watcher,WatchEvent.Kind<?>[] events,WatchEvent.Modifier... modifiers) throwsIOException

  Registers the file located by this path with a watch service.

  In this release, this path locates a directory that exists. The directory is registered with the watch service so that entries in the directory can be watched. Theevents parameter is the events to register and may contain the following events:

  • ENTRY_CREATE - entry created or moved into the directory
  • ENTRY_DELETE - entry deleted or moved out of the directory
  • ENTRY_MODIFY - entry in directory was modified

  Thecontext for these events is the relative path between the directory located by this path, and the path that locates the directory entry that is created, deleted, or modified.

  The set of events may include additional implementation specific event that are not defined by the enumStandardWatchEventKinds

  Themodifiers parameter specifiesmodifiers that qualify how the directory is registered. This release does not define anystandard modifiers. It may contain implementation specific modifiers.

  Where a file is registered with a watch service by means of a symbolic link then it is implementation specific if the watch continues to depend on the existence of the symbolic link after it is registered.

  Specified by:

  register in interface Watchable

  Parameters:

  watcher - the watch service to which this object is to be registered

  events - the events for which this object should be registered

  modifiers - the modifiers, if any, that modify how the object is registered

  Returns:

  a key representing the registration of this object with the given watch service

  Throws:

  UnsupportedOperationException - if unsupported events or modifiers are specified

  IllegalArgumentException - if an invalid combination of events or modifiers is specified

  ClosedWatchServiceException - if the watch service is closed

  NotDirectoryException - if the file is registered to watch the entries in a directory and the file is not a directory(optional specific exception)

  IOException - if an I/O error occurs

• register

  default WatchKey register(WatchService watcher,WatchEvent.Kind<?>... events) throwsIOException

  Registers the file located by this path with a watch service.

  An invocation of this method behaves in exactly the same way as the invocation

  Copy

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

  Usage Example: Suppose we wish to register a directory for entry create, delete, and modify events:

  Copy

      Path dir = ...    WatchService watcher = ...    WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);

  Specified by:

  register in interface Watchable

  Implementation Requirements:

  The default implementation is equivalent for this path to:

  Copy

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

  Parameters:

  watcher - The watch service to which this object is to be registered

  events - The events for which this object should be registered

  Returns:

  A key representing the registration of this object with the given watch service

  Throws:

  UnsupportedOperationException - If unsupported events are specified

  IllegalArgumentException - If an invalid combination of events is specified

  ClosedWatchServiceException - If the watch service is closed

  NotDirectoryException - If the file is registered to watch the entries in a directory and the file is not a directory(optional specific exception)

  IOException - If an I/O error occurs

• iterator

  default Iterator<Path> iterator()

  Returns an iterator over the name elements of this path.

  The first element returned by the iterator represents the name element that is closest to the root in the directory hierarchy, the second element is the next closest, and so on. The last element returned is the name of the file or directory denoted by this path. Theroot component, if present, is not returned by the iterator.

  Specified by:

  iterator in interface Iterable<Path>

  Implementation Requirements:

  The default implementation returns anIterator<Path> which, for this path, traverses thePaths returned bygetName(index), whereindex ranges from zero togetNameCount() - 1, inclusive.

  Returns:

  an iterator over the name elements of this path

• compareTo

  int compareTo(Path other)

  Compares two abstract paths lexicographically. The ordering defined by this method is provider specific, and in the case of the default provider, platform specific. This method does not access the file system and neither file is required to exist.

  This method may not be used to compare paths that are associated with different file system providers.

  Specified by:

  compareTo in interface Comparable<Path>

  Parameters:

  other - the path compared to this path.

  Returns:

  zero if the argument isequal to this path, a value less than zero if this path is lexicographically less than the argument, or a value greater than zero if this path is lexicographically greater than the argument

  Throws:

  ClassCastException - if the paths are associated with different providers

• equals

  boolean equals(Object other)

  Tests this path for equality with the given object.

  If the given object is not a Path, or is a Path associated with a differentFileSystem, then this method returnsfalse.

  Whether or not two path are equal depends on the file system implementation. In some cases the paths are compared without regard to case, and others are case sensitive. This method does not access the file system and the file is not required to exist. Where required, theisSameFile method may be used to check if two paths locate the same file.

  This method satisfies the general contract of theObject.equals method.

  Overrides:

  equals in class Object

  Parameters:

  other - the object to which this object is to be compared

  Returns:

  true if, and only if, the given object is aPath that is identical to thisPath

  See Also:

  • Object.hashCode()
  • HashMap

• hashCode

  int hashCode()

  Computes a hash code for this path.

  The hash code is based upon the components of the path, and satisfies the general contract of theObject.hashCode method.

  Overrides:

  hashCode in class Object

  Returns:

  the hash-code value for this path

  See Also:

  • Object.equals(java.lang.Object)
  • System.identityHashCode(java.lang.Object)

• toString

  String toString()

  Returns the string representation of this path.

  If this path was created by converting a path string using thegetPath method then the path string returned by this method may differ from the original String used to create the path.

  The returned path string uses the default nameseparator to separate names in the path.

  Overrides:

  toString in class Object

  Returns:

  the string representation of this path