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