2362N/A * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A token representing the registration of a {@link SelectableChannel} with a 0N/A * <p> A selection key is created each time a channel is registered with a 0N/A * selector. A key remains valid until it is <i>cancelled</i> by invoking its 0N/A * {@link #cancel cancel} method, by closing its channel, or by closing its 0N/A * selector. Cancelling a key does not immediately remove it from its 0N/A * selector; it is instead added to the selector's <a 0N/A * next selection operation. The validity of a key may be tested by invoking 0N/A * its {@link #isValid isValid} method. 0N/A * <p> A selection key contains two <i>operation sets</i> represented as 0N/A * integer values. Each bit of an operation set denotes a category of 0N/A * selectable operations that are supported by the key's channel. 0N/A * <li><p> The <i>interest set</i> determines which operation categories will 0N/A * be tested for readiness the next time one of the selector's selection 0N/A * methods is invoked. The interest set is initialized with the value given 0N/A * when the key is created; it may later be changed via the {@link 0N/A * #interestOps(int)} method. </p></li> 0N/A * <li><p> The <i>ready set</i> identifies the operation categories for which 0N/A * the key's channel has been detected to be ready by the key's selector. 0N/A * The ready set is initialized to zero when the key is created; it may later 0N/A * be updated by the selector during a selection operation, but it cannot be 0N/A * updated directly. </p></li> 0N/A * <p> That a selection key's ready set indicates that its channel is ready for 0N/A * some operation category is a hint, but not a guarantee, that an operation in 0N/A * such a category may be performed by a thread without causing the thread to 0N/A * block. A ready set is most likely to be accurate immediately after the 0N/A * completion of a selection operation. It is likely to be made inaccurate by 0N/A * external events and by I/O operations that are invoked upon the 0N/A * corresponding channel. 0N/A * <p> This class defines all known operation-set bits, but precisely which 0N/A * bits are supported by a given channel depends upon the type of the channel. 0N/A * Each subclass of {@link SelectableChannel} defines an {@link 0N/A * SelectableChannel#validOps() validOps()} method which returns a set 0N/A * identifying just those operations that are supported by the channel. An 0N/A * attempt to set or test an operation-set bit that is not supported by a key's 0N/A * channel will result in an appropriate run-time exception. 0N/A * <p> It is often necessary to associate some application-specific data with a 0N/A * selection key, for example an object that represents the state of a 0N/A * higher-level protocol and handles readiness notifications in order to 0N/A * implement that protocol. Selection keys therefore support the 0N/A * <i>attachment</i> of a single arbitrary object to a key. An object can be 0N/A * attached via the {@link #attach attach} method and then later retrieved via 0N/A * the {@link #attachment() attachment} method. 0N/A * <p> Selection keys are safe for use by multiple concurrent threads. The 0N/A * operations of reading and writing the interest set will, in general, be 0N/A * synchronized with certain operations of the selector. Exactly how this 0N/A * synchronization is performed is implementation-dependent: In a naive 0N/A * implementation, reading or writing the interest set may block indefinitely 0N/A * if a selection operation is already in progress; in a high-performance 0N/A * implementation, reading or writing the interest set may block briefly, if at 0N/A * all. In any case, a selection operation will always use the interest-set 0N/A * value that was current at the moment that the operation began. </p> 0N/A * @author Mark Reinhold 0N/A * @author JSR-51 Expert Group 0N/A * @see SelectableChannel 0N/A * Constructs an instance of this class. 0N/A // -- Channel and selector operations -- 0N/A * Returns the channel for which this key was created. This method will 0N/A * continue to return the channel even after the key is cancelled. </p> 0N/A * @return This key's channel 0N/A * Returns the selector for which this key was created. This method will 0N/A * continue to return the selector even after the key is cancelled. </p> 0N/A * @return This key's selector 0N/A * Tells whether or not this key is valid. 0N/A * <p> A key is valid upon creation and remains so until it is cancelled, 0N/A * its channel is closed, or its selector is closed. </p> 0N/A * @return <tt>true</tt> if, and only if, this key is valid 0N/A * Requests that the registration of this key's channel with its selector 0N/A * be cancelled. Upon return the key will be invalid and will have been 0N/A * added to its selector's cancelled-key set. The key will be removed from 0N/A * all of the selector's key sets during the next selection operation. 0N/A * <p> If this key has already been cancelled then invoking this method has 0N/A * no effect. Once cancelled, a key remains forever invalid. </p> 0N/A * <p> This method may be invoked at any time. It synchronizes on the 0N/A * selector's cancelled-key set, and therefore may block briefly if invoked 0N/A * concurrently with a cancellation or selection operation involving the 0N/A * same selector. </p> 0N/A // -- Operation-set accessors -- 0N/A * Retrieves this key's interest set. 0N/A * <p> It is guaranteed that the returned set will only contain operation 0N/A * bits that are valid for this key's channel. 0N/A * <p> This method may be invoked at any time. Whether or not it blocks, 0N/A * and for how long, is implementation-dependent. </p> 0N/A * @return This key's interest set 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A * Sets this key's interest set to the given value. 0N/A * <p> This method may be invoked at any time. Whether or not it blocks, 0N/A * and for how long, is implementation-dependent. </p> 0N/A * @param ops The new interest set 0N/A * @return This selection key 0N/A * @throws IllegalArgumentException 0N/A * If a bit in the set does not correspond to an operation that 0N/A * is supported by this key's channel, that is, if 414N/A * <tt>(ops & ~channel().validOps()) != 0</tt> 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A * Retrieves this key's ready-operation set. 0N/A * <p> It is guaranteed that the returned set will only contain operation 0N/A * bits that are valid for this key's channel. </p> 0N/A * @return This key's ready-operation set 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A // -- Operation bits and bit-testing convenience methods -- 0N/A * Operation-set bit for read operations. 0N/A * <p> Suppose that a selection key's interest set contains 0N/A * <tt>OP_READ</tt> at the start of a <a 0N/A * detects that the corresponding channel is ready for reading, has reached 0N/A * end-of-stream, has been remotely shut down for further reading, or has 0N/A * an error pending, then it will add <tt>OP_READ</tt> to the key's 0N/A * ready-operation set and add the key to its selected-key set. </p> 0N/A * Operation-set bit for write operations. </p> 0N/A * <p> Suppose that a selection key's interest set contains 0N/A * <tt>OP_WRITE</tt> at the start of a <a 0N/A * detects that the corresponding channel is ready for writing, has been 0N/A * remotely shut down for further writing, or has an error pending, then it 0N/A * will add <tt>OP_WRITE</tt> to the key's ready set and add the key to its 0N/A * selected-key set. </p> 0N/A * Operation-set bit for socket-connect operations. </p> 0N/A * <p> Suppose that a selection key's interest set contains 0N/A * <tt>OP_CONNECT</tt> at the start of a <a 0N/A * detects that the corresponding socket channel is ready to complete its 0N/A * connection sequence, or has an error pending, then it will add 0N/A * <tt>OP_CONNECT</tt> to the key's ready set and add the key to its 0N/A * selected-key set. </p> 0N/A * Operation-set bit for socket-accept operations. </p> 0N/A * <p> Suppose that a selection key's interest set contains 0N/A * <tt>OP_ACCEPT</tt> at the start of a <a 0N/A * detects that the corresponding server-socket channel is ready to accept 0N/A * another connection, or has an error pending, then it will add 0N/A * <tt>OP_ACCEPT</tt> to the key's ready set and add the key to its 0N/A * selected-key set. </p> 0N/A * Tests whether this key's channel is ready for reading. 0N/A * <p> An invocation of this method of the form <tt>k.isReadable()</tt> 0N/A * behaves in exactly the same way as the expression 0N/A * k.readyOps() & OP_READ != 0</pre></blockquote> 0N/A * <p> If this key's channel does not support read operations then this 0N/A * method always returns <tt>false</tt>. </p> 0N/A * @return <tt>true</tt> if, and only if, 0N/A * <tt>readyOps()</tt> <tt>&</tt> <tt>OP_READ</tt> is 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A * Tests whether this key's channel is ready for writing. 0N/A * <p> An invocation of this method of the form <tt>k.isWritable()</tt> 0N/A * behaves in exactly the same way as the expression 0N/A * k.readyOps() & OP_WRITE != 0</pre></blockquote> 0N/A * <p> If this key's channel does not support write operations then this 0N/A * method always returns <tt>false</tt>. </p> 0N/A * @return <tt>true</tt> if, and only if, 0N/A * <tt>readyOps()</tt> <tt>&</tt> <tt>OP_WRITE</tt> 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A * Tests whether this key's channel has either finished, or failed to 0N/A * finish, its socket-connection operation. 0N/A * <p> An invocation of this method of the form <tt>k.isConnectable()</tt> 0N/A * behaves in exactly the same way as the expression 0N/A * k.readyOps() & OP_CONNECT != 0</pre></blockquote> 0N/A * <p> If this key's channel does not support socket-connect operations 0N/A * then this method always returns <tt>false</tt>. </p> 0N/A * @return <tt>true</tt> if, and only if, 0N/A * <tt>readyOps()</tt> <tt>&</tt> <tt>OP_CONNECT</tt> 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A * Tests whether this key's channel is ready to accept a new socket 0N/A * <p> An invocation of this method of the form <tt>k.isAcceptable()</tt> 0N/A * behaves in exactly the same way as the expression 0N/A * k.readyOps() & OP_ACCEPT != 0</pre></blockquote> 0N/A * <p> If this key's channel does not support socket-accept operations then 0N/A * this method always returns <tt>false</tt>. </p> 0N/A * @return <tt>true</tt> if, and only if, 0N/A * <tt>readyOps()</tt> <tt>&</tt> <tt>OP_ACCEPT</tt> 0N/A * @throws CancelledKeyException 0N/A * If this key has been cancelled 0N/A // -- Attachments -- 0N/A * Attaches the given object to this key. 0N/A * <p> An attached object may later be retrieved via the {@link #attachment() 0N/A * attachment} method. Only one object may be attached at a time; invoking 0N/A * this method causes any previous attachment to be discarded. The current 0N/A * attachment may be discarded by attaching <tt>null</tt>. </p> 0N/A * The object to be attached; may be <tt>null</tt> 0N/A * @return The previously-attached object, if any, 0N/A * otherwise <tt>null</tt> 0N/A * Retrieves the current attachment. </p> 0N/A * @return The object currently attached to this key, 0N/A * or <tt>null</tt> if there is no attachment