86 * facility is not available. Consequently, many of the details on how events
87 * are detected, their timeliness, and whether their ordering is preserved are
88 * highly implementation specific. For example, when a file in a watched
89 * directory is modified then it may result in a single {@link
90 * StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} event in some
91 * implementations but several events in other implementations. Short-lived
92 * files (meaning files that are deleted very quickly after they are created)
93 * may not be detected by primitive implementations that periodically poll the
94 * file system to detect changes.
95 *
96 * <p> If a watched file is not located on a local storage device then it is
97 * implementation specific if changes to the file can be detected. In particular,
98 * it is not required that changes to files carried out on remote systems be
99 * detected.
100 *
101 * @since 1.7
102 *
103 * @see FileSystem#newWatchService
104 */
105
106 public abstract class WatchService
107 implements Closeable
108 {
109 /**
110 * Initializes a new instance of this class.
111 */
112 protected WatchService() { }
113
114 /**
115 * Closes this watch service.
116 *
117 * <p> If a thread is currently blocked in the {@link #take take} or {@link
118 * #poll(long,TimeUnit) poll} methods waiting for a key to be queued then
119 * it immediately receives a {@link ClosedWatchServiceException}. Any
120 * valid keys associated with this watch service are {@link WatchKey#isValid
121 * invalidated}.
122 *
123 * <p> After a watch service is closed, any further attempt to invoke
124 * operations upon it will throw {@link ClosedWatchServiceException}.
125 * If this watch service is already closed then invoking this method
126 * has no effect.
127 *
128 * @throws IOException
129 * if an I/O error occurs
130 */
131 @Override
132 public abstract void close() throws IOException;
133
134 /**
135 * Retrieves and removes the next watch key, or {@code null} if none are
136 * present.
137 *
138 * @return the next watch key, or {@code null}
139 *
140 * @throws ClosedWatchServiceException
141 * if this watch service is closed
142 */
143 public abstract WatchKey poll();
144
145 /**
146 * Retrieves and removes the next watch key, waiting if necessary up to the
147 * specified wait time if none are yet present.
148 *
149 * @param timeout
150 * how to wait before giving up, in units of unit
151 * @param unit
152 * a {@code TimeUnit} determining how to interpret the timeout
153 * parameter
154 *
155 * @return the next watch key, or {@code null}
156 *
157 * @throws ClosedWatchServiceException
158 * if this watch service is closed, or it is closed while waiting
159 * for the next key
160 * @throws InterruptedException
161 * if interrupted while waiting
162 */
163 public abstract WatchKey poll(long timeout, TimeUnit unit)
164 throws InterruptedException;
165
166 /**
167 * Retrieves and removes next watch key, waiting if none are yet present.
168 *
169 * @return the next watch key
170 *
171 * @throws ClosedWatchServiceException
172 * if this watch service is closed, or it is closed while waiting
173 * for the next key
174 * @throws InterruptedException
175 * if interrupted while waiting
176 */
177 public abstract WatchKey take() throws InterruptedException;
178 }
|
86 * facility is not available. Consequently, many of the details on how events
87 * are detected, their timeliness, and whether their ordering is preserved are
88 * highly implementation specific. For example, when a file in a watched
89 * directory is modified then it may result in a single {@link
90 * StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} event in some
91 * implementations but several events in other implementations. Short-lived
92 * files (meaning files that are deleted very quickly after they are created)
93 * may not be detected by primitive implementations that periodically poll the
94 * file system to detect changes.
95 *
96 * <p> If a watched file is not located on a local storage device then it is
97 * implementation specific if changes to the file can be detected. In particular,
98 * it is not required that changes to files carried out on remote systems be
99 * detected.
100 *
101 * @since 1.7
102 *
103 * @see FileSystem#newWatchService
104 */
105
106 public interface WatchService
107 extends Closeable
108 {
109
110 /**
111 * Closes this watch service.
112 *
113 * <p> If a thread is currently blocked in the {@link #take take} or {@link
114 * #poll(long,TimeUnit) poll} methods waiting for a key to be queued then
115 * it immediately receives a {@link ClosedWatchServiceException}. Any
116 * valid keys associated with this watch service are {@link WatchKey#isValid
117 * invalidated}.
118 *
119 * <p> After a watch service is closed, any further attempt to invoke
120 * operations upon it will throw {@link ClosedWatchServiceException}.
121 * If this watch service is already closed then invoking this method
122 * has no effect.
123 *
124 * @throws IOException
125 * if an I/O error occurs
126 */
127 @Override
128 void close() throws IOException;
129
130 /**
131 * Retrieves and removes the next watch key, or {@code null} if none are
132 * present.
133 *
134 * @return the next watch key, or {@code null}
135 *
136 * @throws ClosedWatchServiceException
137 * if this watch service is closed
138 */
139 WatchKey poll();
140
141 /**
142 * Retrieves and removes the next watch key, waiting if necessary up to the
143 * specified wait time if none are yet present.
144 *
145 * @param timeout
146 * how to wait before giving up, in units of unit
147 * @param unit
148 * a {@code TimeUnit} determining how to interpret the timeout
149 * parameter
150 *
151 * @return the next watch key, or {@code null}
152 *
153 * @throws ClosedWatchServiceException
154 * if this watch service is closed, or it is closed while waiting
155 * for the next key
156 * @throws InterruptedException
157 * if interrupted while waiting
158 */
159 WatchKey poll(long timeout, TimeUnit unit)
160 throws InterruptedException;
161
162 /**
163 * Retrieves and removes next watch key, waiting if none are yet present.
164 *
165 * @return the next watch key
166 *
167 * @throws ClosedWatchServiceException
168 * if this watch service is closed, or it is closed while waiting
169 * for the next key
170 * @throws InterruptedException
171 * if interrupted while waiting
172 */
173 WatchKey take() throws InterruptedException;
174 }
|