java.nio.channels.package-info Maven / Gradle / Ivy
Show all versions of qbicc-rt-java.base Show documentation
/*
* Copyright (c) 2001, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* 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.SeekableByteChannel}
* A {@code ByteChannel} connected to an entity that contains a variable-length
* sequence of bytes
* {@link java.nio.channels.AsynchronousChannel}
* Supports asynchronous I/O operations.
* {@link java.nio.channels.AsynchronousByteChannel}
* Can read and write bytes asynchronously
* {@link java.nio.channels.NetworkChannel}
* A channel to a network socket
* {@link java.nio.channels.MulticastChannel}
* Can join Internet Protocol (IP) multicast groups {@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.
*
*
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.SeekableByteChannel}
* interface extends the {@code ByteChannel} interface with methods to {@link
* java.nio.channels.SeekableByteChannel#position() query} and {@link
* java.nio.channels.SeekableByteChannel#position(long) modify} the channel's
* current position, and its {@link java.nio.channels.SeekableByteChannel#size
* size}.
*
*
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.NetworkChannel} interface specifies methods
* to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,
* obtain the address to which the socket is bound, and methods to {@link
* java.nio.channels.NetworkChannel#getOption get} and {@link
* java.nio.channels.NetworkChannel#setOption set} socket options. The {@link
* java.nio.channels.MulticastChannel} interface specifies methods to join
* Internet Protocol (IP) multicast groups.
*
*
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.
*
*
A {@code FileChannel} is created by invoking one of its static {@link
* java.nio.channels.FileChannel#open open} methods, or by invoking the {@code
* getChannel} method of a {@link java.io.FileInputStream}, {@link
* java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a
* file channel connected to the same underlying file as the {@link java.io}
* class.
*
*
*
*
*
* Multiplexed, non-blocking I/O
* Description {@link java.nio.channels.SelectableChannel}
* A channel that can be multiplexed
* {@link java.nio.channels.DatagramChannel}
* A channel to a datagram-oriented socket
* {@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 to a stream-oriented listening socket
* {@link java.nio.channels.SocketChannel}
* A channel for a stream-oriented connecting 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 {@code 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.
*
*
{@link java.nio.channels.DatagramChannel},
* {@link java.nio.channels.SocketChannel} and
* {@link java.nio.channels.ServerSocketChannel}s can be created
* with different {@link java.net.ProtocolFamily protocol families}. The standard
* family types are specified in {@link java.net.StandardProtocolFamily}.
*
*
Channels for Internet Protocol sockets are created using the
* {@link java.net.StandardProtocolFamily#INET INET} or {@link
* java.net.StandardProtocolFamily#INET6 INET6} protocol families. Internet
* Protocol sockets support network communication using TCP and UDP and are
* addressed using {@link java.net.InetSocketAddress}es which encapsulate an IP
* address and port number. Internet Protocol sockets are also the default
* type created, when a protocol family is not specified in the channel factory
* creation method.
*
*
Channels for Unix Domain sockets are created
* using the {@link java.net.StandardProtocolFamily#UNIX UNIX} protocol family.
* Unix Domain sockets support local inter-process
* communication on the same host, and are addressed using {@link
* java.net.UnixDomainSocketAddress}es which encapsulate a filesystem pathname
* on the local system.
*
*
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.
*
*
*
*
*
*
* Asynchronous I/O
* Description
* {@link java.nio.channels.AsynchronousFileChannel}
* An asynchronous channel for reading, writing, and manipulating a file
* {@link java.nio.channels.AsynchronousSocketChannel}
* An asynchronous channel to a stream-oriented connecting socket
* {@link java.nio.channels.AsynchronousServerSocketChannel}
* An asynchronous channel to a stream-oriented listening socket
* {@link java.nio.channels.CompletionHandler}
* A handler for consuming the result of an asynchronous operation
* {@link java.nio.channels.AsynchronousChannelGroup}
* A grouping of asynchronous channels for the purpose of resource sharing
*
* {@link java.nio.channels.AsynchronousChannel 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 {@link java.util.concurrent.Future} representing the
* pending result of each operation. The {@code Future} can be used to poll or
* wait for the result of the operation. Asynchronous I/O operations can also
* specify a {@link java.nio.channels.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 {@link java.nio.channels.AsynchronousFileChannel} class
* for asynchronous reading, writing, and manipulating a file. As with the {@link
* java.nio.channels.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.
* Unlike the {@code FileChannel} it does not define methods for mapping a
* region of the file directly into memory. Where memory mapped I/O is required,
* then a {@code FileChannel} can be used.
*
*
Asynchronous channels are bound to an asynchronous channel group for the
* purpose of resource sharing. A group has an associated {@link
* java.util.concurrent.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 {@code ExecutorService}
* 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 {@link
* java.nio.channels.spi.AsynchronousChannelProvider} 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
* asynchronous I/O mechanisms when very high performance is required.
*
*
Unless otherwise noted, passing a {@code 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
*/
package java.nio.channels;