モジュール 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を拡張しますが、それがサポートする Iteratorは1つだけなので、それは汎用のIterableではありません。つまり、iteratorメソッドを呼び出して、2つめまたはそれに続くイテレータを取得すると、IllegalStateExceptionがスローされます。

ディレクトリ・ストリームのIteratorの重要な特性の1つに、そのhasNextメソッドが要素を1つ以上先読みすることが保証されていることがあります。 hasNextメソッドがtrueを返し、それに続いてnextメソッドが呼び出された場合、入出力エラーが発生したり、ストリームがclosedされたりしても、nextメソッドは例外をスローしないことが保証されています。 Iteratorはremove操作をサポートしていません。

DirectoryStreamは作成時にオープンされ、closeメソッドを呼び出すことでクローズされます。 ディレクトリ・ストリームをクローズすると、そのストリームに関連付けられたリソースがすべて解放されます。 ストリームのクローズに失敗すると、リソース・リークが発生することがあります。 try-with-resources文は、確実にストリームがクローズされるようにする役立つ構文を提供します。 

   Path dir = ...
   try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
       for (Path entry: stream) {
           ...
       }
   }

ディレクトリ・ストリームがクローズされたあとで、Iteratorを使用してそのディレクトリにさらにアクセスすると、ストリームの終わりに達したかのような動作をします。 Iteratorは、先読みが原因で、ディレクトリ・ストリームがクローズされたあとに1つまたは複数の要素を返すことがあります。 バッファに入っているこれらの要素が読み取られると、後続のhasNextメソッドの呼出しでfalseが返され、それに続くnextメソッドの呼出しでNoSuchElementExceptionがスローされます。

ディレクトリ・ストリームは、非同期クローズ可能である必要はありません。 ディレクトリからの読取りを行っているディレクトリ・ストリームのイテレータで、あるスレッドがブロックされているときに、別のスレッドがcloseメソッドを呼び出した場合、2つめのスレッドは読取り操作が完了するまでブロックされる可能性があります。

ディレクトリへのアクセス時に入出力エラーが検出された場合は、それによってIteratorのhasNextまたはnextメソッドはIOExceptionを原因としたDirectoryIteratorExceptionをスローします。 前述したように、hasNextメソッドは要素を1つ以上先読みすることが保証されています。 これは、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)

  • ネストされたクラスのサマリー

    ネストされたクラス 
    修飾子と型 インタフェース 説明
    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 - このディレクトリ・ストリームがクローズされたか、イテレータがすでに返されている場合