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.util.List; 29 30 /** 31 * A token representing the registration of a {@link Watchable watchable} object 32 * with a {@link WatchService}. 33 * 34 * <p> A watch key is created when a watchable object is registered with a watch 35 * service. The key remains {@link #isValid valid} until: 36 * <ol> 37 * <li> It is cancelled, explicitly, by invoking its {@link #cancel cancel} 38 * method, or</li> 39 * <li> Cancelled implicitly, because the object is no longer accessible, 40 * or </li> 41 * <li> By {@link WatchService#close closing} the watch service. </li> 42 * </ol> 43 * 44 * <p> A watch key has a state. When initially created the key is said to be 45 * <em>ready</em>. When an event is detected then the key is <em>signalled</em> 46 * and queued so that it can be retrieved by invoking the watch service's {@link 47 * WatchService#poll() poll} or {@link WatchService#take() take} methods. Once 48 * signalled, a key remains in this state until its {@link #reset reset} method 49 * is invoked to return the key to the ready state. Events detected while the 50 * key is in the signalled state are queued but do not cause the key to be 51 * re-queued for retrieval from the watch service. Events are retrieved by 52 * invoking the key's {@link #pollEvents pollEvents} method. This method 53 * retrieves and removes all events accumulated for the object. When initially 54 * created, a watch key has no pending events. Typically events are retrieved 55 * when the key is in the signalled state leading to the following idiom: 56 * 57 * <pre> 58 * for (;;) { 59 * // retrieve key 60 * WatchKey key = watcher.take(); 61 * 62 * // process events 63 * for (WatchEvent<?> event: key.pollEvents()) { 64 * : 65 * } 66 * 67 * // reset the key 68 * boolean valid = key.reset(); 69 * if (!valid) { 70 * // object no longer registered 71 * } 72 * } 73 * </pre> 74 * 75 * <p> Watch keys are safe for use by multiple concurrent threads. Where there 76 * are several threads retrieving signalled keys from a watch service then care 77 * should be taken to ensure that the {@code reset} method is only invoked after 78 * the events for the object have been processed. This ensures that one thread 79 * is processing the events for an object at any time. 80 * 81 * @since 1.7 82 */ 83 84 public interface WatchKey { 85 86 /** 87 * Tells whether or not this watch key is valid. 88 * 89 * <p> A watch key is valid upon creation and remains until it is cancelled, 90 * or its watch service is closed. 91 * 92 * @return {@code true} if, and only if, this watch key is valid 93 */ isValid()94 boolean isValid(); 95 96 /** 97 * Retrieves and removes all pending events for this watch key, returning 98 * a {@code List} of the events that were retrieved. 99 * 100 * <p> Note that this method does not wait if there are no events pending. 101 * 102 * @return the list of the events retrieved; may be empty 103 */ pollEvents()104 List<WatchEvent<?>> pollEvents(); 105 106 /** 107 * Resets this watch key. 108 * 109 * <p> If this watch key has been cancelled or this watch key is already in 110 * the ready state then invoking this method has no effect. Otherwise 111 * if there are pending events for the object then this watch key is 112 * immediately re-queued to the watch service. If there are no pending 113 * events then the watch key is put into the ready state and will remain in 114 * that state until an event is detected or the watch key is cancelled. 115 * 116 * @return {@code true} if the watch key is valid and has been reset, and 117 * {@code false} if the watch key could not be reset because it is 118 * no longer {@link #isValid valid} 119 */ reset()120 boolean reset(); 121 122 /** 123 * Cancels the registration with the watch service. Upon return the watch key 124 * will be invalid. If the watch key is enqueued, waiting to be retrieved 125 * from the watch service, then it will remain in the queue until it is 126 * removed. Pending events, if any, remain pending and may be retrieved by 127 * invoking the {@link #pollEvents pollEvents} method after the key is 128 * cancelled. 129 * 130 * <p> If this watch key has already been cancelled then invoking this 131 * method has no effect. Once cancelled, a watch key remains forever invalid. 132 */ cancel()133 void cancel(); 134 135 /** 136 * Returns the object for which this watch key was created. This method will 137 * continue to return the object even after the key is cancelled. 138 * 139 * <p> As the {@code WatchService} is intended to map directly on to the 140 * native file event notification facility (where available) then many of 141 * details on how registered objects are watched is highly implementation 142 * specific. When watching a directory for changes for example, and the 143 * directory is moved or renamed in the file system, there is no guarantee 144 * that the watch key will be cancelled and so the object returned by this 145 * method may no longer be a valid path to the directory. 146 * 147 * @return the object for which this watch key was created 148 */ watchable()149 Watchable watchable(); 150 } 151