64 * :
65 * }
66 *
67 * // reset the key
68 * boolean valid = key.reset();
69 * if (!valid) {
70 * // object no longer registered
71 * }
72 * }
73 * </pre>
74 *
75 * <p> Watch keys are safe for use by multiple concurrent threads. Where there
76 * are several threads retrieving signalled keys from a watch service then care
77 * should be taken to ensure that the {@code reset} method is only invoked after
78 * the events for the object have been processed. This ensures that one thread
79 * is processing the events for an object at any time.
80 *
81 * @since 1.7
82 */
83
84 public abstract class WatchKey {
85 /**
86 * Initializes a new instance of this class.
87 */
88 protected WatchKey() { }
89
90 /**
91 * Tells whether or not this watch key is valid.
92 *
93 * <p> A watch key is valid upon creation and remains until it is cancelled,
94 * or its watch service is closed.
95 *
96 * @return {@code true} if, and only if, this watch key is valid
97 */
98 public abstract boolean isValid();
99
100 /**
101 * Retrieves and removes all pending events for this watch key, returning
102 * a {@code List} of the events that were retrieved.
103 *
104 * <p> Note that this method does not wait if there are no events pending.
105 *
106 * @return the list of the events retrieved; may be empty
107 */
108 public abstract List<WatchEvent<?>> pollEvents();
109
110 /**
111 * Resets this watch key.
112 *
113 * <p> If this watch key has been cancelled or this watch key is already in
114 * the ready state then invoking this method has no effect. Otherwise
115 * if there are pending events for the object then this watch key is
116 * immediately re-queued to the watch service. If there are no pending
117 * events then the watch key is put into the ready state and will remain in
118 * that state until an event is detected or the watch key is cancelled.
119 *
120 * @return {@code true} if the watch key is valid and has been reset, and
121 * {@code false} if the watch key could not be reset because it is
122 * no longer {@link #isValid valid}
123 */
124 public abstract boolean reset();
125
126 /**
127 * Cancels the registration with the watch service. Upon return the watch key
128 * will be invalid. If the watch key is enqueued, waiting to be retrieved
129 * from the watch service, then it will remain in the queue until it is
130 * removed. Pending events, if any, remain pending and may be retrieved by
131 * invoking the {@link #pollEvents pollEvents} method after the key is
132 * cancelled.
133 *
134 * <p> If this watch key has already been cancelled then invoking this
135 * method has no effect. Once cancelled, a watch key remains forever invalid.
136 */
137 public abstract void cancel();
138 }
|
64 * :
65 * }
66 *
67 * // reset the key
68 * boolean valid = key.reset();
69 * if (!valid) {
70 * // object no longer registered
71 * }
72 * }
73 * </pre>
74 *
75 * <p> Watch keys are safe for use by multiple concurrent threads. Where there
76 * are several threads retrieving signalled keys from a watch service then care
77 * should be taken to ensure that the {@code reset} method is only invoked after
78 * the events for the object have been processed. This ensures that one thread
79 * is processing the events for an object at any time.
80 *
81 * @since 1.7
82 */
83
84 public interface WatchKey {
85
86 /**
87 * Tells whether or not this watch key is valid.
88 *
89 * <p> A watch key is valid upon creation and remains until it is cancelled,
90 * or its watch service is closed.
91 *
92 * @return {@code true} if, and only if, this watch key is valid
93 */
94 boolean isValid();
95
96 /**
97 * Retrieves and removes all pending events for this watch key, returning
98 * a {@code List} of the events that were retrieved.
99 *
100 * <p> Note that this method does not wait if there are no events pending.
101 *
102 * @return the list of the events retrieved; may be empty
103 */
104 List<WatchEvent<?>> pollEvents();
105
106 /**
107 * Resets this watch key.
108 *
109 * <p> If this watch key has been cancelled or this watch key is already in
110 * the ready state then invoking this method has no effect. Otherwise
111 * if there are pending events for the object then this watch key is
112 * immediately re-queued to the watch service. If there are no pending
113 * events then the watch key is put into the ready state and will remain in
114 * that state until an event is detected or the watch key is cancelled.
115 *
116 * @return {@code true} if the watch key is valid and has been reset, and
117 * {@code false} if the watch key could not be reset because it is
118 * no longer {@link #isValid valid}
119 */
120 boolean reset();
121
122 /**
123 * Cancels the registration with the watch service. Upon return the watch key
124 * will be invalid. If the watch key is enqueued, waiting to be retrieved
125 * from the watch service, then it will remain in the queue until it is
126 * removed. Pending events, if any, remain pending and may be retrieved by
127 * invoking the {@link #pollEvents pollEvents} method after the key is
128 * cancelled.
129 *
130 * <p> If this watch key has already been cancelled then invoking this
131 * method has no effect. Once cancelled, a watch key remains forever invalid.
132 */
133 void cancel();
134
135 /**
136 * Returns the object for which this watch key was created. This method will
137 * continue to return the object even after the key is cancelled.
138 *
139 * <p> As the {@code WatchService} is intended to map directly on to the
140 * native file event notification facility (where available) then many of
141 * details on how registered objects are watched is highly implementation
142 * specific. When watching a directory for changes for example, and the
143 * directory is moved or renamed in the file system, there is no guarantee
144 * that the watch key will be cancelled and so the object returned by this
145 * method may no longer be a valid path to the directory.
146 *
147 * @return the object for which this watch key was created
148 */
149 //T watchable();
150 }
|