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}. * *
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 * {@code next} method will not throw an exception due to an I/O error, or * because the stream has been {@link #close closed}. The {@code Iterator} does * not support the {@link Iterator#remove remove} operation. * *
A {@code DirectoryStream} is opened upon creation and is closed by * invoking the {@code close} method. Closing a directory stream releases any * resources associated with the stream. Failure to close the stream may result * in a resource leak. The try-with-resources statement provides a useful * construct to ensure that the stream is closed: *
* Path dir = ...
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
* for (Path entry: stream) {
* ...
* }
* }
*
*
* 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}. * *
A directory stream is not required to be asynchronously closeable. * 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. * *
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}. * *
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. * *
The iterator is weakly consistent. 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 the {@code DirectoryStream} is created. * *
Usage Examples: * Suppose we want a list of the source files in a directory. This example uses * both the for-each and try-with-resources constructs. *
* List<Path> listSourceFiles(Path dir) throws IOException {
* List<Path> result = new ArrayList<>();
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
* for (Path entry: stream) {
* result.add(entry);
* }
* } catch (DirectoryIteratorException ex) {
* // I/O error encounted during the iteration, the cause is an IOException
* throw ex.getCause();
* }
* return result;
* }
*
* @param