1 /*
   2  * Copyright (c) 2007, 2009, 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  * StandardWatchEventKind#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  * 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 }