java.nio.channels

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

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 @version 1.10, 07/05/05 @author Mark Reinhold @author JSR-51 Expert Group

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.

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.

Datagram channels are not a complete abstraction of network datagram sockets.

A file channel has a current position within its file which can be both FileChannel.position() queried and FileChannel.position(long)modified .

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

A file-lock object is initially valid.

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.

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 InterruptibleChannel.close close method.

A pipe consists of a pair of channels: A writable Pipe.SinkChannel sink channel and a readable Pipe.SourceChannel source channel.

Only one read operation upon a readable channel may be in progress at any given time.

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.

In order to be used with a selector, an instance of this class must first be registered via the SelectableChannel.register(Selector,int,Object)register method.

A selection key is created each time a channel is registered with a selector.

A selector may be created by invoking the Selector.open open method of this class, which will use the system's default java.nio.channels.spi.SelectorProvider selector provider to create a new selector.

Server-socket channels are not a complete abstraction of listening network sockets.

Socket channels are not a complete abstraction of connecting network sockets.

Only one write operation upon a writable channel may be in progress at any given time.