2
|
1 |
/*
|
5506
|
2 |
* Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.
|
2
|
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
|
5506
|
7 |
* published by the Free Software Foundation. Oracle designates this
|
2
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
5506
|
9 |
* by Oracle in the LICENSE file that accompanied this code.
|
2
|
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 |
*
|
5506
|
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.
|
2
|
24 |
*/
|
|
25 |
|
|
26 |
package java.nio.channels;
|
|
27 |
|
|
28 |
import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
|
|
29 |
import java.io.IOException;
|
|
30 |
|
|
31 |
|
|
32 |
/**
|
|
33 |
* A token representing the registration of a {@link SelectableChannel} with a
|
|
34 |
* {@link Selector}.
|
|
35 |
*
|
|
36 |
* <p> A selection key is created each time a channel is registered with a
|
|
37 |
* selector. A key remains valid until it is <i>cancelled</i> by invoking its
|
|
38 |
* {@link #cancel cancel} method, by closing its channel, or by closing its
|
|
39 |
* selector. Cancelling a key does not immediately remove it from its
|
|
40 |
* selector; it is instead added to the selector's <a
|
|
41 |
* href="Selector.html#ks"><i>cancelled-key set</i></a> for removal during the
|
|
42 |
* next selection operation. The validity of a key may be tested by invoking
|
|
43 |
* its {@link #isValid isValid} method.
|
|
44 |
*
|
|
45 |
* <a name="opsets">
|
|
46 |
*
|
|
47 |
* <p> A selection key contains two <i>operation sets</i> represented as
|
|
48 |
* integer values. Each bit of an operation set denotes a category of
|
|
49 |
* selectable operations that are supported by the key's channel.
|
|
50 |
*
|
|
51 |
* <ul>
|
|
52 |
*
|
|
53 |
* <li><p> The <i>interest set</i> determines which operation categories will
|
|
54 |
* be tested for readiness the next time one of the selector's selection
|
|
55 |
* methods is invoked. The interest set is initialized with the value given
|
|
56 |
* when the key is created; it may later be changed via the {@link
|
|
57 |
* #interestOps(int)} method. </p></li>
|
|
58 |
*
|
|
59 |
* <li><p> The <i>ready set</i> identifies the operation categories for which
|
|
60 |
* the key's channel has been detected to be ready by the key's selector.
|
|
61 |
* The ready set is initialized to zero when the key is created; it may later
|
|
62 |
* be updated by the selector during a selection operation, but it cannot be
|
|
63 |
* updated directly. </p></li>
|
|
64 |
*
|
|
65 |
* </ul>
|
|
66 |
*
|
|
67 |
* <p> That a selection key's ready set indicates that its channel is ready for
|
|
68 |
* some operation category is a hint, but not a guarantee, that an operation in
|
|
69 |
* such a category may be performed by a thread without causing the thread to
|
|
70 |
* block. A ready set is most likely to be accurate immediately after the
|
|
71 |
* completion of a selection operation. It is likely to be made inaccurate by
|
|
72 |
* external events and by I/O operations that are invoked upon the
|
|
73 |
* corresponding channel.
|
|
74 |
*
|
|
75 |
* <p> This class defines all known operation-set bits, but precisely which
|
|
76 |
* bits are supported by a given channel depends upon the type of the channel.
|
|
77 |
* Each subclass of {@link SelectableChannel} defines an {@link
|
|
78 |
* SelectableChannel#validOps() validOps()} method which returns a set
|
|
79 |
* identifying just those operations that are supported by the channel. An
|
|
80 |
* attempt to set or test an operation-set bit that is not supported by a key's
|
|
81 |
* channel will result in an appropriate run-time exception.
|
|
82 |
*
|
|
83 |
* <p> It is often necessary to associate some application-specific data with a
|
|
84 |
* selection key, for example an object that represents the state of a
|
|
85 |
* higher-level protocol and handles readiness notifications in order to
|
|
86 |
* implement that protocol. Selection keys therefore support the
|
|
87 |
* <i>attachment</i> of a single arbitrary object to a key. An object can be
|
|
88 |
* attached via the {@link #attach attach} method and then later retrieved via
|
|
89 |
* the {@link #attachment() attachment} method.
|
|
90 |
*
|
|
91 |
* <p> Selection keys are safe for use by multiple concurrent threads. The
|
|
92 |
* operations of reading and writing the interest set will, in general, be
|
|
93 |
* synchronized with certain operations of the selector. Exactly how this
|
|
94 |
* synchronization is performed is implementation-dependent: In a naive
|
|
95 |
* implementation, reading or writing the interest set may block indefinitely
|
|
96 |
* if a selection operation is already in progress; in a high-performance
|
|
97 |
* implementation, reading or writing the interest set may block briefly, if at
|
|
98 |
* all. In any case, a selection operation will always use the interest-set
|
|
99 |
* value that was current at the moment that the operation began. </p>
|
|
100 |
*
|
|
101 |
*
|
|
102 |
* @author Mark Reinhold
|
|
103 |
* @author JSR-51 Expert Group
|
|
104 |
* @since 1.4
|
|
105 |
*
|
|
106 |
* @see SelectableChannel
|
|
107 |
* @see Selector
|
|
108 |
*/
|
|
109 |
|
|
110 |
public abstract class SelectionKey {
|
|
111 |
|
|
112 |
/**
|
|
113 |
* Constructs an instance of this class.
|
|
114 |
*/
|
|
115 |
protected SelectionKey() { }
|
|
116 |
|
|
117 |
|
|
118 |
// -- Channel and selector operations --
|
|
119 |
|
|
120 |
/**
|
|
121 |
* Returns the channel for which this key was created. This method will
|
|
122 |
* continue to return the channel even after the key is cancelled. </p>
|
|
123 |
*
|
|
124 |
* @return This key's channel
|
|
125 |
*/
|
|
126 |
public abstract SelectableChannel channel();
|
|
127 |
|
|
128 |
/**
|
|
129 |
* Returns the selector for which this key was created. This method will
|
|
130 |
* continue to return the selector even after the key is cancelled. </p>
|
|
131 |
*
|
|
132 |
* @return This key's selector
|
|
133 |
*/
|
|
134 |
public abstract Selector selector();
|
|
135 |
|
|
136 |
/**
|
|
137 |
* Tells whether or not this key is valid.
|
|
138 |
*
|
|
139 |
* <p> A key is valid upon creation and remains so until it is cancelled,
|
|
140 |
* its channel is closed, or its selector is closed. </p>
|
|
141 |
*
|
|
142 |
* @return <tt>true</tt> if, and only if, this key is valid
|
|
143 |
*/
|
|
144 |
public abstract boolean isValid();
|
|
145 |
|
|
146 |
/**
|
|
147 |
* Requests that the registration of this key's channel with its selector
|
|
148 |
* be cancelled. Upon return the key will be invalid and will have been
|
|
149 |
* added to its selector's cancelled-key set. The key will be removed from
|
|
150 |
* all of the selector's key sets during the next selection operation.
|
|
151 |
*
|
|
152 |
* <p> If this key has already been cancelled then invoking this method has
|
|
153 |
* no effect. Once cancelled, a key remains forever invalid. </p>
|
|
154 |
*
|
|
155 |
* <p> This method may be invoked at any time. It synchronizes on the
|
|
156 |
* selector's cancelled-key set, and therefore may block briefly if invoked
|
|
157 |
* concurrently with a cancellation or selection operation involving the
|
|
158 |
* same selector. </p>
|
|
159 |
*/
|
|
160 |
public abstract void cancel();
|
|
161 |
|
|
162 |
|
|
163 |
// -- Operation-set accessors --
|
|
164 |
|
|
165 |
/**
|
|
166 |
* Retrieves this key's interest set.
|
|
167 |
*
|
|
168 |
* <p> It is guaranteed that the returned set will only contain operation
|
|
169 |
* bits that are valid for this key's channel.
|
|
170 |
*
|
|
171 |
* <p> This method may be invoked at any time. Whether or not it blocks,
|
|
172 |
* and for how long, is implementation-dependent. </p>
|
|
173 |
*
|
|
174 |
* @return This key's interest set
|
|
175 |
*
|
|
176 |
* @throws CancelledKeyException
|
|
177 |
* If this key has been cancelled
|
|
178 |
*/
|
|
179 |
public abstract int interestOps();
|
|
180 |
|
|
181 |
/**
|
|
182 |
* Sets this key's interest set to the given value.
|
|
183 |
*
|
|
184 |
* <p> This method may be invoked at any time. Whether or not it blocks,
|
|
185 |
* and for how long, is implementation-dependent. </p>
|
|
186 |
*
|
|
187 |
* @param ops The new interest set
|
|
188 |
*
|
|
189 |
* @return This selection key
|
|
190 |
*
|
|
191 |
* @throws IllegalArgumentException
|
|
192 |
* If a bit in the set does not correspond to an operation that
|
|
193 |
* is supported by this key's channel, that is, if
|
18156
|
194 |
* {@code (ops & ~channel().validOps()) != 0}
|
2
|
195 |
*
|
|
196 |
* @throws CancelledKeyException
|
|
197 |
* If this key has been cancelled
|
|
198 |
*/
|
|
199 |
public abstract SelectionKey interestOps(int ops);
|
|
200 |
|
|
201 |
/**
|
|
202 |
* Retrieves this key's ready-operation set.
|
|
203 |
*
|
|
204 |
* <p> It is guaranteed that the returned set will only contain operation
|
|
205 |
* bits that are valid for this key's channel. </p>
|
|
206 |
*
|
|
207 |
* @return This key's ready-operation set
|
|
208 |
*
|
|
209 |
* @throws CancelledKeyException
|
|
210 |
* If this key has been cancelled
|
|
211 |
*/
|
|
212 |
public abstract int readyOps();
|
|
213 |
|
|
214 |
|
|
215 |
// -- Operation bits and bit-testing convenience methods --
|
|
216 |
|
|
217 |
/**
|
|
218 |
* Operation-set bit for read operations.
|
|
219 |
*
|
|
220 |
* <p> Suppose that a selection key's interest set contains
|
|
221 |
* <tt>OP_READ</tt> at the start of a <a
|
|
222 |
* href="Selector.html#selop">selection operation</a>. If the selector
|
|
223 |
* detects that the corresponding channel is ready for reading, has reached
|
|
224 |
* end-of-stream, has been remotely shut down for further reading, or has
|
|
225 |
* an error pending, then it will add <tt>OP_READ</tt> to the key's
|
|
226 |
* ready-operation set and add the key to its selected-key set. </p>
|
|
227 |
*/
|
|
228 |
public static final int OP_READ = 1 << 0;
|
|
229 |
|
|
230 |
/**
|
|
231 |
* Operation-set bit for write operations. </p>
|
|
232 |
*
|
|
233 |
* <p> Suppose that a selection key's interest set contains
|
|
234 |
* <tt>OP_WRITE</tt> at the start of a <a
|
|
235 |
* href="Selector.html#selop">selection operation</a>. If the selector
|
|
236 |
* detects that the corresponding channel is ready for writing, has been
|
|
237 |
* remotely shut down for further writing, or has an error pending, then it
|
|
238 |
* will add <tt>OP_WRITE</tt> to the key's ready set and add the key to its
|
|
239 |
* selected-key set. </p>
|
|
240 |
*/
|
|
241 |
public static final int OP_WRITE = 1 << 2;
|
|
242 |
|
|
243 |
/**
|
|
244 |
* Operation-set bit for socket-connect operations. </p>
|
|
245 |
*
|
|
246 |
* <p> Suppose that a selection key's interest set contains
|
|
247 |
* <tt>OP_CONNECT</tt> at the start of a <a
|
|
248 |
* href="Selector.html#selop">selection operation</a>. If the selector
|
|
249 |
* detects that the corresponding socket channel is ready to complete its
|
|
250 |
* connection sequence, or has an error pending, then it will add
|
|
251 |
* <tt>OP_CONNECT</tt> to the key's ready set and add the key to its
|
|
252 |
* selected-key set. </p>
|
|
253 |
*/
|
|
254 |
public static final int OP_CONNECT = 1 << 3;
|
|
255 |
|
|
256 |
/**
|
|
257 |
* Operation-set bit for socket-accept operations. </p>
|
|
258 |
*
|
|
259 |
* <p> Suppose that a selection key's interest set contains
|
|
260 |
* <tt>OP_ACCEPT</tt> at the start of a <a
|
|
261 |
* href="Selector.html#selop">selection operation</a>. If the selector
|
|
262 |
* detects that the corresponding server-socket channel is ready to accept
|
|
263 |
* another connection, or has an error pending, then it will add
|
|
264 |
* <tt>OP_ACCEPT</tt> to the key's ready set and add the key to its
|
|
265 |
* selected-key set. </p>
|
|
266 |
*/
|
|
267 |
public static final int OP_ACCEPT = 1 << 4;
|
|
268 |
|
|
269 |
/**
|
|
270 |
* Tests whether this key's channel is ready for reading.
|
|
271 |
*
|
|
272 |
* <p> An invocation of this method of the form <tt>k.isReadable()</tt>
|
|
273 |
* behaves in exactly the same way as the expression
|
|
274 |
*
|
18156
|
275 |
* <blockquote><pre>{@code
|
|
276 |
* k.readyOps() & OP_READ != 0
|
|
277 |
* }</pre></blockquote>
|
2
|
278 |
*
|
|
279 |
* <p> If this key's channel does not support read operations then this
|
|
280 |
* method always returns <tt>false</tt>. </p>
|
|
281 |
*
|
|
282 |
* @return <tt>true</tt> if, and only if,
|
18156
|
283 |
{@code readyOps() & OP_READ} is nonzero
|
2
|
284 |
*
|
|
285 |
* @throws CancelledKeyException
|
|
286 |
* If this key has been cancelled
|
|
287 |
*/
|
|
288 |
public final boolean isReadable() {
|
|
289 |
return (readyOps() & OP_READ) != 0;
|
|
290 |
}
|
|
291 |
|
|
292 |
/**
|
|
293 |
* Tests whether this key's channel is ready for writing.
|
|
294 |
*
|
|
295 |
* <p> An invocation of this method of the form <tt>k.isWritable()</tt>
|
|
296 |
* behaves in exactly the same way as the expression
|
|
297 |
*
|
18156
|
298 |
* <blockquote><pre>{@code
|
|
299 |
* k.readyOps() & OP_WRITE != 0
|
|
300 |
* }</pre></blockquote>
|
2
|
301 |
*
|
|
302 |
* <p> If this key's channel does not support write operations then this
|
|
303 |
* method always returns <tt>false</tt>. </p>
|
|
304 |
*
|
|
305 |
* @return <tt>true</tt> if, and only if,
|
18156
|
306 |
* {@code readyOps() & OP_WRITE} is nonzero
|
2
|
307 |
*
|
|
308 |
* @throws CancelledKeyException
|
|
309 |
* If this key has been cancelled
|
|
310 |
*/
|
|
311 |
public final boolean isWritable() {
|
|
312 |
return (readyOps() & OP_WRITE) != 0;
|
|
313 |
}
|
|
314 |
|
|
315 |
/**
|
|
316 |
* Tests whether this key's channel has either finished, or failed to
|
|
317 |
* finish, its socket-connection operation.
|
|
318 |
*
|
|
319 |
* <p> An invocation of this method of the form <tt>k.isConnectable()</tt>
|
|
320 |
* behaves in exactly the same way as the expression
|
|
321 |
*
|
18156
|
322 |
* <blockqoute><pre>{@code
|
|
323 |
* k.readyOps() & OP_CONNECT != 0
|
|
324 |
* }</pre></blockquote>
|
2
|
325 |
*
|
|
326 |
* <p> If this key's channel does not support socket-connect operations
|
|
327 |
* then this method always returns <tt>false</tt>. </p>
|
|
328 |
*
|
|
329 |
* @return <tt>true</tt> if, and only if,
|
18156
|
330 |
* {@code readyOps() & OP_CONNECT} is nonzero
|
2
|
331 |
*
|
|
332 |
* @throws CancelledKeyException
|
|
333 |
* If this key has been cancelled
|
|
334 |
*/
|
|
335 |
public final boolean isConnectable() {
|
|
336 |
return (readyOps() & OP_CONNECT) != 0;
|
|
337 |
}
|
|
338 |
|
|
339 |
/**
|
|
340 |
* Tests whether this key's channel is ready to accept a new socket
|
|
341 |
* connection.
|
|
342 |
*
|
|
343 |
* <p> An invocation of this method of the form <tt>k.isAcceptable()</tt>
|
|
344 |
* behaves in exactly the same way as the expression
|
|
345 |
*
|
18156
|
346 |
* <blockquote><pre>{@code
|
|
347 |
* k.readyOps() & OP_ACCEPT != 0
|
|
348 |
* }</pre></blockquote>
|
2
|
349 |
*
|
|
350 |
* <p> If this key's channel does not support socket-accept operations then
|
|
351 |
* this method always returns <tt>false</tt>. </p>
|
|
352 |
*
|
|
353 |
* @return <tt>true</tt> if, and only if,
|
18156
|
354 |
* {@code readyOps() & OP_ACCEPT} is nonzero
|
2
|
355 |
*
|
|
356 |
* @throws CancelledKeyException
|
|
357 |
* If this key has been cancelled
|
|
358 |
*/
|
|
359 |
public final boolean isAcceptable() {
|
|
360 |
return (readyOps() & OP_ACCEPT) != 0;
|
|
361 |
}
|
|
362 |
|
|
363 |
|
|
364 |
// -- Attachments --
|
|
365 |
|
|
366 |
private volatile Object attachment = null;
|
|
367 |
|
|
368 |
private static final AtomicReferenceFieldUpdater<SelectionKey,Object>
|
|
369 |
attachmentUpdater = AtomicReferenceFieldUpdater.newUpdater(
|
|
370 |
SelectionKey.class, Object.class, "attachment"
|
|
371 |
);
|
|
372 |
|
|
373 |
/**
|
|
374 |
* Attaches the given object to this key.
|
|
375 |
*
|
|
376 |
* <p> An attached object may later be retrieved via the {@link #attachment()
|
|
377 |
* attachment} method. Only one object may be attached at a time; invoking
|
|
378 |
* this method causes any previous attachment to be discarded. The current
|
|
379 |
* attachment may be discarded by attaching <tt>null</tt>. </p>
|
|
380 |
*
|
|
381 |
* @param ob
|
|
382 |
* The object to be attached; may be <tt>null</tt>
|
|
383 |
*
|
|
384 |
* @return The previously-attached object, if any,
|
|
385 |
* otherwise <tt>null</tt>
|
|
386 |
*/
|
|
387 |
public final Object attach(Object ob) {
|
|
388 |
return attachmentUpdater.getAndSet(this, ob);
|
|
389 |
}
|
|
390 |
|
|
391 |
/**
|
|
392 |
* Retrieves the current attachment. </p>
|
|
393 |
*
|
|
394 |
* @return The object currently attached to this key,
|
|
395 |
* or <tt>null</tt> if there is no attachment
|
|
396 |
*/
|
|
397 |
public final Object attachment() {
|
|
398 |
return attachment;
|
|
399 |
}
|
|
400 |
|
|
401 |
}
|