Module java.base
Package java.nio.file

Interface DirectoryStream<T>

类型参数:
T - 迭代器返回的元素类型
所有超接口:
AutoCloseable, Closeable, Iterable<T>
所有已知子接口:
SecureDirectoryStream<T>
public interface DirectoryStream<T> extends Closeable, Iterable<T>
用于遍历目录中条目的对象。目录流允许方便地使用 for-each 结构来遍历目录。

虽然 DirectoryStream 扩展了 Iterable，但它不是通用的 Iterable，因为它仅支持单个 Iterator；调用 iterator 方法以获取第二个或后续的迭代器会抛出 IllegalStateException。

目录流的 Iterator 的一个重要特性是，其 hasNext 方法保证至少预读一个元素。如果 hasNext 方法返回 true，并且随后调用 next 方法，则保证 next 方法不会因 I/O 错误或流已被 关闭 而抛出异常。该 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 方法，则第二个线程可能会阻塞，直到读取操作完成。

如果在访问目录时遇到 I/O 错误，则会导致 Iterator 的 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 错误，原因是 IOException
            throw ex.getCause();
        }
        return result;
    }
自 JDK 版本:
1.7
参见:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    DirectoryStream.Filter<T>
    由决定是否接受或过滤目录条目的对象实现的接口。

  • Method Summary

    Modifier and Type
    Method
    Description
    Iterator<T>
    iterator()
    返回与此 DirectoryStream 关联的迭代器。

    Methods declared in interface java.io.Closeable

    close

    Methods declared in interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • iterator

      Iterator<T> iterator()
      返回与此 DirectoryStream 关联的迭代器。
      指定者:
      iterator 在接口 Iterable<T> 中
      返回:
      与此 DirectoryStream 关联的迭代器
      抛出:
      IllegalStateException - 如果此目录流已关闭或迭代器已被返回