io nio

Package Specification

• Java Object Serialization Specification

Related Documentation

• Serialization Enhancements

The central abstractions of the NIO APIs are:

• Buffers, which are containers for data;

• Charsets and their associated decoders and encoders,
  which translate between bytes and Unicode characters;

• Channels of various types, which represent connections
  to entities capable of performing I/O operations; and

• Selectors and selection keys, which together with
  selectable channels define a multiplexed, non-blocking
  I/O facility.

The java.nio package defines the buffer classes, which are used throughout the NIO APIs. The charset API is defined in the {@link java.nio.charset} package, and the channel and selector APIs are defined in the {@link java.nio.channels} package. Each of these subpackages has its own service-provider (SPI) subpackage, the contents of which can be used to extend the platform's default implementations or to construct alternative implementations.

Buffers	Description
{@link java.nio.Buffer}	Position, limit, and capacity; clear, flip, rewind, and mark/reset
{@link java.nio.ByteBuffer}	Get/put, compact, views; allocate, wrap
{@link java.nio.MappedByteBuffer}	A byte buffer mapped to a file
{@link java.nio.CharBuffer}	Get/put, compact; allocate, wrap
{@link java.nio.DoubleBuffer}	' '
{@link java.nio.FloatBuffer}	' '
{@link java.nio.IntBuffer}	' '
{@link java.nio.LongBuffer}	' '
{@link java.nio.ShortBuffer}	' '
{@link java.nio.ByteOrder}	Typesafe enumeration for byte orders

• A byte buffer can be allocated as a direct buffer, in which case the Java virtual machine will make a best effort to perform native I/O operations directly upon it.

• A byte buffer can be created by {@link java.nio.channels.FileChannel#map mapping} a region of a file directly into memory, in which case a few additional file-related operations defined in the {@link java.nio.MappedByteBuffer} class are available.

• A byte buffer provides access to its content as either a heterogeneous or homogeneous sequence of binary data of any non-boolean primitive type, in either big-endian or little-endian byte order.

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

Only developers who are defining new selector providers should need to make direct use of 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.9, 07/05/05 @author Mark Reinhold @author JSR-51 Expert Group

Class name	Description
{@link java.nio.charset.Charset}	A named mapping between characters and bytes
{@link java.nio.charset.CharsetDecoder}	Decodes bytes into characters
{@link java.nio.charset.CharsetEncoder}	Encodes characters into bytes
{@link java.nio.charset.CoderResult}	Describes coder results
{@link java.nio.charset.CodingErrorAction}	Describes actions to take when coding errors are detected

A charset is named mapping between sequences of sixteen-bit Unicode characters and sequences of bytes, in the sense defined in RFC 2278. A decoder is an engine which transforms bytes in a specific charset into characters, and an encoder is an engine which transforms characters into bytes. Encoders and decoders operate on byte and character buffers. They are collectively referred to as coders.

The {@link java.nio.charset.Charset} class defines methods for creating coders for a given charset and for retrieving the various names associated with a charset. It also defines static methods for testing whether a particular charset is supported, for locating charset instances by name, and for constructing a map that contains every charset for which support is available in the current Java virtual machine.

Most users will not use these classes directly; instead they will use the existing charset-related constructors and methods in the {@link java.lang.String} class, together with the existing {@link java.io.InputStreamReader} and {@link java.io.OutputStreamWriter} classes, all of whose implementations have been reworked to make use of the charset facilities defined in this package. A small number of changes have been made to the {@link java.io.InputStreamReader} and {@link java.io.OutputStreamWriter} classes in order to allow explicit charset objects to be specified in the construction of instances of those classes.

Support for new charsets can be made available via the interface defined in the {@link java.nio.charset.spi.CharsetProvider} class in the {@link java.nio.charset.spi} 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.8, 07/05/05 @author Mark Reinhold @author JSR-51 Expert Group

Only developers who are defining new charsets should need to make direct use of 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.6, 07/05/05 @author Mark Reinhold @author JSR-51 Expert Group