Module  java.base
软件包  java.nio.file

Interface DirectoryStream<T>

  • 参数类型
    T - 迭代器返回的元素的类型
    All Superinterfaces:
    AutoCloseableCloseableIterable<T>
    All Known Subinterfaces:
    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操作。

    A 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错误,则导致IteratorhasNextnext方法以IOException作为原因抛出DirectoryIteratorException 如上所述, 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;
       } 
    从以下版本开始:
    1.7
    另请参见:
    Files.newDirectoryStream(Path)
    • 方法详细信息

      • iterator

        Iterator<T> iterator​()
        返回与此 DirectoryStream相关联的迭代器。
        Specified by:
        iterator在接口 Iterable<T>
        结果
        与此 DirectoryStream相关联的迭代器
        异常
        IllegalStateException - 如果此目录流已关闭或迭代器已被返回