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

メソッドの詳細

iterator

Iterator<T> iterator()

この DirectoryStream に関連付けられたイテレータを返します。

定義:

iterator、インタフェース: Iterable<T>

戻り値:

この DirectoryStream に関連付けられたイテレータ

例外:

IllegalStateException - このディレクトリストリームがクローズされたか、イテレータがすでに返されている場合