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 */ SelectionKey()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 */ channel()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 */ selector()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 */ isValid()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 */ cancel()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 */ interestOps()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 */ interestOps(int ops)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 */ interestOpsOr(int ops)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 */ interestOpsAnd(int ops)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 */ readyOps()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 */ isReadable()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 */ isWritable()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 */ isConnectable()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 */ isAcceptable()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 */ attach(Object ob)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 */ attachment()462 public final Object attachment() { 463 return attachment; 464 } 465 466 } 467