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
26package java.nio.file;
27
28import 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
45public 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     * StandardWatchEventKinds#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}
128