A Selector is an object that monitors multiple
nonblocking SelectableChannel objects and (after
blocking if necessary) "selects"
the channel that is (or the channels that are) ready for I/O. Create
a new Selector with the static open(
) method. Next register the channels that it is to monitor:
a channel is registered by passing the Selector to
the register( ) method of the channel
(register( ) is defined by the abstract
SelectableChannel class). In addition to the
Selector you must also pass a bitmask that
specifies which I/O operations (reading, writing, connecting, and
accepting) that the Selector is to monitor for
that channel. Each call to this register( ) method
returns a SelectionKey object. (The
SelectionKey class also defines the constants that
are used to form the bitmask of I/O operations.) Note that before a
SelectableChannel can be registered, it must be in
nonblocking mode, which can be accomplished with the
configureBlocking( ) method of
SelectableChannel.
Once the channels are registered with the
Selector, call select(
) to block until one or more of the
channels is ready for I/O. One version of select(
) takes a timeout value and returns if the specified number
of milliseconds elapses without any channels becoming ready for I/O.
These methods also return if any of the channels is closed, if an
error occurs on any channel, if the wakeup( )
method of the Selector is called, or if the
interrupt( ) method of the blocked thread is
called. There is also a selectNow( ) method which
is like select( ) except that it does not block:
it simply polls each of the channels and determines which have become
ready for I/O. The return value of selectNow( )
and of both select( ) methods is the number of
channels ready for I/O. It is possible for this return value to be
zero.
The select( ) and selectNow( )
methods returns the number of channels that are ready for I/O; they
do not return the channels themselves. To obtain this information,
you must call the selectedKeys( ) method, which
returns a java.util.Set containing
SelectionKey objects. After calling
select( ) and selectedKeys( ),
applications typically obtain a java.util.Iterator
for the Set and use it to loop through the
SelectionKey objects that represent the channels
that are ready for I/O. Use the channel( ) method
of the SelectionKey to determine which channel is
ready, and call readyOps( ), isReadable(
), isWritable( ) or related methods of
the SelectionKey to determine what kind of I/O
operation is ready on the channel. SelectionKey
objects remain in the selectedKeys( ) set until
explicitly removed, so after performing the I/O operation for a given
SelectionKey, you should remove that key from the
Set returned by selectedKeys( )
(use the remove( ) method of the
Set of its Iterator).
In addition to the selectedKeys( ) method,
Selector also defines a keys(
) method, which also returns a
Set of SelectionKey objects.
This set represents the complete set of channels that are being
monitored by the Selector and may not be modified,
except by closing the channel or deregistring the channel by calling
the cancel( ) method of the associated
SelectionKey. Cancelled keys are removed from the
keys( ) set on the next call to select(
) or selectNow( ).
Call wakeup( ) to cause another thread blocked in a
call to select( ) to wake up and return
immediately. If wakeup( ) is called but no thread
is currently blocked in a select( ) call, then the
next call to select( ) or selectNow(
) will return immediately.
When a Selector object is no longer needed, close
it by calling close( ). If any thread is blocked
in a select( ) call, it will return immediately as
if wakeup( ) had been called. After calling
close( ), you should not call any other methods of
a Selector. isOpen( ) returns
true if a Selector is still
open, and returns false if it has been closed.
The Selector class is thread-safe. Note, however,
that the Set object returnd by
selectedKeys( ) is not: it should be used by only
one thread at a time.
public abstract class Selector {
// Protected Constructors
protected Selector( );
// Public Class Methods
public static Selector open( ) throws java.io.IOException;
// Public Instance Methods
public abstract void close( ) throws java.io.IOException;
public abstract boolean isOpen( );
public abstract java.util.Set<SelectionKey> keys( );
public abstract java.nio.channels.spi.SelectorProvider provider( );
public abstract int select( ) throws java.io.IOException;
public abstract int select(long timeout) throws java.io.IOException;
public abstract java.util.Set<SelectionKey> selectedKeys( );
public abstract int selectNow( ) throws java.io.IOException;
public abstract Selector wakeup( );
}
