View Javadoc
1   /*
2    * Copyright (c) 2007, 2013, 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   * <h2>Platform dependencies</h2>
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 }