| /* |
| * Copyright (c) 2000, 2013, 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. The |
| * operations of reading and writing the interest set will, in general, be |
| * synchronized with certain operations of the selector. Exactly how this |
| * synchronization is performed is implementation-dependent: In a naive |
| * implementation, reading or writing the interest set may block indefinitely |
| * if a selection operation is already in progress; in a high-performance |
| * implementation, reading or writing the interest set may block briefly, if at |
| * all. In any case, 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> This method may be invoked at any time. Whether or not it blocks, |
| * and for how long, is implementation-dependent. </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. Whether or not it blocks, |
| * and for how long, is implementation-dependent. </p> |
| * |
| * @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); |
| |
| /** |
| * 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 and add the key to its selected-key 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 and add the key to its |
| * selected-key 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 and add the key to its |
| * selected-key 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 and add the key to its |
| * selected-key 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; |
| } |
| |
| } |