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