Showing the changes to java/pkg/java/nio/file/WatchService.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,174 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2007, 2011, 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 | * StandardWatchEventKinds#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 | * StandardWatchEventKinds#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 interface WatchService | ||
| 107 | extends Closeable | ||
| 108 | { | ||
| 109 | |||
| 110 | /** | ||
| 111 | * Closes this watch service. | ||
| 112 | * | ||
| 113 | * <p> If a thread is currently blocked in the {@link #take take} or {@link | ||
| 114 | * #poll(long,TimeUnit) poll} methods waiting for a key to be queued then | ||
| 115 | * it immediately receives a {@link ClosedWatchServiceException}. Any | ||
| 116 | * valid keys associated with this watch service are {@link WatchKey#isValid | ||
| 117 | * invalidated}. | ||
| 118 | * | ||
| 119 | * <p> After a watch service is closed, any further attempt to invoke | ||
| 120 | * operations upon it will throw {@link ClosedWatchServiceException}. | ||
| 121 | * If this watch service is already closed then invoking this method | ||
| 122 | * has no effect. | ||
| 123 | * | ||
| 124 | * @throws IOException | ||
| 125 | * if an I/O error occurs | ||
| 126 | */ | ||
| 127 | @Override | ||
| 128 | void close() throws IOException; | ||
| 129 | |||
| 130 | /** | ||
| 131 | * Retrieves and removes the next watch key, or {@code null} if none are | ||
| 132 | * present. | ||
| 133 | * | ||
| 134 | * @return the next watch key, or {@code null} | ||
| 135 | * | ||
| 136 | * @throws ClosedWatchServiceException | ||
| 137 | * if this watch service is closed | ||
| 138 | */ | ||
| 139 | WatchKey poll(); | ||
| 140 | |||
| 141 | /** | ||
| 142 | * Retrieves and removes the next watch key, waiting if necessary up to the | ||
| 143 | * specified wait time if none are yet present. | ||
| 144 | * | ||
| 145 | * @param timeout | ||
| 146 | * how to wait before giving up, in units of unit | ||
| 147 | * @param unit | ||
| 148 | * a {@code TimeUnit} determining how to interpret the timeout | ||
| 149 | * parameter | ||
| 150 | * | ||
| 151 | * @return the next watch key, or {@code null} | ||
| 152 | * | ||
| 153 | * @throws ClosedWatchServiceException | ||
| 154 | * if this watch service is closed, or it is closed while waiting | ||
| 155 | * for the next key | ||
| 156 | * @throws InterruptedException | ||
| 157 | * if interrupted while waiting | ||
| 158 | */ | ||
| 159 | WatchKey poll(long timeout, TimeUnit unit) | ||
| 160 | throws InterruptedException; | ||
| 161 | |||
| 162 | /** | ||
| 163 | * Retrieves and removes next watch key, waiting if none are yet present. | ||
| 164 | * | ||
| 165 | * @return the next watch key | ||
| 166 | * | ||
| 167 | * @throws ClosedWatchServiceException | ||
| 168 | * if this watch service is closed, or it is closed while waiting | ||
| 169 | * for the next key | ||
| 170 | * @throws InterruptedException | ||
| 171 | * if interrupted while waiting | ||
| 172 | */ | ||
| 173 | WatchKey take() throws InterruptedException; | ||
| 174 | } | ||