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读， Iterator可能在目录流关闭后返回一个或多个元素。 一旦读取了这些缓冲元素，则后续调用hasNext方法将返回false ，随后对next方法的调用将返回NoSuchElementException 。

目录流不需要是异步关闭的 。 如果在目录流的迭代器上从目录读取一个线程，而另一个线程调用close方法，则第二个线程可能会阻塞，直到读取操作完成。

如果在访问目录时遇到I / O错误，则会导致Iterator的hasNext或next方法抛出DirectoryIteratorException并将IOException作为原因。 如上所述，保证hasNext方法至少由一个元素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;
   }