public interface Path extends Comparable<Path>, Iterable<Path>
A Path
represents a path that is hierarchical and composed of a
sequence of directory and file name elements separated by a special separator
or delimiter. A root component, that identifies a file system
hierarchy, may also be present. The name element that is farthest
from the root of the directory hierarchy is the name of a file or directory.
The other name elements are directory names. A Path
can represent a
root, a root and a sequence of names, or simply one or more name elements.
A Path
is considered to be an empty path if it consists
solely of one name element that is empty. Accessing a file using an
empty path is equivalent to accessing the default directory of the
file system. Path
defines the getFileName
,
getParent
, getRoot
, and subpath
methods to access the path components or a subsequence of its name
elements.
In addition to accessing the components of a path, a Path
also
defines the resolve
and resolveSibling
methods to combine paths. The relativize
method that can be used to construct a relative path between two paths.
Paths can be compared
, and tested against each other using
the startsWith
and endsWith
methods.
Paths may be used with the Files
class to operate on files,
directories, and other types of files. For example, suppose we want a Reader
to read text from a file "access.log
". The
file is located in a directory "logs
" relative to the current working
directory and is UTF-8 encoded.
Path path = FileSystems.getDefault().getPath("logs", "access.log"); InputStream is = Files.newInputStream(path); Reader r = new InputStreamReader(is, "utf-8");
Paths associated with the default FileSystem are generally interoperable with the Generic Connection Framework FileConnection.
Implementations of this interface are immutable and safe for use by multiple concurrent threads.
Modifier and Type | Method and Description |
---|---|
int |
compareTo(Path other)
Compares two abstract paths lexicographically.
|
boolean |
endsWith(Path other)
Tests if this path ends with the given path.
|
boolean |
endsWith(String other)
Tests if this path ends with a
Path , constructed by converting
the given path string, in exactly the manner specified by the endsWith(Path) method. |
boolean |
equals(Object other)
Tests this path for equality with the given object.
|
Path |
getFileName()
Returns the name of the file or directory denoted by this path as a
Path object. |
FileSystem |
getFileSystem()
Returns the file system that created this object.
|
Path |
getName(int index)
Returns a name element of this path as a
Path object. |
int |
getNameCount()
Returns the number of name elements in the path.
|
Path |
getParent()
Returns the parent path, or
null if this path does not
have a parent. |
Path |
getRoot()
Returns the root component of this path as a
Path object,
or null if this path does not have a root component. |
int |
hashCode()
Computes a hash code for this path.
|
boolean |
isAbsolute()
Tells whether or not this path is absolute.
|
Iterator<Path> |
iterator()
Returns an iterator over the name elements of this path.
|
Path |
normalize()
Returns a path that is this path with redundant name elements eliminated.
|
Path |
relativize(Path other)
Constructs a relative path between this path and a given path.
|
Path |
resolve(Path other)
Resolve the given path against this path.
|
Path |
resolve(String other)
Converts a given path string to a
Path and resolves it against
this Path in exactly the manner specified by the resolve method. |
Path |
resolveSibling(Path other)
Resolves the given path against this path's
parent
path. |
Path |
resolveSibling(String other)
Converts a given path string to a
Path and resolves it against
this path's parent path in exactly the manner
specified by the resolveSibling method. |
boolean |
startsWith(Path other)
Tests if this path starts with the given path.
|
boolean |
startsWith(String other)
Tests if this path starts with a
Path , constructed by converting
the given path string, in exactly the manner specified by the startsWith(Path) method. |
Path |
subpath(int beginIndex,
int endIndex)
Returns a relative
Path that is a subsequence of the name
elements of this path. |
Path |
toAbsolutePath()
Returns a
Path object representing the absolute path of this
path. |
Path |
toRealPath(LinkOption... options)
Returns the real path of an existing file.
|
String |
toString()
Returns the string representation of this path.
|
int compareTo(Path other)
This method may not be used to compare paths that are associated with different file system providers.
compareTo
in interface Comparable<Path>
other
- the path compared to this path.equal
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 argumentClassCastException
- if the paths are associated with different providersboolean endsWith(Path other)
If the given path has N elements, and no root component, and this path has N or more elements, then this path ends with the given path if the last N 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 path ends 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 different FileSystem
to this path then false
is returned.
other
- the given pathtrue
if this path ends with the given path; otherwise
false
boolean endsWith(String other)
Path
, constructed by converting
the given path string, in exactly the manner specified by the endsWith(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 the String
"bar/
" returns
true
.other
- the given path stringtrue
if this path ends with the given path; otherwise
false
InvalidPathException
- If the path string cannot be converted to a Path.boolean equals(Object other)
If the given object is not a Path, or is a Path associated with a
different FileSystem
, then this method returns false
.
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, the
isSameFile
method may be used to check if two
paths locate the same file.
This method satisfies the general contract of the Object.equals
method.
equals
in class Object
other
- the object to which this object is to be comparedtrue
if, and only if, the given object is a Path
that is identical to this Path
Object.hashCode()
,
HashMap
Path getFileName()
Path
object. The file name is the farthest element from
the root in the directory hierarchy.null
if this path has zero elementsFileSystem getFileSystem()
Path getName(int index)
Path
object.
The index
parameter is the index of the name element to return.
The element that is closest to the root in the directory hierarchy
has index 0
. The element that is farthest from the root
has index count
-1
.
index
- the index of the elementIllegalArgumentException
- if index
is negative, index
is greater than or
equal to the number of elements, or this path has zero name
elementsint getNameCount()
0
if this path
only represents a root componentPath getParent()
null
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 the
farthest 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 the normalize
method, to eliminate redundant names, for cases where
shell-like navigation is required.
If this path has one or more elements, and no root component, then this method is equivalent to evaluating the expression:
subpath(0, getNameCount()-1);
Path getRoot()
Path
object,
or null
if this path does not have a root component.null
int hashCode()
The hash code is based upon the components of the path, and
satisfies the general contract of the Object.hashCode
method.
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
boolean isAbsolute()
An absolute path is complete in that it doesn't need to be combined with other path information in order to locate a file.
true
if, and only if, this path is absoluteIterator<Path> iterator()
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. The root
component, if present, is not returned by the iterator.
Path normalize()
The precise definition of this method is implementation dependent but
in general it derives from this path, a path that does not contain
redundant 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.
getParent()
,
toRealPath(java.nio.file.LinkOption...)
Path relativize(Path other)
Relativization is the inverse of resolution
.
This method attempts to construct a relative
path
that when resolved
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 a root
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 are
equal
then an empty path is returned.
For any two normalized
paths p and
q, where q 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
the same
file as other
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"
.
other
- the path to relativize against this pathIllegalArgumentException
- if other
is not a Path
that can be relativized
against this pathPath resolve(Path other)
If the other
parameter is an absolute
path then this method trivially returns other
. If other
is an empty 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 a root
component, in which case this method
joins the given path to this path and returns a resulting path
that ends
with the given path. Where the given path has
a root component then resolution is highly implementation dependent and
therefore unspecified.
other
- the path to resolve against this pathrelativize(java.nio.file.Path)
Path resolve(String other)
Path
and resolves it against
this Path
in exactly the manner specified by the resolve
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
the Path
"foo/bar/gus
".other
- the path string to resolve against this pathInvalidPathException
- if the path string cannot be converted to a Path.FileSystem.getPath(java.lang.String, java.lang.String...)
Path resolveSibling(Path other)
parent
path. This is useful where a file name needs to be replaced with
another file name. For example, suppose that the name separator is
"/
" and a path represents "dir1/dir2/foo
", then invoking
this method with the Path
"bar
" will result in the Path
"dir1/dir2/bar
". If this path does not have a parent path,
or other
is absolute
, then this method
returns other
. If other
is an empty path then this method
returns this path's parent, or where this path doesn't have a parent, the
empty path.other
- the path to resolve against this path's parentresolve(Path)
Path resolveSibling(String other)
Path
and resolves it against
this path's parent
path in exactly the manner
specified by the resolveSibling
method.other
- the path string to resolve against this path's parentInvalidPathException
- if the path string cannot be converted to a Path.FileSystem.getPath(java.lang.String, java.lang.String...)
boolean startsWith(Path other)
This path starts with the given path if this path's root
component starts 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 then false
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 different FileSystem
to this path then false
is returned.
other
- the given pathtrue
if this path starts with the given path; otherwise
false
boolean startsWith(String other)
Path
, constructed by converting
the given path string, in exactly the manner specified by the startsWith(Path)
method. On UNIX for example, the path
"foo/bar
" starts with "foo
" and "foo/bar
". It
does not start with "f
" or "fo
".other
- the given path stringtrue
if this path starts with the given path; otherwise
false
InvalidPathException
- If the path string cannot be converted to a Path.Path subpath(int beginIndex, int endIndex)
Path
that is a subsequence of the name
elements of this path.
The beginIndex
and endIndex
parameters specify the
subsequence of name elements. The name that is closest to the root
in the directory hierarchy has index 0
. The name that is
farthest from the root has index count
-1
. The returned Path
object has the name elements
that begin at beginIndex
and extend to the element at index endIndex-1
.
beginIndex
- the index of the first element, inclusiveendIndex
- the index of the last element, exclusivePath
object that is a subsequence of the name
elements in this Path
IllegalArgumentException
- if beginIndex
is negative, or greater than or equal to
the number of elements. If endIndex
is less than or
equal to beginIndex
, or larger than the number of elements.Path toAbsolutePath()
Path
object representing the absolute path of this
path.
If this path is already absolute
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 error if the file system is not accessible.
Path
object representing the absolute pathError
- if an I/O error occursPath toRealPath(LinkOption... options) throws IOException
The precise definition of this method is implementation dependent but
in general it derives from this path, an absolute
path that locates the same
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 the toAbsolutePath
method.
The options
array may be used to indicate how symbolic links
are handled. By default, symbolic links are resolved to their final
target. If the option NOFOLLOW_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 the real 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 guaranteed that the resulting path
will locate the same file as this path.
options
- options indicating how symbolic links are handledIOException
- if the file does not exist or an I/O error occursString toString()
If this path was created by converting a path string using the
getPath
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 name separator
to separate names in the path.
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.