Return a
Stream that is lazily populated with
Path by walking the file tree rooted at a given starting file. The
file tree is traversed
depth-first, the elements in the stream
are
Path objects that are obtained as if by
Path#resolve(Path) the relative path against
start.
The
stream walks the file tree as elements are consumed.
The
Stream returned is guaranteed to have at least one
element, the starting file itself. For each file visited, the stream
attempts to read its
BasicFileAttributes. If the file is a
directory and can be opened successfully, entries in the directory, and
their descendants will follow the directory in the stream as
they are encountered. When all entries have been visited, then the
directory is closed. The file tree walk then continues at the next
sibling of the directory.
The stream is weakly consistent. It does not freeze the
file tree while iterating, so it may (or may not) reflect updates to
the file tree that occur after returned from this method.
By default, symbolic links are not automatically followed by this
method. If the
options parameter contains the
FileVisitOption#FOLLOW_LINKS option then symbolic links are
followed. When following links, and the attributes of the target cannot
be read, then this method attempts to get the
BasicFileAttributesof the link.
If the
options parameter contains the
FileVisitOption#FOLLOW_LINKS option then the stream keeps
track of directories visited so that cycles can be detected. A cycle
arises when there is an entry in a directory that is an ancestor of the
directory. Cycle detection is done by recording the
java.nio.file.attribute.BasicFileAttributes#fileKey of directories,
or if file keys are not available, by invoking the
#isSameFile method to test if a directory is the same file as an
ancestor. When a cycle is detected it is treated as an I/O error with
an instance of
FileSystemLoopException.
The
maxDepth parameter is the maximum number of levels of
directories to visit. A value of
0 means that only the starting
file is visited, unless denied by the security manager. A value of
Integer#MAX_VALUE may be used to indicate that all
levels should be visited.
When a security manager is installed and it denies access to a file
(or directory), then it is ignored and not included in the stream.
The returned stream encapsulates one or more
DirectoryStreams.
If timely disposal of file system resources is required, the
try-with-resources construct should be used to ensure that the
stream's
Stream#close method is invoked after the stream
operations are completed. Operating on a closed stream will result in an
java.lang.IllegalStateException.
If an
IOException is thrown when accessing the directory
after this method has returned, it is wrapped in an
UncheckedIOException which will be thrown from the method that caused
the access to take place.