src/java.base/share/classes/java/nio/file/Files.java
Print this page
rev 11503 : 8073923: Files.lines() documentation needs clarification
Reviewed-by: XXX
*** 1,7 ****
/*
! * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 3425,3449 ****
* <p> The stream is <i>weakly consistent</i>. It is thread safe but does
* not freeze the directory while iterating, so it may (or may not)
* reflect updates to the directory that occur after returning from this
* method.
*
! * <p> The returned stream encapsulates a {@link DirectoryStream}.
! * If timely disposal of file system resources is required, the
! * {@code try}-with-resources construct should be used to ensure that the
! * stream's {@link Stream#close close} method is invoked after the stream
! * operations are completed.
*
* <p> Operating on a closed stream behaves as if the end of stream
* has been reached. Due to read-ahead, one or more elements may be
* returned after the stream has been closed.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after this method has returned, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
* @param dir The path to the directory
*
* @return The {@code Stream} describing the content of the
* directory
*
--- 3425,3451 ----
* <p> The stream is <i>weakly consistent</i>. It is thread safe but does
* not freeze the directory while iterating, so it may (or may not)
* reflect updates to the directory that occur after returning from this
* method.
*
! * <p> The returned stream contains a {@link DirectoryStream},
! * which is closed by closing the stream.
*
* <p> Operating on a closed stream behaves as if the end of stream
* has been reached. Due to read-ahead, one or more elements may be
* returned after the stream has been closed.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after this method has returned, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
+ * @apiNote
+ * This method must be used within a try-with-resources statement to ensure
+ * that the contained {@link DirectoryStream} is closed promptly after the
+ * stream operations are completed.
+ *
* @param dir The path to the directory
*
* @return The {@code Stream} describing the content of the
* directory
*
*** 3547,3568 ****
* levels should be visited.
*
* <p> 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.
*
! * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
! * If timely disposal of file system resources is required, the
! * {@code try}-with-resources construct should be used to ensure that the
! * stream's {@link Stream#close close} method is invoked after the stream
! * operations are completed. Operating on a closed stream will result in an
! * {@link java.lang.IllegalStateException}.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after this method has returned, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
* @param start
* the starting file
* @param maxDepth
* the maximum number of directory levels to visit
* @param options
--- 3549,3571 ----
* levels should be visited.
*
* <p> 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.
*
! * <p> The returned stream contains one or more {@link DirectoryStream}s,
! * which are closed by closing the stream.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after this method has returned, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
+ * @apiNote
+ * This method must be used within a try-with-resources statement to ensure
+ * that the contained {@link DirectoryStream}s are closed promptly after the
+ * stream operations are completed.
+ *
* @param start
* the starting file
* @param maxDepth
* the maximum number of directory levels to visit
* @param options
*** 3611,3626 ****
* <blockquote><pre>
* walk(start, Integer.MAX_VALUE, options)
* </pre></blockquote>
* In other words, it visits all levels of the file tree.
*
! * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
! * If timely disposal of file system resources is required, the
! * {@code try}-with-resources construct should be used to ensure that the
! * stream's {@link Stream#close close} method is invoked after the stream
! * operations are completed. Operating on a closed stream will result in an
! * {@link java.lang.IllegalStateException}.
*
* @param start
* the starting file
* @param options
* options to configure the traversal
--- 3614,3630 ----
* <blockquote><pre>
* walk(start, Integer.MAX_VALUE, options)
* </pre></blockquote>
* In other words, it visits all levels of the file tree.
*
! * <p> The returned stream contains one or more {@link DirectoryStream}s,
! * which are closed by closing the stream.
! *
! * @apiNote
! * This method must be used within a try-with-resources statement to ensure
! * that the contained {@link DirectoryStream}s are closed promptly after the
! * stream operations are completed.
*
* @param start
* the starting file
* @param options
* options to configure the traversal
*** 3656,3677 ****
* the {@code BiPredicate} returns true. Compare to calling {@link
* java.util.stream.Stream#filter filter} on the {@code Stream}
* returned by {@code walk} method, this method may be more efficient by
* avoiding redundant retrieval of the {@code BasicFileAttributes}.
*
! * <p> The returned stream encapsulates one or more {@link DirectoryStream}s.
! * If timely disposal of file system resources is required, the
! * {@code try}-with-resources construct should be used to ensure that the
! * stream's {@link Stream#close close} method is invoked after the stream
! * operations are completed. Operating on a closed stream will result in an
! * {@link java.lang.IllegalStateException}.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after returned from this method, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
* @param start
* the starting file
* @param maxDepth
* the maximum number of directory levels to search
* @param matcher
--- 3660,3682 ----
* the {@code BiPredicate} returns true. Compare to calling {@link
* java.util.stream.Stream#filter filter} on the {@code Stream}
* returned by {@code walk} method, this method may be more efficient by
* avoiding redundant retrieval of the {@code BasicFileAttributes}.
*
! * <p> The returned stream contains one or more {@link DirectoryStream}s,
! * which are closed by closing the stream.
*
* <p> If an {@link IOException} is thrown when accessing the directory
* after returned from this method, it is wrapped in an {@link
* UncheckedIOException} which will be thrown from the method that caused
* the access to take place.
*
+ * @apiNote
+ * This method must be used within a try-with-resources statement to ensure
+ * that the contained {@link DirectoryStream} instances are closed promptly
+ * after the stream operations are completed.
+ *
* @param start
* the starting file
* @param maxDepth
* the maximum number of directory levels to search
* @param matcher
*** 3723,3746 ****
*
* <p> Bytes from the file are decoded into characters using the specified
* charset and the same line terminators as specified by {@code
* readAllLines} are supported.
*
* <p> After this method returns, then any subsequent I/O exception that
* occurs while reading from the file or when a malformed or unmappable byte
* sequence is read, is wrapped in an {@link UncheckedIOException} that will
* be thrown from the
* {@link java.util.stream.Stream} method that caused the read to take
* place. In case an {@code IOException} is thrown when closing the file,
* it is also wrapped as an {@code UncheckedIOException}.
*
! * <p> The returned stream encapsulates a {@link Reader}. If timely
! * disposal of file system resources is required, the try-with-resources
! * construct should be used to ensure that the stream's
! * {@link Stream#close close} method is invoked after the stream operations
! * are completed.
! *
*
* @param path
* the path to the file
* @param cs
* the charset to use for decoding
--- 3728,3751 ----
*
* <p> Bytes from the file are decoded into characters using the specified
* charset and the same line terminators as specified by {@code
* readAllLines} are supported.
*
+ * <p> The returned stream contains an open file, which is closed by
+ * closing the stream.
+ *
* <p> After this method returns, then any subsequent I/O exception that
* occurs while reading from the file or when a malformed or unmappable byte
* sequence is read, is wrapped in an {@link UncheckedIOException} that will
* be thrown from the
* {@link java.util.stream.Stream} method that caused the read to take
* place. In case an {@code IOException} is thrown when closing the file,
* it is also wrapped as an {@code UncheckedIOException}.
*
! * @apiNote
! * This method must be used within a try-with-resources statement to ensure
! * that the file is closed promptly after the stream operations are completed.
*
* @param path
* the path to the file
* @param cs
* the charset to use for decoding
*** 3778,3793 ****
--- 3783,3805 ----
/**
* Read all lines from a file as a {@code Stream}. Bytes from the file are
* decoded into characters using the {@link StandardCharsets#UTF_8 UTF-8}
* {@link Charset charset}.
*
+ * <p> The returned stream contains an open file, which is closed by
+ * closing the stream.
+ *
* <p> This method works as if invoking it were equivalent to evaluating the
* expression:
* <pre>{@code
* Files.lines(path, StandardCharsets.UTF_8)
* }</pre>
*
+ * @apiNote
+ * This method must be used within a try-with-resources statement to ensure
+ * that the file is closed promptly after the stream operations are completed.
+ *
* @param path
* the path to the file
*
* @return the lines from the file as a {@code Stream}
*