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