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

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

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

DirectoryStream открывается при создании и закрывается вызовом метода close. Закрытие потока каталога освобождает все связанные с ним ресурсы. Если не закрыть поток, это может привести к утечке ресурсов. Инструкция try-with-resources — удобный способ гарантировать закрытие потока:

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

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

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

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