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}. * *
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}, 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}. * *
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 {@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}. * *
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