< prev index next >

src/java.base/share/classes/java/nio/file/Files.java

Print this page




  57 import java.nio.file.attribute.PosixFilePermission;
  58 import java.nio.file.attribute.UserPrincipal;
  59 import java.nio.file.spi.FileSystemProvider;
  60 import java.nio.file.spi.FileTypeDetector;
  61 import java.security.AccessController;
  62 import java.security.PrivilegedAction;
  63 import java.util.ArrayList;
  64 import java.util.Arrays;
  65 import java.util.Collections;
  66 import java.util.EnumSet;
  67 import java.util.HashSet;
  68 import java.util.Iterator;
  69 import java.util.List;
  70 import java.util.Map;
  71 import java.util.Objects;
  72 import java.util.ServiceLoader;
  73 import java.util.Set;
  74 import java.util.Spliterator;
  75 import java.util.Spliterators;
  76 import java.util.function.BiPredicate;

  77 import java.util.stream.Stream;
  78 import java.util.stream.StreamSupport;
  79 
  80 /**
  81  * This class consists exclusively of static methods that operate on files,
  82  * directories, or other types of files.
  83  *
  84  * <p> In most cases, the methods defined here will delegate to the associated
  85  * file system provider to perform the file operations.
  86  *
  87  * @since 1.7
  88  */
  89 
  90 public final class Files {
  91     private Files() { }
  92 
  93     /**
  94      * Returns the {@code FileSystemProvider} to delegate to.
  95      */
  96     private static FileSystemProvider provider(Path path) {


3553      * arises when there is an entry in a directory that is an ancestor of the
3554      * directory. Cycle detection is done by recording the {@link
3555      * java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
3556      * or if file keys are not available, by invoking the {@link #isSameFile
3557      * isSameFile} method to test if a directory is the same file as an
3558      * ancestor. When a cycle is detected it is treated as an I/O error with
3559      * an instance of {@link FileSystemLoopException}.
3560      *
3561      * <p> The {@code maxDepth} parameter is the maximum number of levels of
3562      * directories to visit. A value of {@code 0} means that only the starting
3563      * file is visited, unless denied by the security manager. A value of
3564      * {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
3565      * levels should be visited.
3566      *
3567      * <p> When a security manager is installed and it denies access to a file
3568      * (or directory), then it is ignored and not included in the stream.
3569      *
3570      * <p> The returned stream contains references to one or more open directories.
3571      * The directories are closed by closing the stream.
3572      *
3573      * <p> If an {@link IOException} is thrown when accessing the directory



















































































































3574      * after this method has returned, it is wrapped in an {@link
3575      * UncheckedIOException} which will be thrown from the method that caused
3576      * the access to take place.
3577      *
3578      * @apiNote
3579      * This method must be used within a try-with-resources statement or similar
3580      * control structure to ensure that the stream's open directories are closed
3581      * promptly after the stream's operations have completed.
3582      *
3583      * @param   start
3584      *          the starting file
3585      * @param   maxDepth
3586      *          the maximum number of directory levels to visit
3587      * @param   options
3588      *          options to configure the traversal
3589      *
3590      * @return  the {@link Stream} of {@link Path}
3591      *
3592      * @throws  IllegalArgumentException
3593      *          if the {@code maxDepth} parameter is negative




3594      * @throws  SecurityException
3595      *          If the security manager denies access to the starting file.
3596      *          In the case of the default provider, the {@link
3597      *          SecurityManager#checkRead(String) checkRead} method is invoked
3598      *          to check read access to the directory.
3599      * @throws  IOException
3600      *          if an I/O error is thrown when accessing the starting file.
3601      * @since   1.8
3602      */
3603     public static Stream<Path> walk(Path start,
3604                                     int maxDepth,
3605                                     FileVisitOption... options)
3606         throws IOException
3607     {
3608         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options);
3609         try {
3610             Spliterator<FileTreeWalker.Event> spliterator =
3611                 Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT);
3612             return StreamSupport.stream(spliterator, false)
3613                                 .onClose(iterator::close)
3614                                 .map(entry -> entry.file());
3615         } catch (Error|RuntimeException e) {
3616             iterator.close();
3617             throw e;
3618         }
3619     }
3620 
3621     /**
3622      * Return a {@code Stream} that is lazily populated with {@code
3623      * Path} by walking the file tree rooted at a given starting file.  The
3624      * file tree is traversed <em>depth-first</em>, the elements in the stream
3625      * are {@link Path} objects that are obtained as if by {@link
3626      * Path#resolve(Path) resolving} the relative path against {@code start}.
3627      *
3628      * <p> This method works as if invoking it were equivalent to evaluating the
3629      * expression:
3630      * <blockquote><pre>
3631      * walk(start, Integer.MAX_VALUE, options)
3632      * </pre></blockquote>
3633      * In other words, it visits all levels of the file tree.
3634      *
3635      * <p> The returned stream contains references to one or more open directories.
3636      * The directories are closed by closing the stream.
3637      *
3638      * @apiNote
3639      * This method must be used within a try-with-resources statement or similar
3640      * control structure to ensure that the stream's open directories are closed
3641      * promptly after the stream's operations have completed.
3642      *
3643      * @param   start
3644      *          the starting file
3645      * @param   options
3646      *          options to configure the traversal
3647      *
3648      * @return  the {@link Stream} of {@link Path}
3649      *




3650      * @throws  SecurityException
3651      *          If the security manager denies access to the starting file.
3652      *          In the case of the default provider, the {@link
3653      *          SecurityManager#checkRead(String) checkRead} method is invoked
3654      *          to check read access to the directory.
3655      * @throws  IOException
3656      *          if an I/O error is thrown when accessing the starting file.
3657      *
3658      * @see     #walk(Path, int, FileVisitOption...)
3659      * @since   1.8
3660      */
3661     public static Stream<Path> walk(Path start, FileVisitOption... options) throws IOException {
3662         return walk(start, Integer.MAX_VALUE, options);
3663     }
3664 
3665     /**
3666      * Return a {@code Stream} that is lazily populated with {@code
3667      * Path} by searching for files in a file tree rooted at a given starting
3668      * file.
3669      *
3670      * <p> This method walks the file tree in exactly the manner specified by
3671      * the {@link #walk walk} method. For each file encountered, the given
3672      * {@link BiPredicate} is invoked with its {@link Path} and {@link
3673      * BasicFileAttributes}. The {@code Path} object is obtained as if by
3674      * {@link Path#resolve(Path) resolving} the relative path against {@code
3675      * start} and is only included in the returned {@link Stream} if
3676      * the {@code BiPredicate} returns true. Compare to calling {@link
3677      * java.util.stream.Stream#filter filter} on the {@code Stream}
3678      * returned by {@code walk} method, this method may be more efficient by
3679      * avoiding redundant retrieval of the {@code BasicFileAttributes}.
3680      *
3681      * <p> The returned stream contains references to one or more open directories.
3682      * The directories are closed by closing the stream.
3683      *
3684      * <p> If an {@link IOException} is thrown when accessing the directory

























































































3685      * after returned from this method, it is wrapped in an {@link
3686      * UncheckedIOException} which will be thrown from the method that caused
3687      * the access to take place.
3688      *
3689      * @apiNote
3690      * This method must be used within a try-with-resources statement or similar
3691      * control structure to ensure that the stream's open directories are closed
3692      * promptly after the stream's operations have completed.
3693      *
3694      * @param   start
3695      *          the starting file
3696      * @param   maxDepth
3697      *          the maximum number of directory levels to search
3698      * @param   matcher
3699      *          the function used to decide whether a file should be included
3700      *          in the returned stream
3701      * @param   options
3702      *          options to configure the traversal
3703      *
3704      * @return  the {@link Stream} of {@link Path}
3705      *
3706      * @throws  IllegalArgumentException
3707      *          if the {@code maxDepth} parameter is negative




3708      * @throws  SecurityException
3709      *          If the security manager denies access to the starting file.
3710      *          In the case of the default provider, the {@link
3711      *          SecurityManager#checkRead(String) checkRead} method is invoked
3712      *          to check read access to the directory.
3713      * @throws  IOException
3714      *          if an I/O error is thrown when accessing the starting file.
3715      *

3716      * @see     #walk(Path, int, FileVisitOption...)
3717      * @since   1.8
3718      */
3719     public static Stream<Path> find(Path start,
3720                                     int maxDepth,
3721                                     BiPredicate<Path, BasicFileAttributes> matcher,
3722                                     FileVisitOption... options)
3723         throws IOException
3724     {
3725         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options);
3726         try {
3727             Spliterator<FileTreeWalker.Event> spliterator =
3728                 Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT);
3729             return StreamSupport.stream(spliterator, false)
3730                                 .onClose(iterator::close)
3731                                 .filter(entry -> matcher.test(entry.file(), entry.attributes()))
3732                                 .map(entry -> entry.file());
3733         } catch (Error|RuntimeException e) {
3734             iterator.close();
3735             throw e;
3736         }
3737     }
3738 
3739 
3740     /**
3741      * Read all lines from a file as a {@code Stream}. Unlike {@link
3742      * #readAllLines(Path, Charset) readAllLines}, this method does not read
3743      * all lines into a {@code List}, but instead populates lazily as the stream
3744      * is consumed.
3745      *
3746      * <p> Bytes from the file are decoded into characters using the specified
3747      * charset and the same line terminators as specified by {@code
3748      * readAllLines} are supported.
3749      *
3750      * <p> The returned stream contains a reference to an open file. The file
3751      * is closed by closing the stream.
3752      *
3753      * <p> The file contents should not be modified during the execution of the
3754      * terminal stream operation. Otherwise, the result of the terminal stream
3755      * operation is undefined.




  57 import java.nio.file.attribute.PosixFilePermission;
  58 import java.nio.file.attribute.UserPrincipal;
  59 import java.nio.file.spi.FileSystemProvider;
  60 import java.nio.file.spi.FileTypeDetector;
  61 import java.security.AccessController;
  62 import java.security.PrivilegedAction;
  63 import java.util.ArrayList;
  64 import java.util.Arrays;
  65 import java.util.Collections;
  66 import java.util.EnumSet;
  67 import java.util.HashSet;
  68 import java.util.Iterator;
  69 import java.util.List;
  70 import java.util.Map;
  71 import java.util.Objects;
  72 import java.util.ServiceLoader;
  73 import java.util.Set;
  74 import java.util.Spliterator;
  75 import java.util.Spliterators;
  76 import java.util.function.BiPredicate;
  77 import java.util.function.Consumer;
  78 import java.util.stream.Stream;
  79 import java.util.stream.StreamSupport;
  80 
  81 /**
  82  * This class consists exclusively of static methods that operate on files,
  83  * directories, or other types of files.
  84  *
  85  * <p> In most cases, the methods defined here will delegate to the associated
  86  * file system provider to perform the file operations.
  87  *
  88  * @since 1.7
  89  */
  90 
  91 public final class Files {
  92     private Files() { }
  93 
  94     /**
  95      * Returns the {@code FileSystemProvider} to delegate to.
  96      */
  97     private static FileSystemProvider provider(Path path) {


3554      * arises when there is an entry in a directory that is an ancestor of the
3555      * directory. Cycle detection is done by recording the {@link
3556      * java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
3557      * or if file keys are not available, by invoking the {@link #isSameFile
3558      * isSameFile} method to test if a directory is the same file as an
3559      * ancestor. When a cycle is detected it is treated as an I/O error with
3560      * an instance of {@link FileSystemLoopException}.
3561      *
3562      * <p> The {@code maxDepth} parameter is the maximum number of levels of
3563      * directories to visit. A value of {@code 0} means that only the starting
3564      * file is visited, unless denied by the security manager. A value of
3565      * {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
3566      * levels should be visited.
3567      *
3568      * <p> When a security manager is installed and it denies access to a file
3569      * (or directory), then it is ignored and not included in the stream.
3570      *
3571      * <p> The returned stream contains references to one or more open directories.
3572      * The directories are closed by closing the stream.
3573      *
3574      * <p> If an {@link IOException} is thrown when accessing a file or directory,
3575      * it is passed to given {@code ioExceptionHandler}.
3576      * If this handler throws an unchecked exception it will be thrown from the
3577      * method that caused the access to take place. If the handler doesn't throw
3578      * any exception then the elements of the stream that caused the IOException(s)
3579      * by accessing them are absent from the stream. This may include entire subtrees
3580      * rooted at directories that caused IOException(s) by accessing them.
3581      * The 1st access to starting file takes place in this method.
3582      *
3583      * @apiNote
3584      * This method must be used within a try-with-resources statement or similar
3585      * control structure to ensure that the stream's open directories are closed
3586      * promptly after the stream's operations have completed.
3587      *
3588      * @param   start
3589      *          the starting file
3590      * @param   maxDepth
3591      *          the maximum number of directory levels to visit
3592      * @param   ioExceptionHandler
3593      *          the consumer used to handle any IOException(s) that are thrown
3594      *          while walking the file tree
3595      * @param   options
3596      *          options to configure the traversal
3597      *
3598      * @return  the {@link Stream} of {@link Path}
3599      *
3600      * @throws  IllegalArgumentException
3601      *          if the {@code maxDepth} parameter is negative
3602      * @throws  NullPointerException
3603      *          if {@code start} or {@code ioExceptionHandler}
3604      *          or {@code options} is {@code null} or the options array contains
3605      *          a {@code null} element
3606      * @throws  SecurityException
3607      *          If the security manager denies access to the starting file.
3608      *          In the case of the default provider, the {@link
3609      *          SecurityManager#checkRead(String) checkRead} method is invoked
3610      *          to check read access to the directory.
3611      * @since   1.9
3612      * @see #walk(Path, int, FileVisitOption...)
3613      */
3614     public static Stream<Path> walk(Path start,
3615                                     int maxDepth,
3616                                     Consumer<IOException> ioExceptionHandler,
3617                                     FileVisitOption... options)
3618     {
3619         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth,
3620                                                          ioExceptionHandler,
3621                                                          options);
3622         try {
3623             Spliterator<FileTreeWalker.Event> spliterator =
3624                 Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT);
3625             return StreamSupport.stream(spliterator, false)
3626                                 .onClose(iterator::close)
3627                                 .map(entry -> entry.file());
3628         } catch (Throwable t) {
3629             try {
3630                 iterator.close();
3631             } catch (Throwable ct) {
3632                 t.addSuppressed(ct);
3633             }
3634             throw t;
3635         }
3636     }
3637 
3638     /**
3639      * Return a {@code Stream} that is lazily populated with {@code
3640      * Path} by walking the file tree rooted at a given starting file.  The
3641      * file tree is traversed <em>depth-first</em>, the elements in the stream
3642      * are {@link Path} objects that are obtained as if by {@link
3643      * Path#resolve(Path) resolving} the relative path against {@code start}.
3644      *
3645      * <p> The {@code stream} walks the file tree as elements are consumed.
3646      * The {@code Stream} returned is guaranteed to have at least one
3647      * element, the starting file itself. For each file visited, the stream
3648      * attempts to read its {@link BasicFileAttributes}. If the file is a
3649      * directory and can be opened successfully, entries in the directory, and
3650      * their <em>descendants</em> will follow the directory in the stream as
3651      * they are encountered. When all entries have been visited, then the
3652      * directory is closed. The file tree walk then continues at the next
3653      * <em>sibling</em> of the directory.
3654      *
3655      * <p> The stream is <i>weakly consistent</i>. It does not freeze the
3656      * file tree while iterating, so it may (or may not) reflect updates to
3657      * the file tree that occur after returned from this method.
3658      *
3659      * <p> By default, symbolic links are not automatically followed by this
3660      * method. If the {@code options} parameter contains the {@link
3661      * FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then symbolic links are
3662      * followed. When following links, and the attributes of the target cannot
3663      * be read, then this method attempts to get the {@code BasicFileAttributes}
3664      * of the link.
3665      *
3666      * <p> If the {@code options} parameter contains the {@link
3667      * FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then the stream keeps
3668      * track of directories visited so that cycles can be detected. A cycle
3669      * arises when there is an entry in a directory that is an ancestor of the
3670      * directory. Cycle detection is done by recording the {@link
3671      * java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
3672      * or if file keys are not available, by invoking the {@link #isSameFile
3673      * isSameFile} method to test if a directory is the same file as an
3674      * ancestor. When a cycle is detected it is treated as an I/O error with
3675      * an instance of {@link FileSystemLoopException}.
3676      *
3677      * <p> The {@code maxDepth} parameter is the maximum number of levels of
3678      * directories to visit. A value of {@code 0} means that only the starting
3679      * file is visited, unless denied by the security manager. A value of
3680      * {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
3681      * levels should be visited.
3682      *
3683      * <p> When a security manager is installed and it denies access to a file
3684      * (or directory), then it is ignored and not included in the stream.
3685      *
3686      * <p> The returned stream contains references to one or more open directories.
3687      * The directories are closed by closing the stream.
3688      *
3689      * <p> If an {@link IOException} is thrown when accessing a file or directory
3690      * after this method has returned, it is wrapped in an {@link
3691      * UncheckedIOException} which will be thrown from the method that caused
3692      * the access to take place.
3693      *
3694      * @apiNote
3695      * This method must be used within a try-with-resources statement or similar
3696      * control structure to ensure that the stream's open directories are closed
3697      * promptly after the stream's operations have completed.
3698      *
3699      * @param   start
3700      *          the starting file
3701      * @param   maxDepth
3702      *          the maximum number of directory levels to visit
3703      * @param   options
3704      *          options to configure the traversal
3705      *
3706      * @return  the {@link Stream} of {@link Path}
3707      *
3708      * @throws  IllegalArgumentException
3709      *          if the {@code maxDepth} parameter is negative
3710      * @throws  NullPointerException
3711      *          if {@code start} or {@code options}
3712      *          is {@code null} or the options array contains
3713      *          a {@code null} element
3714      * @throws  SecurityException
3715      *          If the security manager denies access to the starting file.
3716      *          In the case of the default provider, the {@link
3717      *          SecurityManager#checkRead(String) checkRead} method is invoked
3718      *          to check read access to the directory.
3719      * @throws  IOException
3720      *          if an I/O error is thrown when accessing the starting file.
3721      * @since   1.8
3722      */
3723     public static Stream<Path> walk(Path start,
3724                                     int maxDepth,
3725                                     FileVisitOption... options)
3726         throws IOException
3727     {

3728         try {
3729             return walk(start, maxDepth,
3730                         ioe -> { throw new UncheckedIOException(ioe); },
3731                         options);
3732         } catch (UncheckedIOException uioe) {
3733             throw uioe.getCause();



3734         }
3735     }
3736 
3737     /**
3738      * Return a {@code Stream} that is lazily populated with {@code
3739      * Path} by walking the file tree rooted at a given starting file.  The
3740      * file tree is traversed <em>depth-first</em>, the elements in the stream
3741      * are {@link Path} objects that are obtained as if by {@link
3742      * Path#resolve(Path) resolving} the relative path against {@code start}.
3743      *
3744      * <p> This method works as if invoking it were equivalent to evaluating the
3745      * expression:
3746      * <blockquote><pre>
3747      * walk(start, Integer.MAX_VALUE, options)
3748      * </pre></blockquote>
3749      * In other words, it visits all levels of the file tree.
3750      *
3751      * <p> The returned stream contains references to one or more open directories.
3752      * The directories are closed by closing the stream.
3753      *
3754      * @apiNote
3755      * This method must be used within a try-with-resources statement or similar
3756      * control structure to ensure that the stream's open directories are closed
3757      * promptly after the stream's operations have completed.
3758      *
3759      * @param   start
3760      *          the starting file
3761      * @param   options
3762      *          options to configure the traversal
3763      *
3764      * @return  the {@link Stream} of {@link Path}
3765      *
3766      * @throws  NullPointerException
3767      *          if {@code start} or {@code options}
3768      *          is {@code null} or the options array contains
3769      *          a {@code null} element
3770      * @throws  SecurityException
3771      *          If the security manager denies access to the starting file.
3772      *          In the case of the default provider, the {@link
3773      *          SecurityManager#checkRead(String) checkRead} method is invoked
3774      *          to check read access to the directory.
3775      * @throws  IOException
3776      *          if an I/O error is thrown when accessing the starting file.
3777      *
3778      * @see     #walk(Path, int, FileVisitOption...)
3779      * @since   1.8
3780      */
3781     public static Stream<Path> walk(Path start, FileVisitOption... options) throws IOException {
3782         return walk(start, Integer.MAX_VALUE, options);
3783     }
3784 
3785     /**
3786      * Return a {@code Stream} that is lazily populated with {@code
3787      * Path} by searching for files in a file tree rooted at a given starting
3788      * file.
3789      *
3790      * <p> This method walks the file tree in exactly the manner specified by
3791      * the {@link #walk walk} method. For each file encountered, the given
3792      * {@link BiPredicate} is invoked with its {@link Path} and {@link
3793      * BasicFileAttributes}. The {@code Path} object is obtained as if by
3794      * {@link Path#resolve(Path) resolving} the relative path against {@code
3795      * start} and is only included in the returned {@link Stream} if
3796      * the {@code BiPredicate} returns true. Compare to calling {@link
3797      * java.util.stream.Stream#filter filter} on the {@code Stream}
3798      * returned by {@code walk} method, this method may be more efficient by
3799      * avoiding redundant retrieval of the {@code BasicFileAttributes}.
3800      *
3801      * <p> The returned stream contains references to one or more open directories.
3802      * The directories are closed by closing the stream.
3803      *
3804      * <p> If an {@link IOException} is thrown when accessing a file or directory,
3805      * it is passed to given {@code ioExceptionHandler}.
3806      * If this handler throws an unchecked exception it will be thrown from the
3807      * method that caused the access to take place. If the handler doesn't throw
3808      * any exception then the elements of the stream that caused the IOException(s)
3809      * by accessing them are absent from the stream. This may include entire subtrees
3810      * rooted at directories that caused IOException(s) by accessing them.
3811      * The 1st access to starting file takes place in this method.
3812      *
3813      * @apiNote
3814      * This method must be used within a try-with-resources statement or similar
3815      * control structure to ensure that the stream's open directories are closed
3816      * promptly after the stream's operations have completed.
3817      *
3818      * @param   start
3819      *          the starting file
3820      * @param   maxDepth
3821      *          the maximum number of directory levels to search
3822      * @param   matcher
3823      *          the function used to decide whether a file should be included
3824      *          in the returned stream
3825      * @param   ioExceptionHandler
3826      *          the consumer used to handle any IOException(s) that are thrown
3827      *          while walking the file tree
3828      * @param   options
3829      *          options to configure the traversal
3830      *
3831      * @return  the {@link Stream} of {@link Path}
3832      *
3833      * @throws  IllegalArgumentException
3834      *          if the {@code maxDepth} parameter is negative
3835      * @throws  NullPointerException
3836      *          if {@code start} or {@code matcher} or {@code ioExceptionHandler}
3837      *          or {@code options} is {@code null} or the options array contains
3838      *          a {@code null} element
3839      * @throws  SecurityException
3840      *          If the security manager denies access to the starting file.
3841      *          In the case of the default provider, the {@link
3842      *          SecurityManager#checkRead(String) checkRead} method is invoked
3843      *          to check read access to the directory.
3844      *
3845      * @see     #find(Path, int, BiPredicate, FileVisitOption...)
3846      * @see     #walk(Path, int, FileVisitOption...)
3847      * @since   1.9
3848      */
3849     public static Stream<Path> find(Path start,
3850                                     int maxDepth,
3851                                     BiPredicate<Path, BasicFileAttributes> matcher,
3852                                     Consumer<IOException> ioExceptionHandler,
3853                                     FileVisitOption... options)
3854     {
3855         Objects.requireNonNull(ioExceptionHandler);
3856         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, ioExceptionHandler, options);
3857         try {
3858             Spliterator<FileTreeWalker.Event> spliterator =
3859                 Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT);
3860             return StreamSupport.stream(spliterator, false)
3861                                 .onClose(iterator::close)
3862                                 .filter(entry -> matcher.test(entry.file(), entry.attributes()))
3863                                 .map(FileTreeWalker.Event::file);
3864         } catch (Throwable t) {
3865             try {
3866                 iterator.close();
3867             } catch (Throwable ct) {
3868                 t.addSuppressed(ct);
3869             }
3870             throw t;
3871         }
3872     }
3873 
3874     /**
3875      * Return a {@code Stream} that is lazily populated with {@code
3876      * Path} by searching for files in a file tree rooted at a given starting
3877      * file.
3878      *
3879      * <p> This method walks the file tree in exactly the manner specified by
3880      * the {@link #walk walk} method. For each file encountered, the given
3881      * {@link BiPredicate} is invoked with its {@link Path} and {@link
3882      * BasicFileAttributes}. The {@code Path} object is obtained as if by
3883      * {@link Path#resolve(Path) resolving} the relative path against {@code
3884      * start} and is only included in the returned {@link Stream} if
3885      * the {@code BiPredicate} returns true. Compare to calling {@link
3886      * java.util.stream.Stream#filter filter} on the {@code Stream}
3887      * returned by {@code walk} method, this method may be more efficient by
3888      * avoiding redundant retrieval of the {@code BasicFileAttributes}.
3889      *
3890      * <p> The returned stream contains references to one or more open directories.
3891      * The directories are closed by closing the stream.
3892      *
3893      * <p> If an {@link IOException} is thrown when accessing a file or directory
3894      * after returned from this method, it is wrapped in an {@link
3895      * UncheckedIOException} which will be thrown from the method that caused
3896      * the access to take place.
3897      *
3898      * @apiNote
3899      * This method must be used within a try-with-resources statement or similar
3900      * control structure to ensure that the stream's open directories are closed
3901      * promptly after the stream's operations have completed.
3902      *
3903      * @param   start
3904      *          the starting file
3905      * @param   maxDepth
3906      *          the maximum number of directory levels to search
3907      * @param   matcher
3908      *          the function used to decide whether a file should be included
3909      *          in the returned stream
3910      * @param   options
3911      *          options to configure the traversal
3912      *
3913      * @return  the {@link Stream} of {@link Path}
3914      *
3915      * @throws  IllegalArgumentException
3916      *          if the {@code maxDepth} parameter is negative
3917      * @throws  NullPointerException
3918      *          if {@code start} or {@code matcher} or {@code options}
3919      *          is {@code null} or the options array contains
3920      *          a {@code null} element
3921      * @throws  SecurityException
3922      *          If the security manager denies access to the starting file.
3923      *          In the case of the default provider, the {@link
3924      *          SecurityManager#checkRead(String) checkRead} method is invoked
3925      *          to check read access to the directory.
3926      * @throws  IOException
3927      *          if an I/O error is thrown when accessing the starting file.
3928      *
3929      * @see     #find(Path, int, BiPredicate, Consumer, FileVisitOption...)
3930      * @see     #walk(Path, int, FileVisitOption...)
3931      * @since   1.8
3932      */
3933     public static Stream<Path> find(Path start,
3934                                     int maxDepth,
3935                                     BiPredicate<Path, BasicFileAttributes> matcher,
3936                                     FileVisitOption... options)
3937         throws IOException
3938     {

3939         try {
3940             return find(start, maxDepth, matcher,
3941                         ioe -> { throw new UncheckedIOException(ioe); },
3942                         options);
3943         } catch (UncheckedIOException uioe) {
3944             throw uioe.getCause();




3945         }
3946     }
3947 
3948 
3949     /**
3950      * Read all lines from a file as a {@code Stream}. Unlike {@link
3951      * #readAllLines(Path, Charset) readAllLines}, this method does not read
3952      * all lines into a {@code List}, but instead populates lazily as the stream
3953      * is consumed.
3954      *
3955      * <p> Bytes from the file are decoded into characters using the specified
3956      * charset and the same line terminators as specified by {@code
3957      * readAllLines} are supported.
3958      *
3959      * <p> The returned stream contains a reference to an open file. The file
3960      * is closed by closing the stream.
3961      *
3962      * <p> The file contents should not be modified during the execution of the
3963      * terminal stream operation. Otherwise, the result of the terminal stream
3964      * operation is undefined.


< prev index next >