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. + *
The returned stream contains a {@link DirectoryStream}, + * which is closed by closing the stream. * *
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 @@ -3442,6 +3439,11 @@ * 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 @@ -3549,18 +3551,19 @@ *
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 {@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}. + *
The returned stream contains one or more {@link DirectoryStream}s, + * which are closed by closing the stream. * *
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 @@ -3613,12 +3616,13 @@ * * In other words, it visits all levels of the file tree. * - *
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}. + *
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 @@ -3658,18 +3662,19 @@ * returned by {@code walk} method, this method may be more efficient by * avoiding redundant retrieval of the {@code BasicFileAttributes}. * - *
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}. + *
The returned stream contains one or more {@link DirectoryStream}s, + * which are closed by closing the stream. * *
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 @@ -3725,6 +3730,9 @@ * charset and the same line terminators as specified by {@code * readAllLines} are supported. * + *
The returned stream contains an open file, which is closed by + * closing the stream. + * *
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 @@ -3733,12 +3741,9 @@ * place. In case an {@code IOException} is thrown when closing the file, * it is also wrapped as an {@code UncheckedIOException}. * - *
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. - * + * @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 @@ -3780,12 +3785,19 @@ * decoded into characters using the {@link StandardCharsets#UTF_8 UTF-8} * {@link Charset charset}. * + *
The returned stream contains an open file, which is closed by + * closing the stream. + * *
This method works as if invoking it were equivalent to evaluating the * expression: *
{@code
* Files.lines(path, StandardCharsets.UTF_8)
* }
*
+ * @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
*
diff --git a/src/java.base/share/classes/java/util/stream/Stream.java b/src/java.base/share/classes/java/util/stream/Stream.java
--- a/src/java.base/share/classes/java/util/stream/Stream.java
+++ b/src/java.base/share/classes/java/util/stream/Stream.java
@@ -126,13 +126,14 @@
* operations may return their receiver rather than a new stream object, it may
* not be possible to detect reuse in all cases.
*
- * Streams have a {@link #close()} method and implement {@link AutoCloseable}, - * but nearly all stream instances do not actually need to be closed after use. - * Generally, only streams whose source is an IO channel (such as those returned - * by {@link Files#lines(Path, Charset)}) will require closing. Most streams + *
Streams have a {@link #close()} method and implement {@link AutoCloseable}. + * Operating on a stream after it has been closed will throw {@link IllegalStateException}. + * Most stream instances do not actually need to be closed after use, as they * are backed by collections, arrays, or generating functions, which require no - * special resource management. (If a stream does require closing, it can be - * declared as a resource in a {@code try}-with-resources statement.) + * special resource management. Generally, only streams whose source is an IO channel, + * such as those returned by {@link Files#lines(Path)}, will require closing. If a + * stream does require closing, it must be opened as a resource within a try-with-resources + * statement to ensure that it is closed promptly after its operations have completed. * *
Stream pipelines may execute either sequentially or in * parallel. This