src/share/classes/java/nio/file/DirectoryStream.java

Print this page
rev 7023 : 8006884: (fs) Add Files.list, lines and find
Reviewed-by:
Contributed-by: alan.bateman@oracle.com, henry.jen@oracle.com

*** 26,45 **** package java.nio.file; import java.util.Iterator; import java.io.Closeable; import java.io.IOException; /** * An object to iterate over the entries in a directory. A directory stream ! * allows for the convenient use of the for-each construct to iterate over a ! * directory. * * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a ! * general-purpose {@code Iterable} as it supports only a single {@code ! * Iterator}; invoking the {@link #iterator iterator} method to obtain a second ! * or subsequent iterator throws {@code IllegalStateException}. </b> * * <p> An important property of the directory stream's {@code Iterator} is that * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by * at least one element. If {@code hasNext} method returns {@code true}, and is * followed by a call to the {@code next} method, it is guaranteed that the --- 26,50 ---- package java.nio.file; import java.util.Iterator; import java.io.Closeable; import java.io.IOException; + import java.util.Spliterator; + import java.util.Spliterators; + import java.util.stream.Stream; + import java.util.stream.StreamSupport; /** * An object to iterate over the entries in a directory. A directory stream ! * allows for the convenient use of the for-each construct or the {@link ! * Stream} API to iterate over a directory. * * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a ! * general-purpose {@code Iterable}. A {@code DirectoryStream} supports only a ! * single iteration via either the {@link #iterator iterator} or the {@link ! * #entries entries} method. Invoking either method to do a second or ! * subsequent iteration throws {@code IllegalStateException}. </b> * * <p> An important property of the directory stream's {@code Iterator} is that * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by * at least one element. If {@code hasNext} method returns {@code true}, and is * followed by a call to the {@code next} method, it is guaranteed that the
*** 59,89 **** * ... * } * } * </pre> * ! * <p> Once a directory stream is closed, then further access to the directory, ! * using the {@code Iterator}, behaves as if the end of stream has been reached. ! * Due to read-ahead, the {@code Iterator} may return one or more elements ! * after the directory stream has been closed. Once these buffered elements ! * have been read, then subsequent calls to the {@code hasNext} method returns ! * {@code false}, and subsequent calls to the {@code next} method will throw ! * {@code NoSuchElementException}. * * <p> A directory stream is not required to be <i>asynchronously closeable</i>. * If a thread is blocked on the directory stream's iterator reading from the * directory, and another thread invokes the {@code close} method, then the * second thread may block until the read operation is complete. * * <p> If an I/O error is encountered when accessing the directory then it ! * causes the {@code Iterator}'s {@code hasNext} or {@code next} methods to ! * throw {@link DirectoryIteratorException} with the {@link IOException} as the ! * cause. As stated above, the {@code hasNext} method is guaranteed to ! * read-ahead by at least one element. This means that if {@code hasNext} method ! * returns {@code true}, and is followed by a call to the {@code next} method, ! * then it is guaranteed that the {@code next} method will not fail with a ! * {@code DirectoryIteratorException}. * * <p> The elements returned by the iterator are in no specific order. Some file * systems maintain special links to the directory itself and the directory's * parent directory. Entries representing these links are not returned by the * iterator. --- 64,95 ---- * ... * } * } * </pre> * ! * <p> Once a directory stream is closed, then further access to the ! * directory, using the {@code Iterator} or {@code Stream}, behaves as if the ! * end of stream has been reached. Due to read-ahead, one or more elements may ! * be returned after the directory stream has been closed. Once these buffered ! * elements have been read, then subsequent calls to the {@code hasNext} ! * method returns {@code false}, and subsequent calls to the {@code next} ! * method will throw {@code NoSuchElementException}. * * <p> A directory stream is not required to be <i>asynchronously closeable</i>. * If a thread is blocked on the directory stream's iterator reading from the * directory, and another thread invokes the {@code close} method, then the * second thread may block until the read operation is complete. * * <p> If an I/O error is encountered when accessing the directory then it ! * causes the methods to throw {@link DirectoryIteratorException} with the ! * {@link IOException} as the cause. This could be the {@code Iterator}'s ! * {@code hasNext} or {@code next} method or one of the {@code Stream} methods. ! * As stated above, the {@code hasNext} method is guaranteed to read-ahead by ! * at least one element. This means that if {@code hasNext} method returns ! * {@code true}, and is followed by a call to the {@code next} method, then it ! * is guaranteed that the {@code next} method will not fail with a {@code ! * DirectoryIteratorException}. * * <p> The elements returned by the iterator are in no specific order. Some file * systems maintain special links to the directory itself and the directory's * parent directory. Entries representing these links are not returned by the * iterator.
*** 149,159 **** * Returns the iterator associated with this {@code DirectoryStream}. * * @return the iterator associated with this {@code DirectoryStream} * * @throws IllegalStateException ! * if this directory stream is closed or the iterator has already ! * been returned */ @Override Iterator<T> iterator(); } --- 155,179 ---- * Returns the iterator associated with this {@code DirectoryStream}. * * @return the iterator associated with this {@code DirectoryStream} * * @throws IllegalStateException ! * if this directory stream is closed or the iterator or stream ! * has already been returned */ @Override Iterator<T> iterator(); + + /** + * Returns the stream associated with this {@code DirectoryStream}. + * + * @return the stream associated with this {@code DirectoryStream} + * + * @throws IllegalStateException + * if this directory stream is closed or the iterator or stream + * has already been returned + * @since 1.8 + */ + default Stream<T> entries() { + return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator(), Spliterator.DISTINCT)); + } }