3909N/A * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. 893N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 893N/A * This code is free software; you can redistribute it and/or modify it 893N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 893N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 893N/A * This code is distributed in the hope that it will be useful, but WITHOUT 893N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 893N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 893N/A * version 2 for more details (a copy is included in the LICENSE file that 893N/A * accompanied this code). 893N/A * You should have received a copy of the GNU General Public License version 893N/A * 2 along with this work; if not, write to the Free Software Foundation, 893N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 893N/A * A token representing the registration of a {@link Watchable watchable} object 893N/A * with a {@link WatchService}. 893N/A * <p> A watch key is created when a watchable object is registered with a watch 893N/A * service. The key remains {@link #isValid valid} until: 893N/A * <li> It is cancelled, explicitly, by invoking its {@link #cancel cancel} 893N/A * <li> Cancelled implicitly, because the object is no longer accessible, 893N/A * <li> By {@link WatchService#close closing} the watch service. </li> 893N/A * <p> A watch key has a state. When initially created the key is said to be 893N/A * <em>ready</em>. When an event is detected then the key is <em>signalled</em> 893N/A * and queued so that it can be retrieved by invoking the watch service's {@link 893N/A * WatchService#poll() poll} or {@link WatchService#take() take} methods. Once 893N/A * signalled, a key remains in this state until its {@link #reset reset} method 893N/A * is invoked to return the key to the ready state. Events detected while the 893N/A * key is in the signalled state are queued but do not cause the key to be 893N/A * re-queued for retrieval from the watch service. Events are retrieved by 893N/A * invoking the key's {@link #pollEvents pollEvents} method. This method 893N/A * retrieves and removes all events accumulated for the object. When initially 893N/A * created, a watch key has no pending events. Typically events are retrieved 893N/A * when the key is in the signalled state leading to the following idiom: 893N/A * WatchKey key = watcher.take(); 893N/A * for (WatchEvent<?> event: key.pollEvents()) { 893N/A * boolean valid = key.reset(); 893N/A * // object no longer registered 893N/A * <p> Watch keys are safe for use by multiple concurrent threads. Where there 893N/A * are several threads retrieving signalled keys from a watch service then care 893N/A * should be taken to ensure that the {@code reset} method is only invoked after 893N/A * the events for the object have been processed. This ensures that one thread 893N/A * is processing the events for an object at any time. 893N/A * Tells whether or not this watch key is valid. 893N/A * <p> A watch key is valid upon creation and remains until it is cancelled, 893N/A * or its watch service is closed. 893N/A * @return {@code true} if, and only if, this watch key is valid 893N/A * Retrieves and removes all pending events for this watch key, returning 893N/A * a {@code List} of the events that were retrieved. 893N/A * <p> Note that this method does not wait if there are no events pending. 1319N/A * @return the list of the events retrieved; may be empty 893N/A * Resets this watch key. 893N/A * <p> If this watch key has been cancelled or this watch key is already in 893N/A * the ready state then invoking this method has no effect. Otherwise 893N/A * if there are pending events for the object then this watch key is 893N/A * immediately re-queued to the watch service. If there are no pending 893N/A * events then the watch key is put into the ready state and will remain in 893N/A * that state until an event is detected or the watch key is cancelled. 908N/A * @return {@code true} if the watch key is valid and has been reset, and 893N/A * {@code false} if the watch key could not be reset because it is 893N/A * no longer {@link #isValid valid} 893N/A * Cancels the registration with the watch service. Upon return the watch key 893N/A * will be invalid. If the watch key is enqueued, waiting to be retrieved 893N/A * from the watch service, then it will remain in the queue until it is 893N/A * removed. Pending events, if any, remain pending and may be retrieved by 1319N/A * invoking the {@link #pollEvents pollEvents} method after the key is 893N/A * <p> If this watch key has already been cancelled then invoking this 893N/A * method has no effect. Once cancelled, a watch key remains forever invalid. 3471N/A * Returns the object for which this watch key was created. This method will 3471N/A * continue to return the object even after the key is cancelled. 3471N/A * <p> As the {@code WatchService} is intended to map directly on to the 3471N/A * native file event notification facility (where available) then many of 3471N/A * details on how registered objects are watched is highly implementation 3471N/A * specific. When watching a directory for changes for example, and the 3471N/A * directory is moved or renamed in the file system, there is no guarantee 3471N/A * that the watch key will be cancelled and so the object returned by this 3471N/A * method may no longer be a valid path to the directory. 3471N/A * @return the object for which this watch key was created