A {@link Watchable} object is registered with a watch service by invoking * its {@link Watchable#register register} method, returning a {@link WatchKey} * to represent the registration. When an event for an object is detected the * key is signalled, and if not currently signalled, it is queued to * the watch service so that it can be retrieved by consumers that invoke the * {@link #poll() poll} or {@link #take() take} methods to retrieve keys * and process events. Once the events have been processed the consumer * invokes the key's {@link WatchKey#reset reset} method to reset the key which * allows the key to be signalled and re-queued with further events. * *
Registration with a watch service is cancelled by invoking the key's * {@link WatchKey#cancel cancel} method. A key that is queued at the time that * it is cancelled remains in the queue until it is retrieved. Depending on the * object, a key may be cancelled automatically. For example, suppose a * directory is watched and the watch service detects that it has been deleted * or its file system is no longer accessible. When a key is cancelled in this * manner it is signalled and queued, if not currently signalled. To ensure * that the consumer is notified the return value from the {@code reset} * method indicates if the key is valid. * *
A watch service is safe for use by multiple concurrent consumers. To * ensure that only one consumer processes the events for a particular object at * any time then care should be taken to ensure that the key's {@code reset} * method is only invoked after its events have been processed. The {@link * #close close} method may be invoked at any time to close the service causing * any threads waiting to retrieve keys, to throw {@code * ClosedWatchServiceException}. * *
File systems may report events faster than they can be retrieved or * processed and an implementation may impose an unspecified limit on the number * of events that it may accumulate. Where an implementation knowingly * discards events then it arranges for the key's {@link WatchKey#pollEvents * pollEvents} method to return an element with an event type of {@link * StandardWatchEventKind#OVERFLOW OVERFLOW}. This event can be used by the * consumer as a trigger to re-examine the state of the object. * *
When an event is reported to indicate that a file in a watched directory * has been modified then there is no guarantee that the program (or programs) * that have modified the file have completed. Care should be taken to coordinate * access with other programs that may be updating the file. * The {@link java.nio.channels.FileChannel FileChannel} class defines methods * to lock regions of a file against access by other programs. * *
The implementation that observes events from the file system is intended * to map directly on to the native file event notification facility where * available, or to use a primitive mechanism, such as polling, when a native * facility is not available. Consequently, many of the details on how events * are detected, their timeliness, and whether their ordering is preserved are * highly implementation specific. For example, when a file in a watched * directory is modified then it may result in a single {@link * StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} event in some * implementations but several events in other implementations. Short-lived * files (meaning files that are deleted very quickly after they are created) * may not be detected by primitive implementations that periodically poll the * file system to detect changes. * *
If a watched file is not located on a local storage device then it is * implementation specific if changes to the file can be detected. In particular, * it is not required that changes to files carried out on remote systems be * detected. * * @since 1.7 * * @see FileSystem#newWatchService */ public interface WatchService extends Closeable { /** * Closes this watch service. * *
If a thread is currently blocked in the {@link #take take} or {@link * #poll(long,TimeUnit) poll} methods waiting for a key to be queued then * it immediately receives a {@link ClosedWatchServiceException}. Any * valid keys associated with this watch service are {@link WatchKey#isValid * invalidated}. * *
After a watch service is closed, any further attempt to invoke * operations upon it will throw {@link ClosedWatchServiceException}. * If this watch service is already closed then invoking this method * has no effect. * * @throws IOException * if an I/O error occurs */ @Override void close() throws IOException; /** * Retrieves and removes the next watch key, or {@code null} if none are * present. * * @return the next watch key, or {@code null} * * @throws ClosedWatchServiceException * if this watch service is closed */ WatchKey poll(); /** * Retrieves and removes the next watch key, waiting if necessary up to the * specified wait time if none are yet present. * * @param timeout * how to wait before giving up, in units of unit * @param unit * a {@code TimeUnit} determining how to interpret the timeout * parameter * * @return the next watch key, or {@code null} * * @throws ClosedWatchServiceException * if this watch service is closed, or it is closed while waiting * for the next key * @throws InterruptedException * if interrupted while waiting */ WatchKey poll(long timeout, TimeUnit unit) throws InterruptedException; /** * Retrieves and removes next watch key, waiting if none are yet present. * * @return the next watch key * * @throws ClosedWatchServiceException * if this watch service is closed, or it is closed while waiting * for the next key * @throws InterruptedException * if interrupted while waiting */ WatchKey take() throws InterruptedException; }