モジュール java.base
パッケージ 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 - 待機中に割込みが発生した場合