1 /* 2 * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.nio.file; 27 28 import java.io.Closeable; 29 import java.io.IOException; 30 import java.util.concurrent.TimeUnit; 31 32 /** 33 * A watch service that <em>watches</em> registered objects for changes and 34 * events. For example a file manager may use a watch service to monitor a 35 * directory for changes so that it can update its display of the list of files 36 * when files are created or deleted. 37 * 38 * <p> A {@link Watchable} object is registered with a watch service by invoking 39 * its {@link Watchable#register register} method, returning a {@link WatchKey} 40 * to represent the registration. When an event for an object is detected the 41 * key is <em>signalled</em>, and if not currently signalled, it is queued to 42 * the watch service so that it can be retrieved by consumers that invoke the 43 * {@link #poll() poll} or {@link #take() take} methods to retrieve keys 44 * and process events. Once the events have been processed the consumer 45 * invokes the key's {@link WatchKey#reset reset} method to reset the key which 46 * allows the key to be signalled and re-queued with further events. 47 * 48 * <p> Registration with a watch service is cancelled by invoking the key's 49 * {@link WatchKey#cancel cancel} method. A key that is queued at the time that 50 * it is cancelled remains in the queue until it is retrieved. Depending on the 51 * object, a key may be cancelled automatically. For example, suppose a 52 * directory is watched and the watch service detects that it has been deleted 53 * or its file system is no longer accessible. When a key is cancelled in this 54 * manner it is signalled and queued, if not currently signalled. To ensure 55 * that the consumer is notified the return value from the {@code reset} 56 * method indicates if the key is valid. 57 * 58 * <p> A watch service is safe for use by multiple concurrent consumers. To 59 * ensure that only one consumer processes the events for a particular object at 60 * any time then care should be taken to ensure that the key's {@code reset} 61 * method is only invoked after its events have been processed. The {@link 62 * #close close} method may be invoked at any time to close the service causing 63 * any threads waiting to retrieve keys, to throw {@code 64 * ClosedWatchServiceException}. 65 * 66 * <p> File systems may report events faster than they can be retrieved or 67 * processed and an implementation may impose an unspecified limit on the number 68 * of events that it may accumulate. Where an implementation <em>knowingly</em> 69 * discards events then it arranges for the key's {@link WatchKey#pollEvents 70 * pollEvents} method to return an element with an event type of {@link 71 * StandardWatchEventKind#OVERFLOW OVERFLOW}. This event can be used by the 72 * consumer as a trigger to re-examine the state of the object. 73 * 74 * <p> When an event is reported to indicate that a file in a watched directory 75 * has been modified then there is no guarantee that the program (or programs) 76 * that have modified the file have completed. Care should be taken to coordinate 77 * access with other programs that may be updating the file. 78 * The {@link java.nio.channels.FileChannel FileChannel} class defines methods 79 * to lock regions of a file against access by other programs. 80 * 81 * <h4>Platform dependencies</h4> 82 * 83 * <p> The implementation that observes events from the file system is intended 84 * to map directly on to the native file event notification facility where 85 * available, or to use a primitive mechanism, such as polling, when a native 86 * facility is not available. Consequently, many of the details on how events 87 * are detected, their timeliness, and whether their ordering is preserved are 88 * highly implementation specific. For example, when a file in a watched 89 * directory is modified then it may result in a single {@link 90 * StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} event in some 91 * implementations but several events in other implementations. Short-lived 92 * files (meaning files that are deleted very quickly after they are created) 93 * may not be detected by primitive implementations that periodically poll the 94 * file system to detect changes. 95 * 96 * <p> If a watched file is not located on a local storage device then it is 97 * implementation specific if changes to the file can be detected. In particular, 98 * it is not required that changes to files carried out on remote systems be 99 * detected. 100 * 101 * @since 1.7 102 * 103 * @see FileSystem#newWatchService 104 */ 105 106 public abstract class WatchService 107 implements Closeable 108 { 109 /** 110 * Initializes a new instance of this class. 111 */ 112 protected WatchService() { } 113 114 /** 115 * Closes this watch service. 116 * 117 * <p> If a thread is currently blocked in the {@link #take take} or {@link 118 * #poll(long,TimeUnit) poll} methods waiting for a key to be queued then 119 * it immediately receives a {@link ClosedWatchServiceException}. Any 120 * valid keys associated with this watch service are {@link WatchKey#isValid 121 * invalidated}. 122 * 123 * <p> After a watch service is closed, any further attempt to invoke 124 * operations upon it will throw {@link ClosedWatchServiceException}. 125 * If this watch service is already closed then invoking this method 126 * has no effect. 127 * 128 * @throws IOException 129 * if an I/O error occurs 130 */ 131 @Override 132 public abstract void close() throws IOException; 133 134 /** 135 * Retrieves and removes the next watch key, or {@code null} if none are 136 * present. 137 * 138 * @return the next watch key, or {@code null} 139 * 140 * @throws ClosedWatchServiceException 141 * if this watch service is closed 142 */ 143 public abstract WatchKey poll(); 144 145 /** 146 * Retrieves and removes the next watch key, waiting if necessary up to the 147 * specified wait time if none are yet present. 148 * 149 * @param timeout 150 * how to wait before giving up, in units of unit 151 * @param unit 152 * a {@code TimeUnit} determining how to interpret the timeout 153 * parameter 154 * 155 * @return the next watch key, or {@code null} 156 * 157 * @throws ClosedWatchServiceException 158 * if this watch service is closed, or it is closed while waiting 159 * for the next key 160 * @throws InterruptedException 161 * if interrupted while waiting 162 */ 163 public abstract WatchKey poll(long timeout, TimeUnit unit) 164 throws InterruptedException; 165 166 /** 167 * Retrieves and removes next watch key, waiting if none are yet present. 168 * 169 * @return the next watch key 170 * 171 * @throws ClosedWatchServiceException 172 * if this watch service is closed, or it is closed while waiting 173 * for the next key 174 * @throws InterruptedException 175 * if interrupted while waiting 176 */ 177 public abstract WatchKey take() throws InterruptedException; 178 }