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

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

The {@link java.nio.channels.Channel} interface is extended by several other interfaces, each of which specifies a new I/O operation.

The {@link java.nio.channels.ReadableByteChannel} interface specifies a {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes from the channel into a buffer; similarly, the {@link java.nio.channels.WritableByteChannel} interface specifies a {@link java.nio.channels.WritableByteChannel#write write} method that writes bytes from a buffer to the channel. The {@link java.nio.channels.ByteChannel} interface unifies these two interfaces for the common case of channels that can both read and write bytes.

The {@link java.nio.channels.ScatteringByteChannel} and {@link java.nio.channels.GatheringByteChannel} interfaces extend the {@link java.nio.channels.ReadableByteChannel} and {@link java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link java.nio.channels.ScatteringByteChannel#read read} and {@link java.nio.channels.GatheringByteChannel#write write} methods that take a sequence of buffers rather than a single buffer.

The {@link java.nio.channels.Channels} utility class defines static methods that support the interoperation of the stream classes of the {@link java.io} package with the channel classes of this package. An appropriate channel can be constructed from an {@link java.io.InputStream} or an {@link java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an {@link java.io.OutputStream} can be constructed from a channel. A {@link java.io.Reader} can be constructed that uses a given charset to decode bytes from a given readable byte channel, and conversely a {@link java.io.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

{@link java.nio.channels.FileChannel} Reads, writes, maps, and manipulates files
{@link java.nio.channels.FileLock} A lock on a (region of a) file
{@link java.nio.MappedByteBuffer}   A direct byte buffer mapped to a region of a file

The {@link java.nio.channels.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 {@link java.nio.channels.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 {@link java.nio.MappedByteBuffer} class, which extends the {@link java.nio.ByteBuffer} class with several file-related operations.

A getChannel method has been added to each of the {@link java.io.FileInputStream#getChannel FileInputStream}, {@link java.io.FileOutputStream#getChannel FileOutputStream}, and {@link java.io.RandomAccessFile#getChannel RandomAccessFile} classes of the {@link java.io 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

{@link java.nio.channels.SelectableChannel} A channel that can be multiplexed
  {@link java.nio.channels.DatagramChannel} A channel for a {@link java.net.DatagramSocket java.net.DatagramSocket}
  {@link java.nio.channels.Pipe.SinkChannel} The write end of a pipe
  {@link java.nio.channels.Pipe.SourceChannel} The read end of a pipe
  {@link java.nio.channels.ServerSocketChannel}   A channel for a {@link java.net.ServerSocket java.net.ServerSocket}
  {@link java.nio.channels.SocketChannel} A channel for a {@link java.net.Socket java.net.Socket}
{@link java.nio.channels.Selector} A multiplexor of selectable channels
{@link java.nio.channels.SelectionKey} A token representing the registration
of a channel with a selector
{@link java.nio.channels.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 {@link java.nio.channels.SelectableChannel#register 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 {@link java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link java.net.Socket} classes defined in the {@link 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 {@link java.nio.channels.spi.SelectorProvider} class defined in the {@link 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 {@link java.nio.channels.spi.AbstractInterruptibleChannel}, {@link java.nio.channels.spi.AbstractSelectableChannel}, {@link java.nio.channels.spi.AbstractSelectionKey}, and {@link java.nio.channels.spi.AbstractSelector} classes in the {@link java.nio.channels.spi} package. When defining a custom selector provider, only the {@link java.nio.channels.spi.AbstractSelector} and {@link java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed directly; custom channel classes should extend the appropriate {@link java.nio.channels.SelectableChannel} subclasses defined in this package.

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown. @since 1.4 @author Mark Reinhold @author JSR-51 Expert Group