java.nio.channels.SelectionKey Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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;
import java.io.IOException;
/**
* A token representing the registration of a {@link SelectableChannel} with a
* {@link Selector}.
*
* A selection key is created each time a channel is registered with a
* selector. A key remains valid until it is cancelled 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 cancelled-key set for removal during the
* next selection operation. The validity of a key may be tested by invoking
* its {@link #isValid isValid} method.
*
*
*
*
A selection key contains two operation sets represented as
* integer values. Each bit of an operation set denotes a category of
* selectable operations that are supported by the key's channel.
*
*
*
* The interest set 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.
The ready set 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.
*
* 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.
*
*
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.
*
*
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
* attachment 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.
*
*
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.
*
*
* @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.
*
* A key is valid upon creation and remains so until it is cancelled,
* its channel is closed, or its selector is closed.
*
* @return 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.
*
* If this key has already been cancelled then invoking this method has
* no effect. Once cancelled, a key remains forever invalid.
*
* 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.
*/
public abstract void cancel();
// -- Operation-set accessors --
/**
* Retrieves this key's interest set.
*
* It is guaranteed that the returned set will only contain operation
* bits that are valid for this key's channel.
*
*
This method may be invoked at any time. Whether or not it blocks,
* and for how long, is implementation-dependent.
*
* @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.
*
* This method may be invoked at any time. Whether or not it blocks,
* and for how long, is implementation-dependent.
*
* @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.
*
* It is guaranteed that the returned set will only contain operation
* bits that are valid for this key's channel.
*
* @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.
*
* Suppose that a selection key's interest set contains
* OP_READ at the start of a selection operation. 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 OP_READ to the key's
* ready-operation set and add the key to its selected-key set.
*/
public static final int OP_READ = 1 << 0;
/**
* Operation-set bit for write operations.
*
* Suppose that a selection key's interest set contains
* OP_WRITE at the start of a selection operation. 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 OP_WRITE to the key's ready set and add the key to its
* selected-key set.
*/
public static final int OP_WRITE = 1 << 2;
/**
* Operation-set bit for socket-connect operations.
*
* Suppose that a selection key's interest set contains
* OP_CONNECT at the start of a selection operation. 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
* OP_CONNECT to the key's ready set and add the key to its
* selected-key set.
*/
public static final int OP_CONNECT = 1 << 3;
/**
* Operation-set bit for socket-accept operations.
*
* Suppose that a selection key's interest set contains
* OP_ACCEPT at the start of a selection operation. 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
* OP_ACCEPT to the key's ready set and add the key to its
* selected-key set.
*/
public static final int OP_ACCEPT = 1 << 4;
/**
* Tests whether this key's channel is ready for reading.
*
* An invocation of this method of the form k.isReadable()
* behaves in exactly the same way as the expression
*
*
{@code
* k.readyOps() & OP_READ != 0
* }
*
* If this key's channel does not support read operations then this
* method always returns false.
*
* @return 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.
*
* An invocation of this method of the form k.isWritable()
* behaves in exactly the same way as the expression
*
*
{@code
* k.readyOps() & OP_WRITE != 0
* }
*
* If this key's channel does not support write operations then this
* method always returns false.
*
* @return 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.
*
* An invocation of this method of the form k.isConnectable()
* behaves in exactly the same way as the expression
*
*
{@code
* k.readyOps() & OP_CONNECT != 0
* }
*
* If this key's channel does not support socket-connect operations
* then this method always returns false.
*
* @return 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.
*
* An invocation of this method of the form k.isAcceptable()
* behaves in exactly the same way as the expression
*
*
{@code
* k.readyOps() & OP_ACCEPT != 0
* }
*
* If this key's channel does not support socket-accept operations then
* this method always returns false.
*
* @return 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 = null;
private static final AtomicReferenceFieldUpdater
attachmentUpdater = AtomicReferenceFieldUpdater.newUpdater(
SelectionKey.class, Object.class, "attachment"
);
/**
* Attaches the given object to this key.
*
* 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 null.
*
* @param ob
* The object to be attached; may be null
*
* @return The previously-attached object, if any,
* otherwise 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 null if there is no attachment
*/
public final Object attachment() {
return attachment;
}
}