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