Интерфейс 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

Установлено:

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

Установлено:

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

Исключения:

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

poll

WatchKey poll()

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

Возвращает:

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

Исключения:

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

poll

WatchKey poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

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

Параметры:

timeout - время ожидания, в единицах unit

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

Возвращает:

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

Исключения:

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

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

take

WatchKey take()
       throws InterruptedException

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

Возвращает:

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

Исключения:

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

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