模块 java.base
包 java.nio.file

接口 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 错误或流已被 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 方法，则第二个线程可能会阻塞，直到读取操作完成。

如果在访问目录时遇到 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 error encountered during the iteration, the cause is an IOException
      throw ex.getCause();
    }
    return result;
  }
自从：
1.7
参见：

  • 内部类总结

    内部类
    修饰符和类型
    接口
    描述
    static interface 
    DirectoryStream.Filter<T>
    由决定是否应接受或过滤目录条目的对象实现的接口。

  • 方法总结

    修饰符和类型
    方法
    描述
    Iterator<T>
    iterator()
    返回与此 DirectoryStream 关联的迭代器。

    在接口 java.io.Closeable 中声明的方法

    close

    在接口 java.lang.Iterable 中声明的方法

    forEach, spliterator

  • 方法详情

    • iterator

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