SelectionKey

public abstract class SelectionKey extends Object
Known Direct Subclasses

A token representing the registration of a SelectableChannel with a 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 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 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.

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 SelectableChannel defines an 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 attach method and then later retrieved via the 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.

Constant Summary

int OP_ACCEPT Operation-set bit for socket-accept operations.
int OP_CONNECT Operation-set bit for socket-connect operations.
int OP_READ Operation-set bit for read operations.
int OP_WRITE Operation-set bit for write operations.

Protected Constructor Summary

SelectionKey()
Constructs an instance of this class.

Public Method Summary

final Object
attach(Object ob)
Attaches the given object to this key.
final Object
attachment()
Retrieves the current attachment.
abstract void
cancel()
Requests that the registration of this key's channel with its selector be cancelled.
abstract SelectableChannel
channel()
Returns the channel for which this key was created.
abstract int
interestOps()
Retrieves this key's interest set.
abstract SelectionKey
interestOps(int ops)
Sets this key's interest set to the given value.
final boolean
isAcceptable()
Tests whether this key's channel is ready to accept a new socket connection.
final boolean
isConnectable()
Tests whether this key's channel has either finished, or failed to finish, its socket-connection operation.
final boolean
isReadable()
Tests whether this key's channel is ready for reading.
abstract boolean
isValid()
Tells whether or not this key is valid.
final boolean
isWritable()
Tests whether this key's channel is ready for writing.
abstract int
readyOps()
Retrieves this key's ready-operation set.
abstract Selector
selector()
Returns the selector for which this key was created.

Inherited Method Summary

Constants

public static final int OP_ACCEPT

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.

Constant Value: 16

public static final int OP_CONNECT

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.

Constant Value: 8

public static final int OP_READ

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.

Constant Value: