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

public interface DirectoryStream<T>
extends Closeable, Iterable<T>

Объект для итерирования по записям в каталоге. Поток каталога позволяет удобно использовать конструкцию for-each для итерирования по каталогу.

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

Важное свойство потока каталога — это его Iterator, у которого метод hasNext гарантированно осуществляет предварительное чтение не менее одного элемента. Если метод hasNext возвращает true, а за ним следует вызов метода next, гарантируется, что метод next не выбросит исключение из-за ошибки ввода-вывода или из-за того, что поток был закрыт closed. Поток каталога не поддерживает операцию 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's hasNext или next выбросить 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 encounted during the iteration, the cause is an IOException
           throw ex.getCause();
       }
       return result;
   }

Методы

iterator

Iterator<T> iterator()

Возвращает итератор, связанный с этим DirectoryStream.

Определено в:

iterator в интерфейсе Iterable<T>

Возвращает:

итератор, связанный с этим DirectoryStream

Бросает:

IllegalStateException - если этот поток каталога закрыт или итератор уже возвращался