Интерфейс WatchService

public interface WatchService
extends Closeable

Сервис наблюдения, который наблюдает за зарегистрированными объектами на предмет изменений и событий. Например, файловый менеджер может использовать сервис наблюдения для мониторинга директории на предмет изменений, чтобы обновлять отображение списка файлов при создании или удалении файлов.

Объект Watchable регистрируется в сервисе наблюдения вызовом его метода register, возвращая WatchKey для представления регистрации. Когда обнаруживается событие для объекта, ключ сигнализируется, и если он не сигнализирован, он помещается в очередь сервиса наблюдения, чтобы его могли получить потребители, которые вызывают методы poll или take для получения ключей и обработки событий. После обработки событий потребитель вызывает метод ключа reset для сброса ключа, что позволяет ключу быть сигнализированным и повторно помещенным в очередь с новыми событиями.

Регистрация в сервисе наблюдения отменяется вызовом метода ключа cancel. Ключ, который находится в очереди в момент отмены, остается в очереди до тех пор, пока он не будет получен. В зависимости от объекта, ключ может быть отменён автоматически. Например, если наблюдается директория, и сервис наблюдения обнаруживает, что она была удалена или её файловая система больше недоступна. Когда ключ отменяется таким образом, он сигнализируется и помещается в очередь, если он не сигнализирован в данный момент. Чтобы гарантировать, что потребитель уведомлен, возвращаемое значение от метода reset указывает, является ли ключ валидным.

Сервис наблюдения безопасен для использования несколькими одновременными потребителями. Чтобы гарантировать, что только один потребитель обрабатывает события для конкретного объекта в любой момент времени, следует позаботиться о том, чтобы метод ключа reset вызывался только после обработки его событий. Метод close может быть вызван в любое время для закрытия сервиса, что приводит к тому, что любые потоки, ожидающие получения ключей, будут бросать ClosedWatchServiceException.

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

Когда событие сообщается о том, что файл в наблюдаемой директории был изменён, нет никакой гарантии, что программа (или программы), которые изменили файл, завершили свою работу. Следует позаботиться о координации доступа с другими программами, которые могут обновлять файл. Класс FileChannel определяет методы для блокировки областей файла от доступа другими программами.

Зависимости от платформы

Реализация, которая наблюдает события из файловой системы, предназначена для прямого отображения на родную систему уведомлений о событиях файлов, где это возможно, или для использования примитивного механизма, такого как опросный режим, когда родная система недоступна. Следовательно, многие детали о том, как обнаруживаются события, их актуальность и сохранение порядка, в значительной степени зависят от конкретной реализации. Например, когда файл в наблюдаемой директории модифицируется, это может привести к одному событию ENTRY_MODIFY в некоторых реализациях, но к нескольким событиям в других реализациях. Кратковременные файлы (то есть файлы, которые удаляются очень быстро после создания) могут не обнаруживаться примитивными реализациями, которые периодически опрашивают файловую систему для обнаружения изменений.

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

Методы

close

void close()
    throws IOException

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

Если поток в настоящее время заблокирован в методах take или poll, ожидая, пока ключ не будет помещен в очередь, он немедленно получает ClosedWatchServiceException. Любые валидные ключи, связанные с этим сервисом наблюдения, являются invalidated.

После закрытия сервиса наблюдения любая дальнейшая попытка вызвать операции над ним будет бросать ClosedWatchServiceException. Если этот сервис наблюдения уже закрыт, вызов этого метода не оказывает никакого влияния.

Определено в:

close в интерфейсе AutoCloseable

Определено в:

close в интерфейсе Closeable

Бросает:

IOException - если произошла ошибка ввода-вывода

poll

WatchKey poll()

Возвращает и удаляет следующий ключ наблюдения, или null если они отсутствуют.

Возвращает:

следующий ключ наблюдения, или null

Бросает:

ClosedWatchServiceException - если этот сервис наблюдения закрыт

poll(long,java.util.concurrent.TimeUnit)

WatchKey poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

Возвращает и удаляет следующий ключ наблюдения, ожидая, если необходимо, до указанного времени ожидания, если ключи еще отсутствуют.

Параметры:

timeout - время ожидания перед отказом, в единицах единицы

unit - объект TimeUnit, определяющий, как интерпретировать параметр тайм-аута

Возвращает:

следующий ключ наблюдения, или null

Бросает:

ClosedWatchServiceException - если этот сервис наблюдения закрыт, или он закрыт во время ожидания следующего ключа

InterruptedException - если прервано ожидание

take()

WatchKey take()
       throws InterruptedException

Возвращает и удаляет следующий ключ наблюдения, ожидая, если ключи еще отсутствуют.

Возвращает:

следующий ключ наблюдения

Бросает:

ClosedWatchServiceException - если этот сервис наблюдения закрыт, или он закрыт во время ожидания следующего ключа

InterruptedException - если прервано ожидание