- 型パラメータ:
T
- そのイテレータで返される要素の型
- すべてのスーパー・インタフェース:
AutoCloseable
,Closeable
,Iterable<T>
- 既知のすべてのサブインタフェース:
SecureDirectoryStream<T>
public interface DirectoryStream<T> extends Closeable, Iterable<T>
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 encountered during the iteration, the cause is an IOException throw ex.getCause(); } return result; }
- 導入されたバージョン:
- 1.7
- 関連項目:
Files.newDirectoryStream(Path)
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 インタフェース 説明 static interface
DirectoryStream.Filter<T>
ディレクトリ・エントリを受け入れるべきかフィルタするべきかを判断するオブジェクトによって実装されるインタフェースです。 -
メソッドのサマリー
インタフェース java.lang.Iterableで宣言されたメソッド
forEach, spliterator
-
メソッドの詳細
-
iterator
このDirectoryStream
に関連付けられたイテレータを返します。- 定義:
iterator
、インタフェース:Iterable<T>
- 戻り値:
- この
DirectoryStream
に関連付けられたイテレータ - 例外:
IllegalStateException
- このディレクトリ・ストリームがクローズされたか、イテレータがすでに返されている場合
-