History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/file/WatchService.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/nio/file/WatchService.java+174−0
@@ -0,0 +1,174 @@
1+/*
2+ * Copyright (c) 2007, 2011, Oracle and/or its affiliates. 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. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.file;
27+
28+import java.io.Closeable;
29+import java.io.IOException;
30+import java.util.concurrent.TimeUnit;
31+
32+/**
33+ * A watch service that <em>watches</em> registered objects for changes and
34+ * events. For example a file manager may use a watch service to monitor a
35+ * directory for changes so that it can update its display of the list of files
36+ * when files are created or deleted.
37+ *
38+ * <p> A {@link Watchable} object is registered with a watch service by invoking
39+ * its {@link Watchable#register register} method, returning a {@link WatchKey}
40+ * to represent the registration. When an event for an object is detected the
41+ * key is <em>signalled</em>, and if not currently signalled, it is queued to
42+ * the watch service so that it can be retrieved by consumers that invoke the
43+ * {@link #poll() poll} or {@link #take() take} methods to retrieve keys
44+ * and process events. Once the events have been processed the consumer
45+ * invokes the key's {@link WatchKey#reset reset} method to reset the key which
46+ * allows the key to be signalled and re-queued with further events.
47+ *
48+ * <p> Registration with a watch service is cancelled by invoking the key's
49+ * {@link WatchKey#cancel cancel} method. A key that is queued at the time that
50+ * it is cancelled remains in the queue until it is retrieved. Depending on the
51+ * object, a key may be cancelled automatically. For example, suppose a
52+ * directory is watched and the watch service detects that it has been deleted
53+ * or its file system is no longer accessible. When a key is cancelled in this
54+ * manner it is signalled and queued, if not currently signalled. To ensure
55+ * that the consumer is notified the return value from the {@code reset}
56+ * method indicates if the key is valid.
57+ *
58+ * <p> A watch service is safe for use by multiple concurrent consumers. To
59+ * ensure that only one consumer processes the events for a particular object at
60+ * any time then care should be taken to ensure that the key's {@code reset}
61+ * method is only invoked after its events have been processed. The {@link
62+ * #close close} method may be invoked at any time to close the service causing
63+ * any threads waiting to retrieve keys, to throw {@code
64+ * ClosedWatchServiceException}.
65+ *
66+ * <p> File systems may report events faster than they can be retrieved or
67+ * processed and an implementation may impose an unspecified limit on the number
68+ * of events that it may accumulate. Where an implementation <em>knowingly</em>
69+ * discards events then it arranges for the key's {@link WatchKey#pollEvents
70+ * pollEvents} method to return an element with an event type of {@link
71+ * StandardWatchEventKinds#OVERFLOW OVERFLOW}. This event can be used by the
72+ * consumer as a trigger to re-examine the state of the object.
73+ *
74+ * <p> When an event is reported to indicate that a file in a watched directory
75+ * has been modified then there is no guarantee that the program (or programs)
76+ * that have modified the file have completed. Care should be taken to coordinate
77+ * access with other programs that may be updating the file.
78+ * The {@link java.nio.channels.FileChannel FileChannel} class defines methods
79+ * to lock regions of a file against access by other programs.
80+ *
81+ * <h4>Platform dependencies</h4>
82+ *
83+ * <p> The implementation that observes events from the file system is intended
84+ * to map directly on to the native file event notification facility where
85+ * available, or to use a primitive mechanism, such as polling, when a native
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+ * StandardWatchEventKinds#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+}