インタフェース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イベントが発生することがありますが、他の実装では複数のイベントが発生することがあります。 有効期間の短いファイル(作成後すぐに削除されるファイルのこと)は、定期的にファイル・システ� をポーリングして変更を検出するプリミティブな実装では検出されないことがあります。

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

実装上のノート:

JDKのWatchService実装は、登録済の監視可能オブジェクトごとに最大512個の保留イベントをバッファリングします。 この制限を超えると、保留中のイベントが� �棄され、特別なOVERFLOWイベントがキューに入れられます。 この特別なイベントは、オブジェクトの状態を再確認するトリガーです。たとえば、監視ディレクトリをスキャンして、ディレクトリ内のファイルの更新されたリストを取得します。 保留中のイベントの制限は、システ� ・プロパティjdk.nio.file.WatchService.maxEventsPerPollを正の整数として解析する値に設定して、デフォルトから変更できます。 これは、変更量が多く、� �棄されたイベントの影響が大きい環境で役立つ� �合があります。

導入されたバージョン:

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 - timeoutパラメータの解釈方法を決定するTimeUnit

戻り値:

次の監視キーまたはnull

スロー:

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

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

take

WatchKey take() throws InterruptedException

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

戻り値:

次の監視キー

スロー:

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

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