1e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera/* 2e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Copyright (c) 2007, 2011, 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.IOException; 29e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 30e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera/** 31e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * An object that may be registered with a watch service so that it can be 32e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <em>watched</em> for changes and events. 33e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 34e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> This interface defines the {@link #register register} method to register 35e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the object with a {@link WatchService} returning a {@link WatchKey} to 36e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * represent the registration. An object may be registered with more than one 37e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * watch service. Registration with a watch service is cancelled by invoking the 38e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * key's {@link WatchKey#cancel cancel} method. 39e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 40e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @since 1.7 41e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 42e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @see Path#register 43e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 44e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 45e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmerapublic interface Watchable { 46e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 47e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 48e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Registers an object with a watch service. 49e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 50e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> If the file system object identified by this object is currently 51e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * registered with the watch service then the watch key, representing that 52e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * registration, is returned after changing the event set or modifiers to 53e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * those specified by the {@code events} and {@code modifiers} parameters. 54e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Changing the event set does not cause pending events for the object to be 55e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * discarded. Objects are automatically registered for the {@link 56e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * StandardWatchEventKinds#OVERFLOW OVERFLOW} event. This event is not 57e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * required to be present in the array of events. 58e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 59e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> Otherwise the file system object has not yet been registered with the 60e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * given watch service, so it is registered and the resulting new key is 61e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * returned. 62e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 63e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> Implementations of this interface should specify the events they 64e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * support. 65e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 66e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param watcher 67e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the watch service to which this object is to be registered 68e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param events 69e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the events for which this object should be registered 70e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param modifiers 71e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the modifiers, if any, that modify how the object is registered 72e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 73e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return a key representing the registration of this object with the 74e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * given watch service 75e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 76e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws UnsupportedOperationException 77e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if unsupported events or modifiers are specified 78e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IllegalArgumentException 79e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if an invalid of combination of events are modifiers are specified 80e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws ClosedWatchServiceException 81e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if the watch service is closed 82e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IOException 83e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if an I/O error occurs 84e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws SecurityException 85e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if a security manager is installed and it denies an unspecified 86e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * permission required to monitor this object. Implementations of 87e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * this interface should specify the permission checks. 88e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 89e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera WatchKey register(WatchService watcher, 90e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera WatchEvent.Kind<?>[] events, 91e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera WatchEvent.Modifier... modifiers) 92e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera throws IOException; 93e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 94e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 95e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 96e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Registers an object with a watch service. 97e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 98e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> An invocation of this method behaves in exactly the same way as the 99e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * invocation 100e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <pre> 101e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * watchable.{@link #register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) register}(watcher, events, new WatchEvent.Modifier[0]); 102e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </pre> 103e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 104e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param watcher 105e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the watch service to which this object is to be registered 106e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param events 107e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the events for which this object should be registered 108e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 109e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return a key representing the registration of this object with the 110e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * given watch service 111e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 112e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws UnsupportedOperationException 113e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if unsupported events are specified 114e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IllegalArgumentException 115e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if an invalid of combination of events are specified 116e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws ClosedWatchServiceException 117e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if the watch service is closed 118e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IOException 119e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if an I/O error occurs 120e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws SecurityException 121e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if a security manager is installed and it denies an unspecified 122e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * permission required to monitor this object. Implementations of 123e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * this interface should specify the permission checks. 124e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 125e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera WatchKey register(WatchService watcher, WatchEvent.Kind<?>... events) 126e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera throws IOException; 127e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera} 128