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 +1,7 @@
/*
- * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
+ * 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,25 +3425,27 @@
* <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> 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,22 +3549,23 @@
* 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> 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,16 +3614,17 @@
* <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}.
+ * <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,22 +3660,23 @@
* 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> 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,24 +3728,24 @@
*
* <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}.
*
- * <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.
- *
+ * @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,16 +3783,23 @@
/**
* 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}
*