Интерфейс DirectoryStream<T>

Хотя DirectoryStream расширяет Iterable, он не является универсальным Iterable, так как поддерживает только один Iterator; вызов метода iterator для получения второго или последующего итератора вызывает IllegalStateException.

Важная особенность потока каталога Iterator заключается в том, что его метод hasNext гарантирует предварительное чтение как минимум одного элемента. Если метод hasNext возвращает true, и за ним следует вызов метода next, то гарантируется, что метод next не выбросит исключение из-за ошибки ввода-вывода или потому, что поток был closed. Поток Iterator не поддерживает операцию remove.

Поток каталога открывается при создании и закрывается путем вызова метода close. Закрытие потока каталога высвобождает все ресурсы, связанные с потоком. Отсутствие закрытия потока может привести к утечке ресурсов. Конструкция try-with-resources предоставляет полезную конструкцию для гарантированного закрытия потока:

    Path dir = ...
    try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
        for (Path entry: stream) {
            ...
        }
    }

После закрытия потока каталога дальнейший доступ к каталогу с использованием Iterator ведет себя так, как будто достигнут конец потока. Из-за предварительного чтения Iterator может вернуть один или несколько элементов после закрытия потока каталога. После чтения этих буферизованных элементов последующие вызовы метода hasNext возвращают false, а последующие вызовы метода next выбросят NoSuchElementException.

Поток каталога не обязан быть асинхронно закрываемым. Если поток заблокирован на чтении из каталога итератором потока каталога, а другой поток вызывает метод close, то второй поток может заблокироваться до завершения операции чтения.

Если при доступе к каталогу возникает ошибка ввода-вывода, то она заставляет методы Iterator или next потока hasNext выбросить DirectoryIteratorException с IOException в качестве причины. Как указано выше, метод hasNext гарантирует предварительное чтение как минимум одного элемента. Это означает, что если метод hasNext возвращает true, а за ним следует вызов метода next, то гарантируется, что метод next не завершится с ошибкой DirectoryIteratorException.

Элементы, возвращаемые итератором, не упорядочены каким-либо определенным образом. Некоторые файловые системы поддерживают специальные ссылки на сам каталог и родительский каталог каталога. Записи, представляющие эти ссылки, не возвращаются итератором.

Итератор слабо согласован. Он потокобезопасен, но не блокирует каталог во время итерации, поэтому он может (или может не) отражать изменения в каталоге, произошедшие после создания DirectoryStream.

Примеры использования: Предположим, что мы хотим список исходных файлов в каталоге. В этом примере используются как конструкция for-each, так и try-with-resources.

    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 encountered during the iteration, the cause is an IOException
            throw ex.getCause();
        }
        return result;
    }