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 reference to an open directory. + * The directory 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 or similar + * control structure to ensure that the stream's open directory is closed + * promptly after the stream's operations have 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 references to one or more open directories. + * The directories 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 or similar + * control structure to ensure that the stream's open directories are closed + * promptly after the stream's operations have 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 references to one or more open directories. + * The directories are closed by closing the stream. + * + * @apiNote + * This method must be used within a try-with-resources statement or similar + * control structure to ensure that the stream's open directories are closed + * promptly after the stream's operations have 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 references to one or more open directories. + * The directories 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 or similar + * control structure to ensure that the stream's open directories are closed + * promptly after the stream's operations have 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 a reference to an open file. The file + * 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,10 @@ * 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 or similar + * control structure to ensure that the stream's open file is closed promptly + * after the stream's operations have completed. * * @param path * the path to the file @@ -3780,12 +3786,20 @@ * decoded into characters using the {@link StandardCharsets#UTF_8 UTF-8} * {@link Charset charset}. * + *
The returned stream contains a reference to an open file. The file + * 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 or similar
+ * control structure to ensure that the stream's open file is closed promptly
+ * after the stream's operations have completed.
+ *
* @param path
* the path to the file
*
diff -r cb2fb204a82b -r 5f136809bb3c jdk/src/java.base/share/classes/java/util/stream/Stream.java
--- a/jdk/src/java.base/share/classes/java/util/stream/Stream.java Wed Mar 04 13:44:18 2015 +0300
+++ b/jdk/src/java.base/share/classes/java/util/stream/Stream.java Wed Mar 04 13:22:45 2015 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 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
@@ -126,13 +126,15 @@
* 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 or similar control structure to ensure that it is closed promptly after its + * operations have completed. * *
Stream pipelines may execute either sequentially or in * parallel. This