java.nio.file

インタフェース WatchService

すべてのスーパーインタフェース:

AutoCloseable, Closeable

public interface WatchService
extends Closeable

登録されたオブジェクトの変更およびイベントを監視する監視サービスです。たとえば、ファイルマネージャーでは、ファイルが作成または削除されたときにファイルリストの表示を更新できるように、監視サービスを使ってディレクトリの変更を監視することがあります。

register メソッドを呼び出して Watchable オブジェクトを監視サービスに登録すると、その登録を表す WatchKey が返されます。オブジェクトのイベントが検出されると、その鍵は signalled になり、現在 signalled になっていない場合は、poll または take メソッドを呼び出して鍵の取得やイベントの処理を行うコンシューマが取得できるように、監視サービスのキューに入れられます。イベントの処理が完了すると、コンシューマはその鍵の reset メソッドを呼び出して鍵をリセットします。これにより、さらにイベントがあれば、その鍵は signalled になり、再度キューに入れられるようになります。

監視サービスへの登録は、鍵の cancel メソッドを呼び出すことにより取り消されます。取り消される時点でキューに入っている鍵は、それが取得されるまでキューの中に残ります。オブジェクトによっては、鍵が自動的に取り消されることもあります。たとえば、ディレクトリが監視されていて、監視サービスによって、それが削除されてしまったか、そのファイルシステムにアクセスできなくなったことが検出されたとします。こうして鍵が取り消されると、それが現在 signalled になっていなければ、signalled になってキューに入れられます。コンシューマが通知を受けられるように、reset メソッドからの戻り値によって、その鍵が有効かどうかが示されます。

監視サービスは、複数の並行コンシューマで安全に使用できます。常に特定のオブジェクトのイベントを処理するコンシューマが 1 つのみになるように、その鍵の reset メソッドがそのイベントの処理の完了後にのみ呼び出されるように注意してください。close メソッドは、サービスを閉じるためにいつでも呼び出すことができ、それによって鍵の取得を待機しているスレッドから ClosedWatchServiceException がスローされます。

ファイルシステムはイベントをその取得または処理能力を超える速さで報告する可能性があるため、実装では蓄積できるイベントの数に不特定の制限を課す場合があります。実装では、イベントを故意に破棄する場合、鍵の pollEvents メソッドが OVERFLOW というイベントタイプで要素を返すように調整します。このイベントは、コンシューマがオブジェクトの状態を見直すためにトリガーとして使用できます。

監視対象のディレクトリ内のファイルが変更されたことを知らせるイベントが報告された場合、そのファイルを変更したプログラムが完了しているという保証はありません。そのファイルを更新している可能性のある他のプログラムとのアクセスの調整に注意が必要です。FileChannel クラスには、ファイルの領域を他のプログラムからアクセスできないようにするメソッドが定義されています。

プラットフォームの依存性

ファイルシステムからイベントを監視する実装は、ネイティブファイルイベント通知機能 (使用可能な場合) に直接マップしたり、ネイティブ機能が使用できない場合はポーリングなどの基本メカニズムを使用したりするよう意図されています。その結果、イベントの検出方法、その適用のタイミング、およびその順序が維持されるかどうかに関する詳細の多くは、実装によって大きく異なります。たとえば、監視対象のディレクトリ内のファイルが変更されると、一部の実装では単一の ENTRY_MODIFY イベントが発生することがありますが、他の実装では複数のイベントが発生することがあります。有効期間の短いファイル (作成後すぐに削除されるファイルのこと) は、定期的にファイルシステムをポーリングして変更を検出するプリミティブな実装では検出されないことがあります。

監視されたファイルがローカルストレージデバイス上にない場合、そのファイルへの変更を検出できるかどうかは、実装に固有です。特に、リモートシステム上で行われたファイルへの変更は検出される必要はありません。

導入されたバージョン:

1.7

関連項目:

FileSystem.newWatchService()

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
void	close() この監視サービスを閉じます。
WatchKey	poll() 次の監視鍵を取得して削除します。何も存在しない場合は null を返します。
WatchKey	poll(long timeout, TimeUnit unit) 次の監視鍵を取得して削除します。何も存在しない場合は、必要に応じて指定された待機時間まで待機します。
WatchKey	take() 次の監視鍵を取得して削除します。何も存在しない場合は待機します。

メソッドの詳細

close

void close()
           throws IOException

この監視サービスを閉じます。

鍵がキューに入れられるのを待機している take または poll メソッドでスレッドが現在ブロックされている場合、それはすぐに ClosedWatchServiceException を受け取ります。この監視サービスに関連付けられている有効な鍵は invalidated です。

監視サービスが閉じたあとで、それに対してさらに操作を呼び出そうとすると、ClosedWatchServiceException がスローされます。この監視サービスがすでに閉じている場合は、このメソッドを呼び出しても何の効果もありません。

定義:

close、インタフェース: AutoCloseable

定義:

close、インタフェース: Closeable

例外:

IOException - 入出力エラーが発生した場合

poll

WatchKey poll()

次の監視鍵を取得して削除します。何も存在しない場合は null を返します。

戻り値:

次の監視鍵または null

例外:

ClosedWatchServiceException - この監視サービスが閉じている場合

poll

WatchKey poll(long timeout,
            TimeUnit unit)
              throws InterruptedException

次の監視鍵を取得して削除します。何も存在しない場合は、必要に応じて指定された待機時間まで待機します。

パラメータ:

timeout - 処理を中止するまでの待機時間。単位は unit

unit - timeout パラメータの解釈方法を決定する TimeUnit

戻り値:

次の監視鍵または null

例外:

ClosedWatchServiceException - この監視サービスが閉じられた場合、または次の鍵の待機中に閉じられた場合

InterruptedException - 待機中に割り込みが発生した場合

take

WatchKey take()
              throws InterruptedException

次の監視鍵を取得して削除します。何も存在しない場合は待機します。

戻り値:

次の監視鍵

例外:

ClosedWatchServiceException - この監視サービスが閉じられた場合、または次の鍵の待機中に閉じられた場合

InterruptedException - 待機中に割り込みが発生した場合