1 /*
2 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
3410 return write(path, lines, StandardCharsets.UTF_8, options);
3411 }
3412
3413 // -- Stream APIs --
3414
3415 /**
3416 * Return a lazily populated {@code Stream}, the elements of
3417 * which are the entries in the directory. The listing is not recursive.
3418 *
3419 * <p> The elements of the stream are {@link Path} objects that are
3420 * obtained as if by {@link Path#resolve(Path) resolving} the name of the
3421 * directory entry against {@code dir}. Some file systems maintain special
3422 * links to the directory itself and the directory's parent directory.
3423 * Entries representing these links are not included.
3424 *
3425 * <p> The stream is <i>weakly consistent</i>. It is thread safe but does
3426 * not freeze the directory while iterating, so it may (or may not)
3427 * reflect updates to the directory that occur after returning from this
3428 * method.
3429 *
3430 * <p> The returned stream encapsulates a {@link DirectoryStream}.
3431 * If timely disposal of file system resources is required, the
3432 * {@code try}-with-resources construct should be used to ensure that the
3433 * stream's {@link Stream#close close} method is invoked after the stream
3434 * operations are completed.
3435 *
3436 * <p> Operating on a closed stream behaves as if the end of stream
3437 * has been reached. Due to read-ahead, one or more elements may be
3438 * returned after the stream has been closed.
3439 *
3440 * <p> If an {@link IOException} is thrown when accessing the directory
3441 * after this method has returned, it is wrapped in an {@link
3442 * UncheckedIOException} which will be thrown from the method that caused
3443 * the access to take place.
3444 *
3445 * @param dir The path to the directory
3446 *
3447 * @return The {@code Stream} describing the content of the
3448 * directory
3449 *
3450 * @throws NotDirectoryException
3451 * if the file could not otherwise be opened because it is not
3452 * a directory <i>(optional specific exception)</i>
3453 * @throws IOException
3454 * if an I/O error occurs when opening the directory
3455 * @throws SecurityException
3456 * In the case of the default provider, and a security manager is
3457 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3458 * method is invoked to check read access to the directory.
3459 *
3460 * @see #newDirectoryStream(Path)
3461 * @since 1.8
3462 */
3463 public static Stream<Path> list(Path dir) throws IOException {
3464 DirectoryStream<Path> ds = Files.newDirectoryStream(dir);
3532 * <p> If the {@code options} parameter contains the {@link
3533 * FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then the stream keeps
3534 * track of directories visited so that cycles can be detected. A cycle
3535 * arises when there is an entry in a directory that is an ancestor of the
3536 * directory. Cycle detection is done by recording the {@link
3537 * java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
3538 * or if file keys are not available, by invoking the {@link #isSameFile
3539 * isSameFile} method to test if a directory is the same file as an
3540 * ancestor. When a cycle is detected it is treated as an I/O error with
3541 * an instance of {@link FileSystemLoopException}.
3542 *
3543 * <p> The {@code maxDepth} parameter is the maximum number of levels of
3544 * directories to visit. A value of {@code 0} means that only the starting
3545 * file is visited, unless denied by the security manager. A value of
3546 * {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
3547 * levels should be visited.
3548 *
3549 * <p> When a security manager is installed and it denies access to a file
3550 * (or directory), then it is ignored and not included in the stream.
3551 *
3552 * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
3553 * If timely disposal of file system resources is required, the
3554 * {@code try}-with-resources construct should be used to ensure that the
3555 * stream's {@link Stream#close close} method is invoked after the stream
3556 * operations are completed. Operating on a closed stream will result in an
3557 * {@link java.lang.IllegalStateException}.
3558 *
3559 * <p> If an {@link IOException} is thrown when accessing the directory
3560 * after this method has returned, it is wrapped in an {@link
3561 * UncheckedIOException} which will be thrown from the method that caused
3562 * the access to take place.
3563 *
3564 * @param start
3565 * the starting file
3566 * @param maxDepth
3567 * the maximum number of directory levels to visit
3568 * @param options
3569 * options to configure the traversal
3570 *
3571 * @return the {@link Stream} of {@link Path}
3572 *
3573 * @throws IllegalArgumentException
3574 * if the {@code maxDepth} parameter is negative
3575 * @throws SecurityException
3576 * If the security manager denies access to the starting file.
3577 * In the case of the default provider, the {@link
3578 * SecurityManager#checkRead(String) checkRead} method is invoked
3579 * to check read access to the directory.
3580 * @throws IOException
3581 * if an I/O error is thrown when accessing the starting file.
3582 * @since 1.8
3583 */
3596 } catch (Error|RuntimeException e) {
3597 iterator.close();
3598 throw e;
3599 }
3600 }
3601
3602 /**
3603 * Return a {@code Stream} that is lazily populated with {@code
3604 * Path} by walking the file tree rooted at a given starting file. The
3605 * file tree is traversed <em>depth-first</em>, the elements in the stream
3606 * are {@link Path} objects that are obtained as if by {@link
3607 * Path#resolve(Path) resolving} the relative path against {@code start}.
3608 *
3609 * <p> This method works as if invoking it were equivalent to evaluating the
3610 * expression:
3611 * <blockquote><pre>
3612 * walk(start, Integer.MAX_VALUE, options)
3613 * </pre></blockquote>
3614 * In other words, it visits all levels of the file tree.
3615 *
3616 * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
3617 * If timely disposal of file system resources is required, the
3618 * {@code try}-with-resources construct should be used to ensure that the
3619 * stream's {@link Stream#close close} method is invoked after the stream
3620 * operations are completed. Operating on a closed stream will result in an
3621 * {@link java.lang.IllegalStateException}.
3622 *
3623 * @param start
3624 * the starting file
3625 * @param options
3626 * options to configure the traversal
3627 *
3628 * @return the {@link Stream} of {@link Path}
3629 *
3630 * @throws SecurityException
3631 * If the security manager denies access to the starting file.
3632 * In the case of the default provider, the {@link
3633 * SecurityManager#checkRead(String) checkRead} method is invoked
3634 * to check read access to the directory.
3635 * @throws IOException
3636 * if an I/O error is thrown when accessing the starting file.
3637 *
3638 * @see #walk(Path, int, FileVisitOption...)
3639 * @since 1.8
3640 */
3641 public static Stream<Path> walk(Path start, FileVisitOption... options) throws IOException {
3642 return walk(start, Integer.MAX_VALUE, options);
3643 }
3644
3645 /**
3646 * Return a {@code Stream} that is lazily populated with {@code
3647 * Path} by searching for files in a file tree rooted at a given starting
3648 * file.
3649 *
3650 * <p> This method walks the file tree in exactly the manner specified by
3651 * the {@link #walk walk} method. For each file encountered, the given
3652 * {@link BiPredicate} is invoked with its {@link Path} and {@link
3653 * BasicFileAttributes}. The {@code Path} object is obtained as if by
3654 * {@link Path#resolve(Path) resolving} the relative path against {@code
3655 * start} and is only included in the returned {@link Stream} if
3656 * the {@code BiPredicate} returns true. Compare to calling {@link
3657 * java.util.stream.Stream#filter filter} on the {@code Stream}
3658 * returned by {@code walk} method, this method may be more efficient by
3659 * avoiding redundant retrieval of the {@code BasicFileAttributes}.
3660 *
3661 * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
3662 * If timely disposal of file system resources is required, the
3663 * {@code try}-with-resources construct should be used to ensure that the
3664 * stream's {@link Stream#close close} method is invoked after the stream
3665 * operations are completed. Operating on a closed stream will result in an
3666 * {@link java.lang.IllegalStateException}.
3667 *
3668 * <p> If an {@link IOException} is thrown when accessing the directory
3669 * after returned from this method, it is wrapped in an {@link
3670 * UncheckedIOException} which will be thrown from the method that caused
3671 * the access to take place.
3672 *
3673 * @param start
3674 * the starting file
3675 * @param maxDepth
3676 * the maximum number of directory levels to search
3677 * @param matcher
3678 * the function used to decide whether a file should be included
3679 * in the returned stream
3680 * @param options
3681 * options to configure the traversal
3682 *
3683 * @return the {@link Stream} of {@link Path}
3684 *
3685 * @throws IllegalArgumentException
3686 * if the {@code maxDepth} parameter is negative
3687 * @throws SecurityException
3688 * If the security manager denies access to the starting file.
3689 * In the case of the default provider, the {@link
3690 * SecurityManager#checkRead(String) checkRead} method is invoked
3691 * to check read access to the directory.
3692 * @throws IOException
3708 return StreamSupport.stream(spliterator, false)
3709 .onClose(iterator::close)
3710 .filter(entry -> matcher.test(entry.file(), entry.attributes()))
3711 .map(entry -> entry.file());
3712 } catch (Error|RuntimeException e) {
3713 iterator.close();
3714 throw e;
3715 }
3716 }
3717
3718 /**
3719 * Read all lines from a file as a {@code Stream}. Unlike {@link
3720 * #readAllLines(Path, Charset) readAllLines}, this method does not read
3721 * all lines into a {@code List}, but instead populates lazily as the stream
3722 * is consumed.
3723 *
3724 * <p> Bytes from the file are decoded into characters using the specified
3725 * charset and the same line terminators as specified by {@code
3726 * readAllLines} are supported.
3727 *
3728 * <p> After this method returns, then any subsequent I/O exception that
3729 * occurs while reading from the file or when a malformed or unmappable byte
3730 * sequence is read, is wrapped in an {@link UncheckedIOException} that will
3731 * be thrown from the
3732 * {@link java.util.stream.Stream} method that caused the read to take
3733 * place. In case an {@code IOException} is thrown when closing the file,
3734 * it is also wrapped as an {@code UncheckedIOException}.
3735 *
3736 * <p> The returned stream encapsulates a {@link Reader}. If timely
3737 * disposal of file system resources is required, the try-with-resources
3738 * construct should be used to ensure that the stream's
3739 * {@link Stream#close close} method is invoked after the stream operations
3740 * are completed.
3741 *
3742 *
3743 * @param path
3744 * the path to the file
3745 * @param cs
3746 * the charset to use for decoding
3747 *
3748 * @return the lines from the file as a {@code Stream}
3749 *
3750 * @throws IOException
3751 * if an I/O error occurs opening the file
3752 * @throws SecurityException
3753 * In the case of the default provider, and a security manager is
3754 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3755 * method is invoked to check read access to the file.
3756 *
3757 * @see #readAllLines(Path, Charset)
3758 * @see #newBufferedReader(Path, Charset)
3759 * @see java.io.BufferedReader#lines()
3760 * @since 1.8
3761 */
3763 BufferedReader br = Files.newBufferedReader(path, cs);
3764 try {
3765 return br.lines().onClose(asUncheckedRunnable(br));
3766 } catch (Error|RuntimeException e) {
3767 try {
3768 br.close();
3769 } catch (IOException ex) {
3770 try {
3771 e.addSuppressed(ex);
3772 } catch (Throwable ignore) {}
3773 }
3774 throw e;
3775 }
3776 }
3777
3778 /**
3779 * Read all lines from a file as a {@code Stream}. Bytes from the file are
3780 * decoded into characters using the {@link StandardCharsets#UTF_8 UTF-8}
3781 * {@link Charset charset}.
3782 *
3783 * <p> This method works as if invoking it were equivalent to evaluating the
3784 * expression:
3785 * <pre>{@code
3786 * Files.lines(path, StandardCharsets.UTF_8)
3787 * }</pre>
3788 *
3789 * @param path
3790 * the path to the file
3791 *
3792 * @return the lines from the file as a {@code Stream}
3793 *
3794 * @throws IOException
3795 * if an I/O error occurs opening the file
3796 * @throws SecurityException
3797 * In the case of the default provider, and a security manager is
3798 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3799 * method is invoked to check read access to the file.
3800 *
3801 * @since 1.8
3802 */
3803 public static Stream<String> lines(Path path) throws IOException {
3804 return lines(path, StandardCharsets.UTF_8);
3805 }
3806 }
|
1 /*
2 * Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
3410 return write(path, lines, StandardCharsets.UTF_8, options);
3411 }
3412
3413 // -- Stream APIs --
3414
3415 /**
3416 * Return a lazily populated {@code Stream}, the elements of
3417 * which are the entries in the directory. The listing is not recursive.
3418 *
3419 * <p> The elements of the stream are {@link Path} objects that are
3420 * obtained as if by {@link Path#resolve(Path) resolving} the name of the
3421 * directory entry against {@code dir}. Some file systems maintain special
3422 * links to the directory itself and the directory's parent directory.
3423 * Entries representing these links are not included.
3424 *
3425 * <p> The stream is <i>weakly consistent</i>. It is thread safe but does
3426 * not freeze the directory while iterating, so it may (or may not)
3427 * reflect updates to the directory that occur after returning from this
3428 * method.
3429 *
3430 * <p> The returned stream contains a {@link DirectoryStream},
3431 * which is closed by closing the stream.
3432 *
3433 * <p> Operating on a closed stream behaves as if the end of stream
3434 * has been reached. Due to read-ahead, one or more elements may be
3435 * returned after the stream has been closed.
3436 *
3437 * <p> If an {@link IOException} is thrown when accessing the directory
3438 * after this method has returned, it is wrapped in an {@link
3439 * UncheckedIOException} which will be thrown from the method that caused
3440 * the access to take place.
3441 *
3442 * @apiNote
3443 * This method must be used within a try-with-resources statement to ensure
3444 * that the contained {@link DirectoryStream} is closed promptly after the
3445 * stream operations are completed.
3446 *
3447 * @param dir The path to the directory
3448 *
3449 * @return The {@code Stream} describing the content of the
3450 * directory
3451 *
3452 * @throws NotDirectoryException
3453 * if the file could not otherwise be opened because it is not
3454 * a directory <i>(optional specific exception)</i>
3455 * @throws IOException
3456 * if an I/O error occurs when opening the directory
3457 * @throws SecurityException
3458 * In the case of the default provider, and a security manager is
3459 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3460 * method is invoked to check read access to the directory.
3461 *
3462 * @see #newDirectoryStream(Path)
3463 * @since 1.8
3464 */
3465 public static Stream<Path> list(Path dir) throws IOException {
3466 DirectoryStream<Path> ds = Files.newDirectoryStream(dir);
3534 * <p> If the {@code options} parameter contains the {@link
3535 * FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then the stream keeps
3536 * track of directories visited so that cycles can be detected. A cycle
3537 * arises when there is an entry in a directory that is an ancestor of the
3538 * directory. Cycle detection is done by recording the {@link
3539 * java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
3540 * or if file keys are not available, by invoking the {@link #isSameFile
3541 * isSameFile} method to test if a directory is the same file as an
3542 * ancestor. When a cycle is detected it is treated as an I/O error with
3543 * an instance of {@link FileSystemLoopException}.
3544 *
3545 * <p> The {@code maxDepth} parameter is the maximum number of levels of
3546 * directories to visit. A value of {@code 0} means that only the starting
3547 * file is visited, unless denied by the security manager. A value of
3548 * {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
3549 * levels should be visited.
3550 *
3551 * <p> When a security manager is installed and it denies access to a file
3552 * (or directory), then it is ignored and not included in the stream.
3553 *
3554 * <p> The returned stream contains one or more {@link DirectoryStream}s,
3555 * which are closed by closing the stream.
3556 *
3557 * <p> If an {@link IOException} is thrown when accessing the directory
3558 * after this method has returned, it is wrapped in an {@link
3559 * UncheckedIOException} which will be thrown from the method that caused
3560 * the access to take place.
3561 *
3562 * @apiNote
3563 * This method must be used within a try-with-resources statement to ensure
3564 * that the contained {@link DirectoryStream}s are closed promptly after the
3565 * stream operations are completed.
3566 *
3567 * @param start
3568 * the starting file
3569 * @param maxDepth
3570 * the maximum number of directory levels to visit
3571 * @param options
3572 * options to configure the traversal
3573 *
3574 * @return the {@link Stream} of {@link Path}
3575 *
3576 * @throws IllegalArgumentException
3577 * if the {@code maxDepth} parameter is negative
3578 * @throws SecurityException
3579 * If the security manager denies access to the starting file.
3580 * In the case of the default provider, the {@link
3581 * SecurityManager#checkRead(String) checkRead} method is invoked
3582 * to check read access to the directory.
3583 * @throws IOException
3584 * if an I/O error is thrown when accessing the starting file.
3585 * @since 1.8
3586 */
3599 } catch (Error|RuntimeException e) {
3600 iterator.close();
3601 throw e;
3602 }
3603 }
3604
3605 /**
3606 * Return a {@code Stream} that is lazily populated with {@code
3607 * Path} by walking the file tree rooted at a given starting file. The
3608 * file tree is traversed <em>depth-first</em>, the elements in the stream
3609 * are {@link Path} objects that are obtained as if by {@link
3610 * Path#resolve(Path) resolving} the relative path against {@code start}.
3611 *
3612 * <p> This method works as if invoking it were equivalent to evaluating the
3613 * expression:
3614 * <blockquote><pre>
3615 * walk(start, Integer.MAX_VALUE, options)
3616 * </pre></blockquote>
3617 * In other words, it visits all levels of the file tree.
3618 *
3619 * <p> The returned stream contains one or more {@link DirectoryStream}s,
3620 * which are closed by closing the stream.
3621 *
3622 * @apiNote
3623 * This method must be used within a try-with-resources statement to ensure
3624 * that the contained {@link DirectoryStream}s are closed promptly after the
3625 * stream operations are completed.
3626 *
3627 * @param start
3628 * the starting file
3629 * @param options
3630 * options to configure the traversal
3631 *
3632 * @return the {@link Stream} of {@link Path}
3633 *
3634 * @throws SecurityException
3635 * If the security manager denies access to the starting file.
3636 * In the case of the default provider, the {@link
3637 * SecurityManager#checkRead(String) checkRead} method is invoked
3638 * to check read access to the directory.
3639 * @throws IOException
3640 * if an I/O error is thrown when accessing the starting file.
3641 *
3642 * @see #walk(Path, int, FileVisitOption...)
3643 * @since 1.8
3644 */
3645 public static Stream<Path> walk(Path start, FileVisitOption... options) throws IOException {
3646 return walk(start, Integer.MAX_VALUE, options);
3647 }
3648
3649 /**
3650 * Return a {@code Stream} that is lazily populated with {@code
3651 * Path} by searching for files in a file tree rooted at a given starting
3652 * file.
3653 *
3654 * <p> This method walks the file tree in exactly the manner specified by
3655 * the {@link #walk walk} method. For each file encountered, the given
3656 * {@link BiPredicate} is invoked with its {@link Path} and {@link
3657 * BasicFileAttributes}. The {@code Path} object is obtained as if by
3658 * {@link Path#resolve(Path) resolving} the relative path against {@code
3659 * start} and is only included in the returned {@link Stream} if
3660 * the {@code BiPredicate} returns true. Compare to calling {@link
3661 * java.util.stream.Stream#filter filter} on the {@code Stream}
3662 * returned by {@code walk} method, this method may be more efficient by
3663 * avoiding redundant retrieval of the {@code BasicFileAttributes}.
3664 *
3665 * <p> The returned stream contains one or more {@link DirectoryStream}s,
3666 * which are closed by closing the stream.
3667 *
3668 * <p> If an {@link IOException} is thrown when accessing the directory
3669 * after returned from this method, it is wrapped in an {@link
3670 * UncheckedIOException} which will be thrown from the method that caused
3671 * the access to take place.
3672 *
3673 * @apiNote
3674 * This method must be used within a try-with-resources statement to ensure
3675 * that the contained {@link DirectoryStream} instances are closed promptly
3676 * after the stream operations are completed.
3677 *
3678 * @param start
3679 * the starting file
3680 * @param maxDepth
3681 * the maximum number of directory levels to search
3682 * @param matcher
3683 * the function used to decide whether a file should be included
3684 * in the returned stream
3685 * @param options
3686 * options to configure the traversal
3687 *
3688 * @return the {@link Stream} of {@link Path}
3689 *
3690 * @throws IllegalArgumentException
3691 * if the {@code maxDepth} parameter is negative
3692 * @throws SecurityException
3693 * If the security manager denies access to the starting file.
3694 * In the case of the default provider, the {@link
3695 * SecurityManager#checkRead(String) checkRead} method is invoked
3696 * to check read access to the directory.
3697 * @throws IOException
3713 return StreamSupport.stream(spliterator, false)
3714 .onClose(iterator::close)
3715 .filter(entry -> matcher.test(entry.file(), entry.attributes()))
3716 .map(entry -> entry.file());
3717 } catch (Error|RuntimeException e) {
3718 iterator.close();
3719 throw e;
3720 }
3721 }
3722
3723 /**
3724 * Read all lines from a file as a {@code Stream}. Unlike {@link
3725 * #readAllLines(Path, Charset) readAllLines}, this method does not read
3726 * all lines into a {@code List}, but instead populates lazily as the stream
3727 * is consumed.
3728 *
3729 * <p> Bytes from the file are decoded into characters using the specified
3730 * charset and the same line terminators as specified by {@code
3731 * readAllLines} are supported.
3732 *
3733 * <p> The returned stream contains an open file, which is closed by
3734 * closing the stream.
3735 *
3736 * <p> After this method returns, then any subsequent I/O exception that
3737 * occurs while reading from the file or when a malformed or unmappable byte
3738 * sequence is read, is wrapped in an {@link UncheckedIOException} that will
3739 * be thrown from the
3740 * {@link java.util.stream.Stream} method that caused the read to take
3741 * place. In case an {@code IOException} is thrown when closing the file,
3742 * it is also wrapped as an {@code UncheckedIOException}.
3743 *
3744 * @apiNote
3745 * This method must be used within a try-with-resources statement to ensure
3746 * that the file is closed promptly after the stream operations are completed.
3747 *
3748 * @param path
3749 * the path to the file
3750 * @param cs
3751 * the charset to use for decoding
3752 *
3753 * @return the lines from the file as a {@code Stream}
3754 *
3755 * @throws IOException
3756 * if an I/O error occurs opening the file
3757 * @throws SecurityException
3758 * In the case of the default provider, and a security manager is
3759 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3760 * method is invoked to check read access to the file.
3761 *
3762 * @see #readAllLines(Path, Charset)
3763 * @see #newBufferedReader(Path, Charset)
3764 * @see java.io.BufferedReader#lines()
3765 * @since 1.8
3766 */
3768 BufferedReader br = Files.newBufferedReader(path, cs);
3769 try {
3770 return br.lines().onClose(asUncheckedRunnable(br));
3771 } catch (Error|RuntimeException e) {
3772 try {
3773 br.close();
3774 } catch (IOException ex) {
3775 try {
3776 e.addSuppressed(ex);
3777 } catch (Throwable ignore) {}
3778 }
3779 throw e;
3780 }
3781 }
3782
3783 /**
3784 * Read all lines from a file as a {@code Stream}. Bytes from the file are
3785 * decoded into characters using the {@link StandardCharsets#UTF_8 UTF-8}
3786 * {@link Charset charset}.
3787 *
3788 * <p> The returned stream contains an open file, which is closed by
3789 * closing the stream.
3790 *
3791 * <p> This method works as if invoking it were equivalent to evaluating the
3792 * expression:
3793 * <pre>{@code
3794 * Files.lines(path, StandardCharsets.UTF_8)
3795 * }</pre>
3796 *
3797 * @apiNote
3798 * This method must be used within a try-with-resources statement to ensure
3799 * that the file is closed promptly after the stream operations are completed.
3800 *
3801 * @param path
3802 * the path to the file
3803 *
3804 * @return the lines from the file as a {@code Stream}
3805 *
3806 * @throws IOException
3807 * if an I/O error occurs opening the file
3808 * @throws SecurityException
3809 * In the case of the default provider, and a security manager is
3810 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3811 * method is invoked to check read access to the file.
3812 *
3813 * @since 1.8
3814 */
3815 public static Stream<String> lines(Path path) throws IOException {
3816 return lines(path, StandardCharsets.UTF_8);
3817 }
3818 }
|