Unchecked exception thrown when an attempt is made to initiate an accept
operation on a channel and a previous accept operation has not completed.

Unchecked exception thrown when an attempt is made to bind the socket a
network oriented channel that is already bound.

Unchecked exception thrown when an attempt is made to connect a SocketChannel that is already connected.

An asynchronous channel that can read and write bytes.

 Some channels may not allow more than one read or write to be outstanding
at any given time. If a thread invokes a read method before a previous read
operation has completed then a ReadPendingException will be thrown.
Similarly, if a write method is invoked before a previous write has completed
then WritePendingException is thrown. Whether or not other kinds of
I/O operations may proceed concurrently with a read operation depends upon
the type of the channel.

 Note that ByteBuffers are not safe for use by
multiple concurrent threads. When a read or write operation is initiated then
care must be taken to ensure that the buffer is not accessed until the
operation completes.

A channel that supports asynchronous I/O operations. Asynchronous I/O
 operations will usually take one of two forms:




Future<V> operation(...)


void operation(... A attachment, CompletionHandler<V,? super A> handler)


 where operation is the name of the I/O operation (read or write for
 example), V is the result type of the I/O operation, and A is
 the type of an object attached to the I/O operation to provide context when
 consuming the result. The attachment is important for cases where a
 state-less CompletionHandler is used to consume the result
 of many I/O operations.

  In the first form, the methods defined by the Future
 interface may be used to check if the operation has completed, wait for its
 completion, and to retrieve the result. In the second form, a CompletionHandler is invoked to consume the result of the I/O operation when
 it completes or fails.

  A channel that implements this interface is asynchronously
 closeable: If an I/O operation is outstanding on the channel and the
 channel's close method is invoked, then the I/O operation
 fails with the exception AsynchronousCloseException.

  Asynchronous channels are safe for use by multiple concurrent threads.
 Some channel implementations may support concurrent reading and writing, but
 may not allow more than one read and one write operation to be outstanding at
 any given time.

 Cancellation

  The Future interface defines the cancel
 method to cancel execution. This causes all threads waiting on the result of
 the I/O operation to throw CancellationException.
 Whether the underlying I/O operation can be cancelled is highly implementation
 specific and therefore not specified. Where cancellation leaves the channel,
 or the entity to which it is connected, in an inconsistent state, then the
 channel is put into an implementation specific error state that
 prevents further attempts to initiate I/O operations that are similar
 to the operation that was cancelled. For example, if a read operation is
 cancelled but the implementation cannot guarantee that bytes have not been
 read from the channel then it puts the channel into an error state; further
 attempts to initiate a read operation cause an unspecified runtime
 exception to be thrown. Similarly, if a write operation is cancelled but the
 implementation cannot guarantee that bytes have not been written to the
 channel then subsequent attempts to initiate a write will fail with
 an unspecified runtime exception.

  Where the cancel method is invoked with the mayInterruptIfRunning parameter set to true then the I/O operation
 may be interrupted by closing the channel. In that case all threads waiting
 on the result of the I/O operation throw CancellationException and
 any other I/O operations outstanding on the channel complete with the
 exception AsynchronousCloseException.

  Where the cancel method is invoked to cancel read or write
 operations then it is recommended that all buffers used in the I/O operations
 be discarded or care taken to ensure that the buffers are not accessed while
 the channel remains open.

System property
Description


 java.nio.channels.DefaultThreadPool.threadFactory
 The value of this property is taken to be the fully-qualified name
of a concrete ThreadFactory
class. The class is loaded using the system class loader and instantiated.
The factory's newThread method is invoked to create each thread for the default
group's thread pool. If the process to load and instantiate the value
of the property fails then an unspecified error is thrown during the
construction of the default group.


 java.nio.channels.DefaultThreadPool.initialSize
 The value of the initialSize parameter for the default
group (see withCachedThreadPool).
The value of the property is taken to be the String
representation of an Integer that is the initial size parameter.
If the value cannot be parsed as an Integer it causes an
unspecified error to be thrown during the construction of the default
group.

A grouping of asynchronous channels for the purpose of resource sharing.

 An asynchronous channel group encapsulates the mechanics required to
handle the completion of I/O operations initiated by asynchronous channels that are bound to the group. A group has an associated
thread pool to which tasks are submitted to handle I/O events and dispatch to
completion-handlers that consume the result of
asynchronous operations performed on channels in the group. In addition to
handling I/O events, the pooled threads may also execute other tasks required
to support the execution of asynchronous I/O operations.

 An asynchronous channel group is created by invoking the withFixedThreadPool or withCachedThreadPool methods defined here. Channels are bound to a group by
specifying the group when constructing the channel. The associated thread
pool is owned by the group; termination of the group results in the
shutdown of the associated thread pool.

 In addition to groups created explicitly, the Java virtual machine
maintains a system-wide default group that is constructed
automatically. Asynchronous channels that do not specify a group at
construction time are bound to the default group. The default group has an
associated thread pool that creates new threads as needed. The default group
may be configured by means of system properties defined in the table below.
Where the ThreadFactory for the
default group is not configured then the pooled threads of the default group
are daemon threads.



    System property
    Description


     java.nio.channels.DefaultThreadPool.threadFactory
     The value of this property is taken to be the fully-qualified name
    of a concrete ThreadFactory
    class. The class is loaded using the system class loader and instantiated.
    The factory's newThread method is invoked to create each thread for the default
    group's thread pool. If the process to load and instantiate the value
    of the property fails then an unspecified error is thrown during the
    construction of the default group.


     java.nio.channels.DefaultThreadPool.initialSize
     The value of the initialSize parameter for the default
    group (see withCachedThreadPool).
    The value of the property is taken to be the String
    representation of an Integer that is the initial size parameter.
    If the value cannot be parsed as an Integer it causes an
    unspecified error to be thrown during the construction of the default
    group.



Threading

 The completion handler for an I/O operation initiated on a channel bound
to a group is guaranteed to be invoked by one of the pooled threads in the
group. This ensures that the completion handler is run by a thread with the
expected identity.

 Where an I/O operation completes immediately, and the initiating thread
is one of the pooled threads in the group then the completion handler may
be invoked directly by the initiating thread. To avoid stack overflow, an
implementation may impose a limit as to the number of activations on the
thread stack. Some I/O operations may prohibit invoking the completion
handler directly by the initiating thread (see accept).

Shutdown and Termination

 The shutdown method is used to initiate an orderly
shutdown of a group. An orderly shutdown marks the group as shutdown;
further attempts to construct a channel that binds to the group will throw
ShutdownChannelGroupException. Whether or not a group is shutdown can
be tested using the isShutdown method. Once shutdown,
the group terminates when all asynchronous channels that are bound to
the group are closed, all actively executing completion handlers have run to
completion, and resources used by the group are released. No attempt is made
to stop or interrupt threads that are executing completion handlers. The
isTerminated method is used to test if the group has
terminated, and the awaitTermination method can be
used to block until the group has terminated.

 The shutdownNow method can be used to initiate a
forceful shutdown of the group. In addition to the actions performed
by an orderly shutdown, the shutdownNow method closes all open channels
in the group as if by invoking the close
method.

Checked exception received by a thread when another thread closes the
channel or the part of the channel upon which it is blocked in an I/O
operation.

An asynchronous channel for reading, writing, and manipulating a file.

 An asynchronous file channel is created when a file is opened by invoking
one of the open methods defined by this class. The file contains
a variable-length sequence of bytes that can be read and written and whose
current size can be queried. The size of the file increases
when bytes are written beyond its  current size; the size of the file decreases
when it is truncated.

 An asynchronous file channel does not have a current position
within the file. Instead, the file position is specified to each read and
write method that initiates asynchronous operations. A CompletionHandler
is specified as a parameter and is invoked to consume the result of the I/O
operation. This class also defines read and write methods that initiate
asynchronous operations, returning a Future to represent the pending
result of the operation. The Future may be used to check if the
operation has completed, wait for its completion, and retrieve the result.

 In addition to read and write operations, this class defines the
following operations:



   Updates made to a file may be forced
  out to the underlying storage device, ensuring that data are not
  lost in the event of a system crash.

   A region of a file may be locked against
  access by other programs.



 An AsynchronousFileChannel is associated with a thread pool to
which tasks are submitted to handle I/O events and dispatch to completion
handlers that consume the results of I/O operations on the channel. The
completion handler for an I/O operation initiated on a channel is guaranteed
to be invoked by one of the threads in the thread pool (This ensures that the
completion handler is run by a thread with the expected identity).
Where an I/O operation completes immediately, and the initiating thread is
itself a thread in the thread pool, then the completion handler may be invoked
directly by the initiating thread. When an AsynchronousFileChannel is
created without specifying a thread pool then the channel is associated with
a system-dependent default thread pool that may be shared with other
channels. The default thread pool is configured by the system properties
defined by the AsynchronousChannelGroup class.

 Channels of this type are safe for use by multiple concurrent threads. The
close method may be invoked at any time, as specified
by the Channel interface. This causes all outstanding asynchronous
operations on the channel to complete with the exception AsynchronousCloseException. Multiple read and write operations may be
outstanding at the same time. When multiple read and write operations are
outstanding then the ordering of the I/O operations, and the order that the
completion handlers are invoked, is not specified; they are not, in particular,
guaranteed to execute in the order that the operations were initiated. The
ByteBuffers used when reading or writing are not
safe for use by multiple concurrent I/O operations. Furthermore, after an I/O
operation is initiated then care should be taken to ensure that the buffer is
not accessed until after the operation has completed.

 As with FileChannel, the view of a file provided by an instance of
this class is guaranteed to be consistent with other views of the same file
provided by other instances in the same program.  The view provided by an
instance of this class may or may not, however, be consistent with the views
seen by other concurrently-running programs due to caching performed by the
underlying operating system and delays induced by network-filesystem protocols.
This is true regardless of the language in which these other programs are
written, and whether they are running on the same machine or on some other
machine.  The exact nature of any such inconsistencies are system-dependent
and are therefore unspecified.

Option Name
Description


 SO_RCVBUF
 The size of the socket receive buffer


 SO_REUSEADDR
 Re-use address

     // handle this connection
     handle(ch);
 }
 public void failed(Throwable exc, Void att) {
     ...
 }

An asynchronous channel for stream-oriented listening sockets.

 An asynchronous server-socket channel is created by invoking the
open method of this class.
A newly-created asynchronous server-socket channel is open but not yet bound.
It can be bound to a local address and configured to listen for connections
by invoking the bind method. Once bound,
the accept method
is used to initiate the accepting of connections to the channel's socket.
An attempt to invoke the accept method on an unbound channel will
cause a NotYetBoundException to be thrown.

 Channels of this type are safe for use by multiple concurrent threads
though at most one accept operation can be outstanding at any time.
If a thread initiates an accept operation before a previous accept operation
has completed then an AcceptPendingException will be thrown.

 Socket options are configured using the setOption method. Channels of this type support the following options:



    Option Name
    Description


     SO_RCVBUF
     The size of the socket receive buffer


     SO_REUSEADDR
     Re-use address



Additional (implementation specific) options may also be supported.

 Usage Example:


 final AsynchronousServerSocketChannel listener =
     AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));

 listener.accept(null, new CompletionHandler<AsynchronousSocketChannel,Void>() {
     public void completed(AsynchronousSocketChannel ch, Void att) {
         // accept the next connection
         listener.accept(null, this);

         // handle this connection
         handle(ch);
     }
     public void failed(Throwable exc, Void att) {
         ...
     }
 });

Option Name
Description


 SO_SNDBUF
 The size of the socket send buffer


 SO_RCVBUF
 The size of the socket receive buffer


 SO_KEEPALIVE
 Keep connection alive


 SO_REUSEADDR
 Re-use address


 TCP_NODELAY
 Disable the Nagle algorithm

An asynchronous channel for stream-oriented connecting sockets.

 Asynchronous socket channels are created in one of two ways. A newly-created
AsynchronousSocketChannel is created by invoking one of the open methods defined by this class. A newly-created channel is open but
not yet connected. A connected AsynchronousSocketChannel is created
when a connection is made to the socket of an AsynchronousServerSocketChannel.
It is not possible to create an asynchronous socket channel for an arbitrary,
pre-existing socket.

 A newly-created channel is connected by invoking its connect
method; once connected, a channel remains connected until it is closed.  Whether
or not a socket channel is connected may be determined by invoking its getRemoteAddress method. An attempt to invoke an I/O
operation upon an unconnected channel will cause a NotYetConnectedException
to be thrown.

 Channels of this type are safe for use by multiple concurrent threads.
They support concurrent reading and writing, though at most one read operation
and one write operation can be outstanding at any time.
If a thread initiates a read operation before a previous read operation has
completed then a ReadPendingException will be thrown. Similarly, an
attempt to initiate a write operation before a previous write has completed
will throw a WritePendingException.

 Socket options are configured using the setOption method. Asynchronous socket channels support the following options:



    Option Name
    Description


     SO_SNDBUF
     The size of the socket send buffer


     SO_RCVBUF
     The size of the socket receive buffer


     SO_KEEPALIVE
     Keep connection alive


     SO_REUSEADDR
     Re-use address


     TCP_NODELAY
     Disable the Nagle algorithm



Additional (implementation specific) options may also be supported.

Timeouts

 The read
and write
methods defined by this class allow a timeout to be specified when initiating
a read or write operation. If the timeout elapses before an operation completes
then the operation completes with the exception InterruptedByTimeoutException. A timeout may leave the channel, or the
underlying connection, in an inconsistent state. Where the implementation
cannot guarantee that bytes have not been read from the channel then it puts
the channel into an implementation specific error state. A subsequent
attempt to initiate a read operation causes an unspecified runtime
exception to be thrown. Similarly if a write operation times out and
the implementation cannot guarantee bytes have not been written to the
channel then further attempts to write to the channel cause an
unspecified runtime exception to be thrown. When a timeout elapses then the
state of the ByteBuffer, or the sequence of buffers, for the I/O
operation is not defined. Buffers should be discarded or at least care must
be taken to ensure that the buffers are not accessed while the channel remains
open. All methods that accept timeout parameters treat values less than or
equal to zero to mean that the I/O operation does not timeout.

A channel that can read and write bytes.  This interface simply unifies
ReadableByteChannel and WritableByteChannel; it does not
specify any new operations.

Unchecked exception thrown when an attempt is made to use
a selection key that is no longer valid.

A nexus for I/O operations.

 A channel represents an open connection to an entity such as a hardware
device, a file, a network socket, or a program component that is capable of
performing one or more distinct I/O operations, for example reading or
writing.

 A channel is either open or closed.  A channel is open upon creation,
and once closed it remains closed.  Once a channel is closed, any attempt to
invoke an I/O operation upon it will cause a ClosedChannelException
to be thrown.  Whether or not a channel is open may be tested by invoking
its isOpen method.

 Channels are, in general, intended to be safe for multithreaded access
as described in the specifications of the interfaces and classes that extend
and implement this interface.

Utility methods for channels and streams.

 This class defines static methods that support the interoperation of the
stream classes of the java.io package with the channel
classes of this package.

Checked exception received by a thread when another thread interrupts it
while it is blocked in an I/O operation upon a channel.  Before this
exception is thrown the channel will have been closed and the interrupt
status of the previously-blocked thread will have been set.

Checked exception thrown when an attempt is made to invoke or complete an
I/O operation upon channel that is closed, or at least closed to that
operation.  That this exception is thrown does not necessarily imply that
the channel is completely closed.  A socket channel whose write half has
been shut down, for example, may still be open for reading.

Unchecked exception thrown when an attempt is made to invoke an I/O
operation upon a closed selector.

A handler for consuming the result of an asynchronous I/O operation.

 The asynchronous channels defined in this package allow a completion
handler to be specified to consume the result of an asynchronous operation.
The completed method is invoked when the I/O operation
completes successfully. The failed method is invoked if the
I/O operations fails. The implementations of these methods should complete
in a timely manner so as to avoid keeping the invoking thread from dispatching
to other completion handlers.

Unchecked exception thrown when an attempt is made to connect a SocketChannel for which a non-blocking connection operation is already in
progress.

Option Name
Description


 SO_SNDBUF
 The size of the socket send buffer


 SO_RCVBUF
 The size of the socket receive buffer


 SO_REUSEADDR
 Re-use address


 SO_BROADCAST
 Allow transmission of broadcast datagrams


 IP_TOS
 The Type of Service (ToS) octet in the Internet Protocol (IP) header


 IP_MULTICAST_IF
 The network interface for Internet Protocol (IP) multicast datagrams


 IP_MULTICAST_TTL
 The time-to-live for Internet Protocol (IP) multicast
  datagrams


 IP_MULTICAST_LOOP
 Loopback for Internet Protocol (IP) multicast datagrams

A selectable channel for datagram-oriented sockets.

 A datagram channel is created by invoking one of the open methods
of this class. It is not possible to create a channel for an arbitrary,
pre-existing datagram socket. A newly-created datagram channel is open but not
connected. A datagram channel need not be connected in order for the send and receive methods to be used.  A datagram channel may be
connected, by invoking its connect method, in order to
avoid the overhead of the security checks are otherwise performed as part of
every send and receive operation.  A datagram channel must be connected in
order to use the read and write methods, since those methods do not
accept or return socket addresses.

 Once connected, a datagram channel remains connected until it is
disconnected or closed.  Whether or not a datagram channel is connected may
be determined by invoking its isConnected method.

 Socket options are configured using the setOption method. A datagram channel to an Internet Protocol socket supports
the following options:



    Option Name
    Description


     SO_SNDBUF
     The size of the socket send buffer


     SO_RCVBUF
     The size of the socket receive buffer


     SO_REUSEADDR
     Re-use address


     SO_BROADCAST
     Allow transmission of broadcast datagrams


     IP_TOS
     The Type of Service (ToS) octet in the Internet Protocol (IP) header


     IP_MULTICAST_IF
     The network interface for Internet Protocol (IP) multicast datagrams


     IP_MULTICAST_TTL
     The time-to-live for Internet Protocol (IP) multicast
      datagrams


     IP_MULTICAST_LOOP
     Loopback for Internet Protocol (IP) multicast datagrams



Additional (implementation specific) options may also be supported.

 Datagram channels are safe for use by multiple concurrent threads.  They
support concurrent reading and writing, though at most one thread may be
reading and at most one thread may be writing at any given time.

A channel for reading, writing, mapping, and manipulating a file.

 A file channel is a SeekableByteChannel that is connected to
a file. It has a current position within its file which can
be both queried and modified.  The file itself contains a variable-length sequence
of bytes that can be read and written and whose current size can be queried.  The size of the file increases
when bytes are written beyond its current size; the size of the file
decreases when it is truncated.  The
file may also have some associated metadata such as access
permissions, content type, and last-modification time; this class does not
define methods for metadata access.

 In addition to the familiar read, write, and close operations of byte
channels, this class defines the following file-specific operations:



   Bytes may be read or
  written at an absolute
  position in a file in a way that does not affect the channel's current
  position.

   A region of a file may be mapped
  directly into memory; for large files this is often much more efficient
  than invoking the usual read or write methods.


   Updates made to a file may be forced
  out to the underlying storage device, ensuring that data are not
  lost in the event of a system crash.

   Bytes can be transferred from a file to
  some other channel, and vice
  versa, in a way that can be optimized by many operating systems
  into a very fast transfer directly to or from the filesystem cache.


   A region of a file may be locked
  against access by other programs.



 File channels are safe for use by multiple concurrent threads.  The
close method may be invoked at any time, as specified
by the Channel interface.  Only one operation that involves the
channel's position or can change its file's size may be in progress at any
given time; attempts to initiate a second such operation while the first is
still in progress will block until the first operation completes.  Other
operations, in particular those that take an explicit position, may proceed
concurrently; whether they in fact do so is dependent upon the underlying
implementation and is therefore unspecified.

 The view of a file provided by an instance of this class is guaranteed
to be consistent with other views of the same file provided by other
instances in the same program.  The view provided by an instance of this
class may or may not, however, be consistent with the views seen by other
concurrently-running programs due to caching performed by the underlying
operating system and delays induced by network-filesystem protocols.  This
is true regardless of the language in which these other programs are
written, and whether they are running on the same machine or on some other
machine.  The exact nature of any such inconsistencies are system-dependent
and are therefore unspecified.

 A file channel is created by invoking one of the open
methods defined by this class. A file channel can also be obtained from an
existing FileInputStream, FileOutputStream, or RandomAccessFile object by invoking
that object's getChannel method, which returns a file channel that
is connected to the same underlying file. Where the file channel is obtained
from an existing stream or random access file then the state of the file
channel is intimately connected to that of the object whose getChannel
method returned the channel.  Changing the channel's position, whether
explicitly or by reading or writing bytes, will change the file position of
the originating object, and vice versa. Changing the file's length via the
file channel will change the length seen via the originating object, and vice
versa.  Changing the file's content by writing bytes will change the content
seen by the originating object, and vice versa.

  At various points this class specifies that an
instance that is "open for reading," "open for writing," or "open for
reading and writing" is required.  A channel obtained via the getChannel method of a FileInputStream instance will be open for reading.  A channel
obtained via the getChannel
method of a FileOutputStream instance will be open for
writing.  Finally, a channel obtained via the getChannel method of a RandomAccessFile instance will be open for reading if the instance
was created with mode "r" and will be open for reading and writing
if the instance was created with mode "rw".

 A file channel that is open for writing may be in
append mode, for example if it was obtained from a file-output stream
that was created by invoking the FileOutputStream(File,boolean) constructor and passing true for
the second parameter.  In this mode each invocation of a relative write
operation first advances the position to the end of the file and then writes
the requested data.  Whether the advancement of the position and the writing
of the data are done in a single atomic operation is system-dependent and
therefore unspecified.

A typesafe enumeration for file-mapping modes.

A token representing a lock on a region of a file.

 A file-lock object is created each time a lock is acquired on a file via
one of the lock or tryLock methods of the
FileChannel class, or the lock
or tryLock
methods of the AsynchronousFileChannel class.

 A file-lock object is initially valid.  It remains valid until the lock
is released by invoking the release method, by closing the
channel that was used to acquire it, or by the termination of the Java
virtual machine, whichever comes first.  The validity of a lock may be
tested by invoking its isValid method.

 A file lock is either exclusive or shared.  A shared lock
prevents other concurrently-running programs from acquiring an overlapping
exclusive lock, but does allow them to acquire overlapping shared locks.  An
exclusive lock prevents other programs from acquiring an overlapping lock of
either type.  Once it is released, a lock has no further effect on the locks
that may be acquired by other programs.

 Whether a lock is exclusive or shared may be determined by invoking its
isShared method.  Some platforms do not support shared
locks, in which case a request for a shared lock is automatically converted
into a request for an exclusive lock.

 The locks held on a particular file by a single Java virtual machine do
not overlap.  The overlaps method may be used to test
whether a candidate lock range overlaps an existing lock.

 A file-lock object records the file channel upon whose file the lock is
held, the type and validity of the lock, and the position and size of the
locked region.  Only the validity of a lock is subject to change over time;
all other aspects of a lock's state are immutable.

 File locks are held on behalf of the entire Java virtual machine.
They are not suitable for controlling access to a file by multiple
threads within the same virtual machine.

 File-lock objects are safe for use by multiple concurrent threads.


 Platform dependencies

 This file-locking API is intended to map directly to the native locking
facility of the underlying operating system.  Thus the locks held on a file
should be visible to all programs that have access to the file, regardless
of the language in which those programs are written.

 Whether or not a lock actually prevents another program from accessing
the content of the locked region is system-dependent and therefore
unspecified.  The native file-locking facilities of some systems are merely
advisory, meaning that programs must cooperatively observe a known
locking protocol in order to guarantee data integrity.  On other systems
native file locks are mandatory, meaning that if one program locks a
region of a file then other programs are actually prevented from accessing
that region in a way that would violate the lock.  On yet other systems,
whether native file locks are advisory or mandatory is configurable on a
per-file basis.  To ensure consistent and correct behavior across platforms,
it is strongly recommended that the locks provided by this API be used as if
they were advisory locks.

 On some systems, acquiring a mandatory lock on a region of a file
prevents that region from being mapped into memory, and vice versa.  Programs that combine
locking and mapping should be prepared for this combination to fail.

 On some systems, closing a channel releases all locks held by the Java
virtual machine on the underlying file regardless of whether the locks were
acquired via that channel or via another channel open on the same file.  It
is strongly recommended that, within a program, a unique channel be used to
acquire all locks on any given file.

 Some network filesystems permit file locking to be used with
memory-mapped files only when the locked regions are page-aligned and a
whole multiple of the underlying hardware's page size.  Some network
filesystems do not implement file locks on regions that extend past a
certain position, often 230 or 231.  In general, great
care should be taken when locking files that reside on network filesystems.

Checked exception received by a thread when another thread interrupts it
while it is waiting to acquire a file lock.  Before this exception is thrown
the interrupt status of the previously-blocked thread will have been set.

A channel that can write bytes from a sequence of buffers.

 A gathering write operation writes, in a single invocation, a
sequence of bytes from one or more of a given sequence of buffers.
Gathering writes are often useful when implementing network protocols or
file formats that, for example, group data into segments consisting of one
or more fixed-length headers followed by a variable-length body.  Similar
scattering read operations are defined in the ScatteringByteChannel interface.

Unchecked exception thrown when a blocking-mode-specific operation
is invoked upon a channel in the incorrect blocking mode.

Unchecked exception thrown when an attempt is made to open a channel
in a group that was not created by the same provider.

Unchecked exception thrown when an attempt is made to register a channel
with a selector that was not created by the provider that created the
channel.

Checked exception received by a thread when a timeout elapses before an
asynchronous operation completes.

A channel that can be asynchronously closed and interrupted.

 A channel that implements this interface is asynchronously
closeable: If a thread is blocked in an I/O operation on an
interruptible channel then another thread may invoke the channel's close method.  This will cause the blocked thread to receive an
AsynchronousCloseException.

 A channel that implements this interface is also interruptible:
If a thread is blocked in an I/O operation on an interruptible channel then
another thread may invoke the blocked thread's interrupt method.  This will cause the channel to be closed, the blocked
thread to receive a ClosedByInterruptException, and the blocked
thread's interrupt status to be set.

 If a thread's interrupt status is already set and it invokes a blocking
I/O operation upon a channel then the channel will be closed and the thread
will immediately receive a ClosedByInterruptException; its interrupt
status will remain set.

 A channel supports asynchronous closing and interruption if, and only
if, it implements this interface.  This can be tested at runtime, if
necessary, via the instanceof operator.

A token representing the membership of an Internet Protocol (IP) multicast
group.

 A membership key may represent a membership to receive all datagrams sent
to the group, or it may be source-specific, meaning that it
represents a membership that receives only datagrams from a specific source
address. Whether or not a membership key is source-specific may be determined
by invoking its sourceAddress method.

 A membership key is valid upon creation and remains valid until the
membership is dropped by invoking the drop method, or
the channel is closed. The validity of the membership key may be tested
by invoking its isValid method.

 Where a membership key is not source-specific and the underlying operation
system supports source filtering, then the block and unblock methods can be used to block or unblock multicast datagrams
from particular source addresses.

// join multicast group on this interface, and also use this
// interface for outgoing multicast datagrams
NetworkInterface ni = NetworkInterface.getByName("hme0");

DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
    .setOption(StandardSocketOptions.SO_REUSEADDR, true)
    .bind(new InetSocketAddress(5000))
    .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);

InetAddress group = InetAddress.getByName("225.4.5.6");

MembershipKey key = dc.join(group, ni);

A network channel that supports Internet Protocol (IP) multicasting.

 IP multicasting is the transmission of IP datagrams to members of
a group that is zero or more hosts identified by a single destination
address.

 In the case of a channel to an IPv4 socket,
the underlying operating system supports
RFC 2236: Internet Group Management Protocol, Version 2 (IGMPv2).
It may optionally support source filtering as specified by  RFC 3376: Internet Group
Management Protocol, Version 3 (IGMPv3).
For channels to an IPv6 socket, the equivalent
standards are  RFC 2710:
Multicast Listener Discovery (MLD) for IPv6 and  RFC 3810: Multicast Listener
Discovery Version 2 (MLDv2) for IPv6.

 The join(InetAddress,NetworkInterface) method is used to
join a group and receive all multicast datagrams sent to the group. A channel
may join several multicast groups and may join the same group on several
interfaces. Membership is dropped by invoking the drop method on the returned MembershipKey. If the
underlying platform supports source filtering then the block and unblock methods can be used to block or
unblock multicast datagrams from particular source addresses.

 The join(InetAddress,NetworkInterface,InetAddress) method
is used to begin receiving datagrams sent to a group whose source address matches
a given source address. This method throws UnsupportedOperationException
if the underlying platform does not support source filtering.  Membership is
cumulative and this method may be invoked again with the same group
and interface to allow receiving datagrams from other source addresses. The
method returns a MembershipKey that represents membership to receive
datagrams from the given source address. Invoking the key's drop method drops membership so that datagrams from the
source address can no longer be received.

Platform dependencies

The multicast implementation is intended to map directly to the native
multicasting facility. Consequently, the following items should be considered
when developing an application that receives IP multicast datagrams:



 The creation of the channel should specify the ProtocolFamily
that corresponds to the address type of the multicast groups that the channel
will join. There is no guarantee that a channel to a socket in one protocol
family can join and receive multicast datagrams when the address of the
multicast group corresponds to another protocol family. For example, it is
implementation specific if a channel to an IPv6
socket can join an IPv4 multicast group and receive
multicast datagrams sent to the group.

 The channel's socket should be bound to the wildcard address. If the socket is bound to
a specific address, rather than the wildcard address then it is implementation
specific if multicast datagrams are received by the socket.

 The SO_REUSEADDR option should be
enabled prior to binding the socket. This is
required to allow multiple members of the group to bind to the same
address.



 Usage Example:


    // join multicast group on this interface, and also use this
    // interface for outgoing multicast datagrams
    NetworkInterface ni = NetworkInterface.getByName("hme0");

    DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
        .setOption(StandardSocketOptions.SO_REUSEADDR, true)
        .bind(new InetSocketAddress(5000))
        .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);

    InetAddress group = InetAddress.getByName("225.4.5.6");

    MembershipKey key = dc.join(group, ni);

A channel to a network socket.

 A channel that implements this interface is a channel to a network
socket. The bind method is used to bind the
socket to a local address, the getLocalAddress method returns the address that the socket is bound to, and
the setOption and getOption methods are used to set and query socket
options.  An implementation of this interface should specify the socket options
that it supports.

 The bind and setOption methods that do
not otherwise have a value to return are specified to return the network
channel upon which they are invoked. This allows method invocations to be
chained. Implementations of this interface should specialize the return type
so that method invocations on the implementation class can be chained.

Unchecked exception thrown when the finishConnect method of a SocketChannel is invoked without first
successfully invoking its connect method.

Unchecked exception thrown when an attempt is made to read
from a channel that was not originally opened for reading.

Unchecked exception thrown when an attempt is made to write
to a channel that was not originally opened for writing.

Unchecked exception thrown when an attempt is made to invoke an I/O
operation upon a server socket channel that is not yet bound.

Unchecked exception thrown when an attempt is made to invoke an I/O
operation upon a socket channel that is not yet connected.

Unchecked exception thrown when an attempt is made to acquire a lock on a
region of a file that overlaps a region already locked by the same Java
virtual machine, or when another thread is already waiting to lock an
overlapping region of the same file.

A pair of channels that implements a unidirectional pipe.

 A pipe consists of a pair of channels: A writable sink channel and a readable source
channel.  Once some bytes are written to the sink channel they can be read
from source channel in exactlyAthe order in which they were written.

 Whether or not a thread writing bytes to a pipe will block until another
thread reads those bytes, or some previously-written bytes, from the pipe is
system-dependent and therefore unspecified.  Many pipe implementations will
buffer up to a certain number of bytes between the sink and source channels,
but such buffering should not be assumed.

A channel representing the writable end of a Pipe.

A channel representing the readable end of a Pipe.

A channel that can read bytes.

 Only one read operation upon a readable channel may be in progress at
any given time.  If one thread initiates a read operation upon a channel
then any other thread that attempts to initiate another read operation will
block until the first operation is complete.  Whether or not other kinds of
I/O operations may proceed concurrently with a read operation depends upon
the type of the channel.

Unchecked exception thrown when an attempt is made to read from an
asynchronous socket channel and a previous read has not completed.

A channel that can read bytes into a sequence of buffers.

 A scattering read operation reads, in a single invocation, a
sequence of bytes into one or more of a given sequence of buffers.
Scattering reads are often useful when implementing network protocols or
file formats that, for example, group data into segments consisting of one
or more fixed-length headers followed by a variable-length body.  Similar
gathering write operations are defined in the GatheringByteChannel interface.

A byte channel that maintains a current position and allows the
position to be changed.

 A seekable byte channel is connected to an entity, typically a file,
that contains a variable-length sequence of bytes that can be read and
written. The current position can be queried and
modified. The channel also provides access to
the current size of the entity to which the channel is connected. The
size increases when bytes are written beyond its current size; the size
decreases when it is truncated.

 The position and truncate methods
which do not otherwise have a value to return are specified to return the
channel upon which they are invoked. This allows method invocations to be
chained. Implementations of this interface should specialize the return type
so that method invocations on the implementation class can be chained.

A channel that can be multiplexed via a Selector.

 In order to be used with a selector, an instance of this class must
first be registered via the register method.  This method returns a new SelectionKey object
that represents the channel's registration with the selector.

 Once registered with a selector, a channel remains registered until it
is deregistered.  This involves deallocating whatever resources were
allocated to the channel by the selector.

 A channel cannot be deregistered directly; instead, the key representing
its registration must be cancelled.  Cancelling a key requests that
the channel be deregistered during the selector's next selection operation.
A key may be cancelled explicitly by invoking its cancel method.  All of a channel's keys are cancelled
implicitly when the channel is closed, whether by invoking its close method or by interrupting a thread blocked in an I/O
operation upon the channel.

 If the selector itself is closed then the channel will be deregistered,
and the key representing its registration will be invalidated, without
further delay.

 A channel may be registered at most once with any particular selector.

 Whether or not a channel is registered with one or more selectors may be
determined by invoking the isRegistered method.

 Selectable channels are safe for use by multiple concurrent
threads.



Blocking mode

A selectable channel is either in blocking mode or in
non-blocking mode.  In blocking mode, every I/O operation invoked
upon the channel will block until it completes.  In non-blocking mode an I/O
operation will never block and may transfer fewer bytes than were requested
or possibly no bytes at all.  The blocking mode of a selectable channel may
be determined by invoking its isBlocking method.

 Newly-created selectable channels are always in blocking mode.
Non-blocking mode is most useful in conjunction with selector-based
multiplexing.  A channel must be placed into non-blocking mode before being
registered with a selector, and may not be returned to blocking mode until
it has been deregistered.

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.



   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 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 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.

 If the channel's key is not already in the selected-key set then
it is added to that set and its ready-operation set is modified to
identify exactly those operations for which the channel is now reported
to be ready.  Any readiness information previously recorded in the ready
set is discarded.

 Otherwise the channel's key is already in the selected-key set,
so its ready-operation set is modified to identify any new operations
for which the channel is reported to be ready.  Any readiness
information previously recorded in the ready set is preserved; in other
words, the ready set returned by the underlying system is
bitwise-disjoined into the key's current ready set.

A multiplexor of SelectableChannel objects.

 A selector may be created by invoking the open method of
this class, which will use the system's default selector provider to
create a new selector.  A selector may also be created by invoking the
openSelector
method of a custom selector provider.  A selector remains open until it is
closed via its close method.



 A selectable channel's registration with a selector is represented by a
SelectionKey object.  A selector maintains three sets of selection
keys:



   The key set contains the keys representing the current
  channel registrations of this selector.  This set is returned by the
  keys method.

   The selected-key set is the set of keys such that each
  key's channel was detected to be ready for at least one of the operations
  identified in the key's interest set during a prior selection operation.
  This set is returned by the selectedKeys method.
  The selected-key set is always a subset of the key set.

   The cancelled-key set is the set of keys that have been
  cancelled but whose channels have not yet been deregistered.  This set is
  not directly accessible.  The cancelled-key set is always a subset of the
  key set.



 All three sets are empty in a newly-created selector.

 A key is added to a selector's key set as a side effect of registering a
channel via the channel's register method.  Cancelled keys are removed from the key set during
selection operations.  The key set itself is not directly modifiable.

 A key is added to its selector's cancelled-key set when it is cancelled,
whether by closing its channel or by invoking its cancel method.  Cancelling a key will cause its channel to be deregistered
during the next selection operation, at which time the key will removed from
all of the selector's key sets.

 Keys are added to the selected-key set by selection
operations.  A key may be removed directly from the selected-key set by
invoking the set's remove
method or by invoking the remove method
of an iterator obtained from the
set.  Keys are never removed from the selected-key set in any other way;
they are not, in particular, removed as a side effect of selection
operations.  Keys may not be added directly to the selected-key set.



Selection

 During each selection operation, keys may be added to and removed from a
selector's selected-key set and may be removed from its key and
cancelled-key sets.  Selection is performed by the select(), select(long), and selectNow() methods, and involves three steps:




   Each key in the cancelled-key set is removed from each key set of
  which it is a member, and its channel is deregistered.  This step leaves
  the cancelled-key set empty.

   The underlying operating system is queried for an update as to the
  readiness of each remaining channel to perform any of the operations
  identified by its key's interest set as of the moment that the selection
  operation began.  For a channel that is ready for at least one such
  operation, one of the following two actions is performed:



     If the channel's key is not already in the selected-key set then
    it is added to that set and its ready-operation set is modified to
    identify exactly those operations for which the channel is now reported
    to be ready.  Any readiness information previously recorded in the ready
    set is discarded.

     Otherwise the channel's key is already in the selected-key set,
    so its ready-operation set is modified to identify any new operations
    for which the channel is reported to be ready.  Any readiness
    information previously recorded in the ready set is preserved; in other
    words, the ready set returned by the underlying system is
    bitwise-disjoined into the key's current ready set.



  If all of the keys in the key set at the start of this step have empty
  interest sets then neither the selected-key set nor any of the keys'
  ready-operation sets will be updated.

   If any keys were added to the cancelled-key set while step (2) was
  in progress then they are processed as in step (1).



 Whether or not a selection operation blocks to wait for one or more
channels to become ready, and if so for how long, is the only essential
difference between the three selection methods.


Concurrency

 Selectors are themselves safe for use by multiple concurrent threads;
their key sets, however, are not.

 The selection operations synchronize on the selector itself, on the key
set, and on the selected-key set, in that order.  They also synchronize on
the cancelled-key set during steps (1) and (3) above.

 Changes made to the interest sets of a selector's keys while a
selection operation is in progress have no effect upon that operation; they
will be seen by the next selection operation.

 Keys may be cancelled and channels may be closed at any time.  Hence the
presence of a key in one or more of a selector's key sets does not imply
that the key is valid or that its channel is open.  Application code should
be careful to synchronize and check these conditions as necessary if there
is any possibility that another thread will cancel a key or close a channel.

 A thread blocked in one of the select() or select(long) methods may be interrupted by some other thread in one of
three ways:



   By invoking the selector's wakeup method,


   By invoking the selector's close method, or


   By invoking the blocked thread's interrupt method, in which case its
  interrupt status will be set and the selector's wakeup
  method will be invoked.



 The close method synchronizes on the selector and all
three key sets in the same order as in a selection operation.



 A selector's key and selected-key sets are not, in general, safe for use
by multiple concurrent threads.  If such a thread might modify one of these
sets directly then access should be controlled by synchronizing on the set
itself.  The iterators returned by these sets' iterator methods are fail-fast: If the set
is modified after the iterator is created, in any way except by invoking the
iterator's own remove method, then a
ConcurrentModificationException will be thrown.

Option Name
Description


 SO_RCVBUF
 The size of the socket receive buffer


 SO_REUSEADDR
 Re-use address

A selectable channel for stream-oriented listening sockets.

 A server-socket channel is created by invoking the open
method of this class.  It is not possible to create a channel for an arbitrary,
pre-existing ServerSocket. A newly-created server-socket channel is
open but not yet bound.  An attempt to invoke the accept
method of an unbound server-socket channel will cause a NotYetBoundException
to be thrown. A server-socket channel can be bound by invoking one of the
bind methods defined by this class.

 Socket options are configured using the setOption method. Server-socket channels support the following options:



    Option Name
    Description


     SO_RCVBUF
     The size of the socket receive buffer


     SO_REUSEADDR
     Re-use address



Additional (implementation specific) options may also be supported.

 Server-socket channels are safe for use by multiple concurrent threads.

Unchecked exception thrown when an attempt is made to construct a channel in
a group that is shutdown or the completion handler for an I/O operation
cannot be invoked because the channel group has terminated.

Option Name
Description


 SO_SNDBUF
 The size of the socket send buffer


 SO_RCVBUF
 The size of the socket receive buffer


 SO_KEEPALIVE
 Keep connection alive


 SO_REUSEADDR
 Re-use address


 SO_LINGER
 Linger on close if data is present (when configured in blocking mode
     only)


 TCP_NODELAY
 Disable the Nagle algorithm

A selectable channel for stream-oriented connecting sockets.

 A socket channel is created by invoking one of the open
methods of this class.  It is not possible to create a channel for an arbitrary,
pre-existing socket. A newly-created socket channel is open but not yet
connected.  An attempt to invoke an I/O operation upon an unconnected
channel will cause a NotYetConnectedException to be thrown.  A
socket channel can be connected by invoking its connect
method; once connected, a socket channel remains connected until it is
closed.  Whether or not a socket channel is connected may be determined by
invoking its isConnected method.

 Socket channels support non-blocking connection: A socket
channel may be created and the process of establishing the link to the
remote socket may be initiated via the connect method for
later completion by the finishConnect method.
Whether or not a connection operation is in progress may be determined by
invoking the isConnectionPending method.

 Socket channels support asynchronous shutdown, which is similar
to the asynchronous close operation specified in the Channel class.
If the input side of a socket is shut down by one thread while another
thread is blocked in a read operation on the socket's channel, then the read
operation in the blocked thread will complete without reading any bytes and
will return -1.  If the output side of a socket is shut down by one
thread while another thread is blocked in a write operation on the socket's
channel, then the blocked thread will receive an AsynchronousCloseException.

 Socket options are configured using the setOption method. Socket channels support the following options:



    Option Name
    Description


     SO_SNDBUF
     The size of the socket send buffer


     SO_RCVBUF
     The size of the socket receive buffer


     SO_KEEPALIVE
     Keep connection alive


     SO_REUSEADDR
     Re-use address


     SO_LINGER
     Linger on close if data is present (when configured in blocking mode
         only)


     TCP_NODELAY
     Disable the Nagle algorithm



Additional (implementation specific) options may also be supported.

 Socket channels are safe for use by multiple concurrent threads.  They
support concurrent reading and writing, though at most one thread may be
reading and at most one thread may be writing at any given time.  The connect and finishConnect methods are
mutually synchronized against each other, and an attempt to initiate a read
or write operation while an invocation of one of these methods is in
progress will block until that invocation is complete.

Base implementation class for interruptible channels.

 This class encapsulates the low-level machinery required to implement
the asynchronous closing and interruption of channels.  A concrete channel
class must invoke the begin and end methods
before and after, respectively, invoking an I/O operation that might block
indefinitely.  In order to ensure that the end method is always
invoked, these methods should be used within a
try ... finally block:



boolean completed = false;
try {
    begin();
    completed = ...;    // Perform blocking I/O operation
    return ...;         // Return result
} finally {
    end(completed);
}

 The completed argument to the end method tells
whether or not the I/O operation actually completed, that is, whether it had
any effect that would be visible to the invoker.  In the case of an
operation that reads bytes, for example, this argument should be
true if, and only if, some bytes were actually transferred into the
invoker's target buffer.

 A concrete channel class must also implement the implCloseChannel method in such a way that if it is
invoked while another thread is blocked in a native I/O operation upon the
channel then that operation will immediately return, either by throwing an
exception or by returning normally.  If a thread is interrupted or the
channel upon which it is blocked is asynchronously closed then the channel's
end method will throw the appropriate exception.

 This class performs the synchronization required to implement the Channel specification.  Implementations of the implCloseChannel method need not synchronize against
other threads that might be attempting to close the channel.

Base implementation class for selectable channels.

 This class defines methods that handle the mechanics of channel
registration, deregistration, and closing.  It maintains the current
blocking mode of this channel as well as its current set of selection keys.
It performs all of the synchronization required to implement the SelectableChannel specification.  Implementations of the
abstract protected methods defined in this class need not synchronize
against other threads that might be engaged in the same operations.

Base implementation class for selection keys.

This class tracks the validity of the key and implements cancellation.

Base implementation class for selectors.

 This class encapsulates the low-level machinery required to implement
the interruption of selection operations.  A concrete selector class must
invoke the begin and end methods before and
after, respectively, invoking an I/O operation that might block
indefinitely.  In order to ensure that the end method is always
invoked, these methods should be used within a
try ... finally block:



try {
    begin();
    // Perform blocking I/O operation here
    ...
} finally {
    end();
}

 This class also defines methods for maintaining a selector's
cancelled-key set and for removing a key from its channel's key set, and
declares the abstract register method that is invoked by a
selectable channel's register
method in order to perform the actual work of registering a channel.

Service-provider class for asynchronous channels.

 An asynchronous channel provider is a concrete subclass of this class that
has a zero-argument constructor and implements the abstract methods specified
below.  A given invocation of the Java virtual machine maintains a single
system-wide default provider instance, which is returned by the provider method.  The first invocation of that method will locate
the default provider as specified below.

 All of the methods in this class are safe for use by multiple concurrent
threads.

Service-provider class for selectors and selectable channels.

 A selector provider is a concrete subclass of this class that has a
zero-argument constructor and implements the abstract methods specified
below.  A given invocation of the Java virtual machine maintains a single
system-wide default provider instance, which is returned by the provider method.  The first invocation of that method will locate
the default provider as specified below.

 The system-wide default provider is used by the static open
methods of the DatagramChannel, Pipe, Selector, ServerSocketChannel, and SocketChannel classes.  It is also
used by the System.inheritedChannel()
method. A program may make use of a provider other than the default provider
by instantiating that provider and then directly invoking the open
methods defined in this class.

 All of the methods in this class are safe for use by multiple concurrent
threads.

Unchecked exception thrown when an attempt is made to invoke a network
operation upon an unresolved socket address.

Unchecked exception thrown when an attempt is made to bind or connect
to a socket address of a type that is not supported.

A channel that can write bytes.

 Only one write operation upon a writable channel may be in progress at
any given time.  If one thread initiates a write operation upon a channel
then any other thread that attempts to initiate another write operation will
block until the first operation is complete.  Whether or not other kinds of
I/O operations may proceed concurrently with a write operation depends upon
the type of the channel.

Unchecked exception thrown when an attempt is made to write to an
asynchronous socket channel and a previous write has not completed.