JavaTM 2 Platform
Standard Ed. 5.0

Package java.nio.channels

Defines channels, which represent connections to entities that are capable of performing I/O operations, such as files and sockets; defines selectors, for multiplexed, non-blocking I/O operations.

See:
          Description

Interface Summary
ByteChannel A channel that can read and write bytes.
Channel A nexus for I/O operations.
GatheringByteChannel A channel that can write bytes from a sequence of buffers.
InterruptibleChannel A channel that can be asynchronously closed and interrupted.
ReadableByteChannel A channel that can read bytes.
ScatteringByteChannel A channel that can read bytes into a sequence of buffers.
WritableByteChannel A channel that can write bytes.
 

Class Summary
Channels Utility methods for channels and streams.
DatagramChannel A selectable channel for datagram-oriented sockets.
FileChannel A channel for reading, writing, mapping, and manipulating a file.
FileChannel.MapMode A typesafe enumeration for file-mapping modes.
FileLock A token representing a lock on a region of a file.
Pipe A pair of channels that implements a unidirectional pipe.
Pipe.SinkChannel A channel representing the writable end of a Pipe.
Pipe.SourceChannel A channel representing the readable end of a Pipe.
SelectableChannel A channel that can be multiplexed via a Selector.
SelectionKey A token representing the registration of a SelectableChannel with a Selector.
Selector A multiplexor of SelectableChannel objects.
ServerSocketChannel A selectable channel for stream-oriented listening sockets.
SocketChannel A selectable channel for stream-oriented connecting sockets.
 

Exception Summary
AlreadyConnectedException Unchecked exception thrown when an attempt is made to connect a SocketChannel that is already connected.
AsynchronousCloseException 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.
CancelledKeyException Unchecked exception thrown when an attempt is made to use a selection key that is no longer valid.
ClosedByInterruptException Checked exception received by a thread when another thread interrupts it while it is blocked in an I/O operation upon a channel.
ClosedChannelException 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.
ClosedSelectorException Unchecked exception thrown when an attempt is made to invoke an I/O operation upon a closed selector.
ConnectionPendingException Unchecked exception thrown when an attempt is made to connect a SocketChannel for which a non-blocking connection operation is already in progress.
FileLockInterruptionException Checked exception received by a thread when another thread interrupts it while it is waiting to acquire a file lock.
IllegalBlockingModeException Unchecked exception thrown when a blocking-mode-specific operation is invoked upon a channel in the incorrect blocking mode.
IllegalSelectorException 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.
NoConnectionPendingException Unchecked exception thrown when the finishConnect method of a SocketChannel is invoked without first successfully invoking its connect method.
NonReadableChannelException Unchecked exception thrown when an attempt is made to read from a channel that was not originally opened for reading.
NonWritableChannelException Unchecked exception thrown when an attempt is made to write to a channel that was not originally opened for writing.
NotYetBoundException Unchecked exception thrown when an attempt is made to invoke an I/O operation upon a server socket channel that is not yet bound.
NotYetConnectedException Unchecked exception thrown when an attempt is made to invoke an I/O operation upon a socket channel that is not yet connected.
OverlappingFileLockException 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.
UnresolvedAddressException Unchecked exception thrown when an attempt is made to invoke a network operation upon an unresolved socket address.
UnsupportedAddressTypeException Unchecked exception thrown when an attempt is made to bind or connect to a socket address of a type that is not supported.
 

Package java.nio.channels Description

Defines channels, which represent connections to entities that are capable of performing I/O operations, such as files and sockets; defines selectors, for multiplexed, non-blocking I/O operations.

Channels

Description

Channel A nexus for I/O operations
  ReadableByteChannel Can read into a buffer
    ScatteringByteChannel   Can read into a sequence of buffers
  WritableByteChannel Can write from a buffer
    GatheringByteChannel Can write from a sequence of buffers
  ByteChannel Can read/write to/from a buffer
Channels 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 Channel interface, channels are either open or closed, and they are both asynchronously closeable and interruptible.

The Channel interface is extended by several other interfaces, each of which specifies a new I/O operation.

The 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 ByteChannel interface unifies these two interfaces for the common case of channels that can both read and write bytes.

The ScatteringByteChannel and GatheringByteChannel interfaces extend the ReadableByteChannel and WritableByteChannel interfaces, respectively, adding read and write methods that take a sequence of buffers rather than a single buffer.

The 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 Writer can be constructed that uses a given charset to encode characters into bytes and write them to a given writable byte channel.

File channels

Description

FileChannel Reads, writes, maps, and manipulates files
FileLock A lock on a (region of a) file
MappedByteBuffer   A direct byte buffer mapped to a region of a file

The 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. This last operation creates an instance of the MappedByteBuffer class, which extends the ByteBuffer class with several file-related operations.

A getChannel method has been added to each of the FileInputStream, FileOutputStream, and RandomAccessFile classes of the java.io package. Invoking this method upon an instance of one of these classes will return a file channel connected to the underlying file.

Multiplexed, non-blocking I/O

Description

SelectableChannel A channel that can be multiplexed
  DatagramChannel A channel for a java.net.DatagramSocket
  Pipe.SinkChannel The write end of a pipe
  Pipe.SourceChannel The read end of a pipe
  ServerSocketChannel   A channel for a java.net.ServerSocket
  SocketChannel A channel for a java.net.Socket
Selector A multiplexor of selectable channels
SelectionKey A token representing the registration
of a channel with a selector
Pipe 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 registered 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 registration.

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 DatagramSocket, ServerSocket, and Socket classes defined in the java.net package. 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 AbstractInterruptibleChannel, AbstractSelectableChannel, AbstractSelectionKey, and AbstractSelector classes in the java.nio.channels.spi package. When defining a custom selector provider, only the AbstractSelector and AbstractSelectionKey classes should be subclassed directly; custom channel classes should extend the appropriate SelectableChannel subclasses defined in this package.

Since:
1.4

JavaTM 2 Platform
Standard Ed. 5.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.