Интерфейс 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, то второй поток может заблокироваться до завершения операции чтения.

Если при доступе к каталогу возникает ошибка ввода-вывода, то это вызывает выброс исключения DirectoryIteratorException для метода Iterator или next с 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;
    }