モジュール java.base
パッケージ java.nio.file

インタフェースWatchKey


public interface WatchKey
watchableオブジェクトがWatchServiceに登録されていることを示すトークンです。

監視キーは、監視可能なオブジェクトが監視サービスに登録されると作成されます。 このキーは、次が行われるまで有効なままです。

  1. そのcancelメソッドの呼出しによって明示的に取り消される
  2. そのオブジェクトにアクセスできなくなったために暗黙的に取り消される
  3. 監視サービスを閉じることで取り消される

監視キーには状態があります。 最初の作成時、そのキーはreadyと呼ばれています。 イベントが検出されると、そのキーはsignalledとなり、監視サービスのpollまたはtakeメソッドの呼出しによって取得できるようにキューに入れられます。 キーは、いったんsignalledになると、そのresetメソッドが呼び出されてキーの状態がreadyに戻されるまで、その状態が続きます。 キーがsignalled状態にあるときに検出されたイベントはキューに入れられますが、それによってキーが監視サービスから取得できるように再度キューに入れられることはありません。 イベントを取得するには、キーのpollEventsメソッドを呼び出します。 このメソッドは、そのオブジェクトに関する蓄積されたすべてのイベントを取得して削除します。 最初の作成時、監視キーには保留中のイベントはありません。 通常、そのキーがsignalled状態になり、次のコードが実行されると、イベントが取得されます。

     for (;;) {
         // retrieve key
         WatchKey key = watcher.take();

         // process events
         for (WatchEvent<?> event: key.pollEvents()) {
             :
         }

         // reset the key
         boolean valid = key.reset();
         if (!valid) {
             // object no longer registered
         }
     }
 

監視キーは複数の並行スレッドで安全に使用できます。 監視サービスからsignalled状態のキーを取得するスレッドがいくつか存在する場合は、そのオブジェクトに関するイベントの処理が完了したあとでのみresetメソッドが呼び出されるように注意してください。 これにより、常に1つのスレッドが1つのオブジェクトに関するイベントを処理するようになります。

導入されたバージョン:
1.7
  • メソッドのサマリー

    修飾子と型 メソッド 説明
    void cancel()
    監視サービスへの登録を取り消します。
    boolean isValid()
    この監視キーが有効であるかどうかを判断します。
    List<WatchEvent<?>> pollEvents()
    この監視キーに関するすべての保留中のイベントを取得して削除し、取得したイベントのListを返します。
    boolean reset()
    この監視キーをリセットします。
    Watchable watchable()
    作成されたこの監視キーのオブジェクトを返します。
  • メソッドの詳細

    • isValid

      boolean isValid()
      この監視キーが有効であるかどうかを判断します。

      監視キーは作成時に有効になり、それが取り消されるか、その監視サービスが閉じられるまで有効な状態が続きます。

      戻り値:
      この監視キーが有効である場合にかぎりtrue
    • pollEvents

      List<WatchEvent<?>> pollEvents()
      この監視キーに関するすべての保留中のイベントを取得して削除し、取得したイベントのListを返します。

      このメソッドは保留中のイベントがない場合は待機しないので注意してください。

      戻り値:
      取得したイベントのリスト。空の場合もある
    • reset

      boolean reset()
      この監視キーをリセットします。

      この監視キーが取り消されている場合、またはこの監視キーがすでにready状態にある場合は、このメソッドを呼び出しても何の効果もありません。 それ以外の場合、そのオブジェクトに関する保留中のイベントがあれば、この監視キーはただちに監視サービスのキューに再度入れられます。 保留中のイベントがなければ、その監視キーはready状態になり、イベントが検出されるか、その監視キーが取り消されるまでその状態が続きます。

      戻り値:
      監視キーが有効でリセットされた場合はtrue。監視キーが有効ではなくなっているためにリセットできなかった場合はfalse
    • cancel

      void cancel()
      監視サービスへの登録を取り消します。 復帰すると、監視キーは無効になります。 監視キーがキューに入っていて、監視サービスから取得されるのを待機している場合、それは削除されるまでキューの中に残ります。 保留中のイベントがあれば、それは保留状態のままとなり、そのキーが取り消されたあともpollEventsメソッドを呼び出して取得できます。

      この監視キーがすでに取り消されている場合は、このメソッドを呼び出しても何の効果もありません。 いったん取り消された監視キーは以後永久に無効です。

    • watchable

      Watchable watchable()
      作成されたこの監視キーのオブジェクトを返します。 このメソッドは、そのキーが取り消されたあともオブジェクトを返し続けます。

      WatchServiceはネイティブ・ファイル・イベント通知機能(使用可能な場合)に直接マップするよう意図されているため、登録されたオブジェクトの監視方法に関する詳細の多くは実装によって大きく異なります。 たとえば、ディレクトリの変更を監視しているときに、そのディレクトリをファイル・システム内で移動または名前変更した場合、監視キーが取り消されるという保証はないため、このメソッドで返されるオブジェクトがそのディレクトリへの有効なパスでなくなっている可能性があります。

      戻り値:
      作成されたこの監視キーのオブジェクト