Интерфейс WatchKey

public interface WatchKey

Токен, представляющий регистрацию объекта watchable в WatchService.

Ключ наблюдения создается при регистрации наблюдаемого объекта в службе наблюдения. Ключ остается valid до тех пор, пока:

Он не отменён явно, вызывая его метод cancel, или
Отменён неявно, так как объект больше недоступен, или
Служба наблюдения closing.

Ключ наблюдения имеет состояние. При первоначальном создании ключ считается готовым. При обнаружении события ключ становится сигнализированным и помещается в очередь, чтобы его можно было получить, вызвав методы службы наблюдения poll или take. После сигнализации ключ остается в этом состоянии до тех пор, пока не будет вызван его метод reset для возвращения ключа в состояние готовности. События, обнаруженные, когда ключ находится в сигнализированном состоянии, помещаются в очередь, но не приводят к повторному размещению ключа в очередь для получения из службы наблюдения. События извлекаются, вызывая метод ключа pollEvents. Этот метод извлекает и удаляет все накопленные события для объекта. При первоначальном создании ключ наблюдения не имеет ожидающих событий. Как правило, события извлекаются, когда ключ находится в сигнализированном состоянии, что приводит к следующему шаблону:

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
         }
     }

Ключи наблюдения безопасны для использования несколькими потоками одновременно. В случаях, когда несколько потоков извлекают сигнализированные ключи из службы наблюдения, следует позаботиться о том, чтобы метод reset вызывался только после обработки событий для объекта. Это гарантирует, что в любой момент времени один поток обрабатывает события для объекта.

Since:: 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()

Сбрасывает этот ключ наблюдения.

Если этот ключ наблюдения был отменён или этот ключ наблюдения уже находится в состоянии готовности, то вызов этого метода не оказывает никакого влияния. В противном случае, если для объекта есть ожидающие события, этот ключ наблюдения немедленно помещается в очередь службы наблюдения. Если ожидающих событий нет, ключ наблюдения переводится в состояние готовности и остаётся в этом состоянии до тех пор, пока не будет обнаружено событие или ключ наблюдения не будет отменён.

Возвращает:: true если ключ наблюдения действителен и был сброшен, и false если ключ наблюдения не может быть сброшен, потому что он больше не valid

cancel

void cancel()

Отменяет регистрацию в службе наблюдения. После возврата ключ наблюдения будет недействительным. Если ключ наблюдения находится в очереди, ожидая извлечения из службы наблюдения, то он останется в очереди до тех пор, пока не будет удалён. Ожидающие события, если таковые имеются, остаются ожидающими и могут быть извлечены, вызвав метод pollEvents после отмены ключа.

Если этот ключ наблюдения уже был отменён, то вызов этого метода не оказывает никакого влияния. После отмены ключ наблюдения навсегда остаётся недействительным.

watchable

Watchable watchable()

Возвращает объект, для которого был создан этот ключ наблюдения. Этот метод будет продолжать возвращать объект даже после отмены ключа.

Поскольку WatchService предназначен для прямого отображения на механизм уведомлений о событиях файлов (если он доступен), многие детали о том, как наблюдаются зарегистрированные объекты, сильно зависят от реализации. Например, при наблюдении за каталогом на предмет изменений, и каталог перемещается или переименовывается в файловой системе, нет никакой гарантии, что ключ наблюдения будет отменён, и поэтому объект, возвращаемый этим методом, может больше не быть допустимым путем к каталогу.

Возвращает:: объект, для которого был создан этот ключ наблюдения