A nexus for I/O operations
Can read into a buffer
Can read into a sequence of buffers
Can write from a buffer
Can write from a sequence of buffers
Can read/write to/from a buffer
ByteChannelconnected to an entity that contains a variable-length sequence of bytes
Supports asynchronous I/O operations.
Can read and write bytes asynchronously
A channel to a network socket
Can join Internet Protocol (IP) multicast groups
Utility methods for channel/stream interoperation
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. As specified in the
channels are either open or closed, and they are both asynchronously
closeable and interruptible.
Channel interface is extended by several
ReadableByteChannel interface specifies a
read method that reads bytes
from the channel into a buffer; similarly, the
WritableByteChannel interface specifies a
write method that writes bytes
from a buffer to the channel. The
interface unifies these two interfaces for the common case of channels that can
both read and write bytes. The
interface extends the
ByteChannel interface with methods to
modify the channel's
current position, and its
GatheringByteChannel interfaces extend the
WritableByteChannel interfaces, respectively, adding
write methods that take a
sequence of buffers rather than a single buffer.
NetworkChannel interface specifies methods
bind the channel's socket,
obtain the address to which the socket is bound, and methods to
set socket options. The
MulticastChannel interface specifies methods to join
Internet Protocol (IP) multicast groups.
Channels utility class defines static methods
that support the interoperation of the stream classes of the
java.io package with the channel classes of this package. An appropriate
channel can be constructed from an
InputStream or an
OutputStream, and conversely an
InputStream or an
OutputStream can be constructed from a channel. A
Reader can be constructed that uses a given charset to decode bytes
from a given readable byte channel, and conversely a
be constructed that uses a given charset to encode characters into bytes and
write them to a given writable byte channel.
File channels Description
Reads, writes, maps, and manipulates files
A lock on a (region of a) file
A direct byte buffer mapped to a region of a file
FileChannel class supports the usual
operations of reading bytes from, and writing bytes to, a channel connected to
a file, as well as those of querying and modifying the current file position
and truncating the file to a specific size. It defines methods for acquiring
locks on the whole file or on a specific region of a file; these methods return
instances of the
FileLock class. Finally, it defines
methods for forcing updates to the file to be written to the storage device that
contains it, for efficiently transferring bytes between the file and other
channels, and for mapping a region of the file directly into memory.
FileChannel is created by invoking one of its static
open methods, or by invoking the
getChannel method of a
RandomAccessFile to return a
file channel connected to the same underlying file as the
Multiplexed, non-blocking I/O Description
A channel that can be multiplexed
A channel to a datagram-oriented socket
The write end of a pipe
The read end of a pipe
A channel to a stream-oriented listening socket
A channel for a stream-oriented connecting socket
A multiplexor of selectable channels
A token representing the registration
of a channel with a selector
Two channels that form a unidirectional pipe
Multiplexed, non-blocking I/O, which is much more scalable than thread-oriented, blocking I/O, is provided by selectors, selectable channels, and selection keys.
A selector is a multiplexor of selectable channels, which in turn are
a special type of channel that can be put into non-blocking mode. To perform
multiplexed I/O operations, one or more selectable channels are first created,
put into non-blocking mode, and
with a selector. Registering a channel specifies the set of I/O operations
that will be tested for readiness by the selector, and returns a selection key that represents the
Once some channels have been registered with a selector, a selection operation can be performed in order to discover which channels, if any, have become ready to perform one or more of the operations in which interest was previously declared. If a channel is ready then the key returned when it was registered will be added to the selector's selected-key set. The key set, and the keys within it, can be examined in order to determine the operations for which each channel is ready. From each key one can retrieve the corresponding channel in order to perform whatever I/O operations are required.
That a selection key indicates that its channel is ready for some operation is a hint, but not a guarantee, that such an operation can be performed by a thread without causing the thread to block. It is imperative that code that performs multiplexed I/O be written so as to ignore these hints when they prove to be incorrect.
This package defines selectable-channel classes corresponding to the
Socket classes defined in the
Minor changes to these classes have been made in order to support sockets that
are associated with channels. This package also defines a simple class that
implements unidirectional pipes. In all cases, a new selectable channel is
created by invoking the static
open method of the corresponding class.
If a channel needs an associated socket then a socket will be created as a side
effect of this operation.
The implementation of selectors, selectable channels, and selection keys
can be replaced by "plugging in" an alternative definition or instance of the
SelectorProvider class defined in the
java.nio.channels.spi package. It is not expected that many developers
will actually make use of this facility; it is provided primarily so that
sophisticated users can take advantage of operating-system-specific
I/O-multiplexing mechanisms when very high performance is required.
Much of the bookkeeping and synchronization required to implement the
multiplexed-I/O abstractions is performed by the
AbstractSelector classes in the
java.nio.channels.spi package. When defining a custom selector provider,
AbstractSelectionKey classes should be subclassed
directly; custom channel classes should extend the appropriate
SelectableChannel subclasses defined in this package.
Asynchronous I/O Description
An asynchronous channel for reading, writing, and manipulating a file
An asynchronous channel to a stream-oriented connecting socket
An asynchronous channel to a stream-oriented listening socket
A handler for consuming the result of an asynchronous operation
A grouping of asynchronous channels for the purpose of resource sharing
Asynchronous channels are a
special type of channel capable of asynchronous I/O operations. Asynchronous
channels are non-blocking and define methods to initiate asynchronous
operations, returning a
Future representing the
pending result of each operation. The
Future can be used to poll or
wait for the result of the operation. Asynchronous I/O operations can also
CompletionHandler to invoke when the
operation completes. A completion handler is user provided code that is executed
to consume the result of I/O operation.
This package defines asynchronous-channel classes that are connected to
a stream-oriented connecting or listening socket, or a datagram-oriented socket.
It also defines the
for asynchronous reading, writing, and manipulating a file. As with the
FileChannel it supports operations to truncate the file
to a specific size, force updates to the file to be written to the storage
device, or acquire locks on the whole file or on a specific region of the file.
FileChannel it does not define methods for mapping a
region of the file directly into memory. Where memory mapped I/O is required,
FileChannel can be used.
Asynchronous channels are bound to an asynchronous channel group for the
purpose of resource sharing. A group has an associated
ExecutorService 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. The group can
optionally be specified when creating the channel or the channel can be bound
to a default group. Sophisticated users may wish to create their
own asynchronous channel groups or configure the
that will be used for the default group.
As with selectors, the implementation of asynchronous channels can be
replaced by "plugging in" an alternative definition or instance of the
AsynchronousChannelProvider class defined in the
java.nio.channels.spi package. It is not expected that many
developers will actually make use of this facility; it is provided primarily
so that sophisticated users can take advantage of operating-system-specific
asynchronous I/O mechanisms when very high performance is required.
Unless otherwise noted, passing a
null argument to a constructor
or method in any class or interface in this package will cause a
NullPointerException to be thrown.
Interface Summary Interface Description AsynchronousByteChannelAn asynchronous channel that can read and write bytes. AsynchronousChannelA channel that supports asynchronous I/O operations. ByteChannelA channel that can read and write bytes. ChannelA nexus for I/O operations. CompletionHandler<V,A>A handler for consuming the result of an asynchronous I/O operation. GatheringByteChannelA channel that can write bytes from a sequence of buffers. InterruptibleChannelA channel that can be asynchronously closed and interrupted. MulticastChannelA network channel that supports Internet Protocol (IP) multicasting. NetworkChannelA channel to a network socket. ReadableByteChannelA channel that can read bytes. ScatteringByteChannelA channel that can read bytes into a sequence of buffers. SeekableByteChannelA byte channel that maintains a current position and allows the position to be changed. WritableByteChannelA channel that can write bytes.
Class Summary Class Description AsynchronousChannelGroupA grouping of asynchronous channels for the purpose of resource sharing. AsynchronousFileChannelAn asynchronous channel for reading, writing, and manipulating a file. AsynchronousServerSocketChannelAn asynchronous channel for stream-oriented listening sockets. AsynchronousSocketChannelAn asynchronous channel for stream-oriented connecting sockets. ChannelsUtility methods for channels and streams. DatagramChannelA selectable channel for datagram-oriented sockets. FileChannelA channel for reading, writing, mapping, and manipulating a file. FileChannel.MapModeA typesafe enumeration for file-mapping modes. FileLockA token representing a lock on a region of a file. MembershipKeyA token representing the membership of an Internet Protocol (IP) multicast group. PipeA pair of channels that implements a unidirectional pipe. Pipe.SinkChannelA channel representing the writable end of a
Pipe.SourceChannelA channel representing the readable end of a
SelectableChannelA channel that can be multiplexed via a
SelectionKey SelectorA multiplexor of
ServerSocketChannelA selectable channel for stream-oriented listening sockets. SocketChannelA selectable channel for stream-oriented connecting sockets.
Exception Summary Exception Description AcceptPendingExceptionUnchecked exception thrown when an attempt is made to initiate an accept operation on a channel and a previous accept operation has not completed. AlreadyBoundExceptionUnchecked exception thrown when an attempt is made to bind the socket a network oriented channel that is already bound. AlreadyConnectedExceptionUnchecked exception thrown when an attempt is made to connect a
SocketChannelthat is already connected.
AsynchronousCloseExceptionChecked 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. CancelledKeyExceptionUnchecked exception thrown when an attempt is made to use a selection key that is no longer valid. ClosedByInterruptExceptionChecked exception received by a thread when another thread interrupts it while it is blocked in an I/O operation upon a channel. ClosedChannelExceptionChecked 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. ClosedSelectorExceptionUnchecked exception thrown when an attempt is made to invoke an I/O operation upon a closed selector. ConnectionPendingExceptionUnchecked exception thrown when an attempt is made to connect a
SocketChannelfor which a non-blocking connection operation is already in progress.
FileLockInterruptionExceptionChecked exception received by a thread when another thread interrupts it while it is waiting to acquire a file lock. IllegalBlockingModeExceptionUnchecked exception thrown when a blocking-mode-specific operation is invoked upon a channel in the incorrect blocking mode. IllegalChannelGroupExceptionUnchecked exception thrown when an attempt is made to open a channel in a group that was not created by the same provider. IllegalSelectorExceptionUnchecked 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. InterruptedByTimeoutExceptionChecked exception received by a thread when a timeout elapses before an asynchronous operation completes. NoConnectionPendingException NonReadableChannelExceptionUnchecked exception thrown when an attempt is made to read from a channel that was not originally opened for reading. NonWritableChannelExceptionUnchecked exception thrown when an attempt is made to write to a channel that was not originally opened for writing. NotYetBoundExceptionUnchecked exception thrown when an attempt is made to invoke an I/O operation upon a server socket channel that is not yet bound. NotYetConnectedExceptionUnchecked exception thrown when an attempt is made to invoke an I/O operation upon a socket channel that is not yet connected. OverlappingFileLockExceptionUnchecked 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. ReadPendingExceptionUnchecked exception thrown when an attempt is made to read from an asynchronous socket channel and a previous read has not completed. ShutdownChannelGroupExceptionUnchecked 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. UnresolvedAddressExceptionUnchecked exception thrown when an attempt is made to invoke a network operation upon an unresolved socket address. UnsupportedAddressTypeExceptionUnchecked exception thrown when an attempt is made to bind or connect to a socket address of a type that is not supported. WritePendingExceptionUnchecked exception thrown when an attempt is made to write to an asynchronous socket channel and a previous write has not completed.