Path: blob/aarch64-shenandoah-jdk8u272-b10/jdk/src/share/classes/java/nio/channels/package-info.java
38918 views
/*1* Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.2* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.3*4* This code is free software; you can redistribute it and/or modify it5* under the terms of the GNU General Public License version 2 only, as6* published by the Free Software Foundation. Oracle designates this7* particular file as subject to the "Classpath" exception as provided8* by Oracle in the LICENSE file that accompanied this code.9*10* This code is distributed in the hope that it will be useful, but WITHOUT11* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or12* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License13* version 2 for more details (a copy is included in the LICENSE file that14* accompanied this code).15*16* You should have received a copy of the GNU General Public License version17* 2 along with this work; if not, write to the Free Software Foundation,18* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.19*20* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA21* or visit www.oracle.com if you need additional information or have any22* questions.23*/2425/**26* Defines channels, which represent connections to entities that are capable of27* performing I/O operations, such as files and sockets; defines selectors, for28* multiplexed, non-blocking I/O operations.29*30* <a name="channels"></a>31*32* <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions">33* <tr><th align="left">Channels</th><th align="left">Description</th></tr>34* <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td>35* <td>A nexus for I/O operations</td></tr>36* <tr><td valign=top><tt> <i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>37* <td>Can read into a buffer</td></tr>38* <tr><td valign=top><tt> <i>{@link java.nio.channels.ScatteringByteChannel} </i></tt></td>39* <td>Can read into a sequence of buffers</td></tr>40* <tr><td valign=top><tt> <i>{@link java.nio.channels.WritableByteChannel}</i></tt></td>41* <td>Can write from a buffer</td></tr>42* <tr><td valign=top><tt> <i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td>43* <td>Can write from a sequence of buffers</td></tr>44* <tr><td valign=top><tt> <i>{@link java.nio.channels.ByteChannel}</i></tt></td>45* <td>Can read/write to/from a buffer</td></tr>46* <tr><td valign=top><tt> <i>{@link java.nio.channels.SeekableByteChannel}</i></tt></td>47* <td>A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes</td></tr>48* <tr><td valign=top><tt> <i>{@link java.nio.channels.AsynchronousChannel}</i></tt></td>49* <td>Supports asynchronous I/O operations.</td></tr>50* <tr><td valign=top><tt> <i>{@link java.nio.channels.AsynchronousByteChannel}</i></tt></td>51* <td>Can read and write bytes asynchronously</td></tr>52* <tr><td valign=top><tt> <i>{@link java.nio.channels.NetworkChannel}</i></tt></td>53* <td>A channel to a network socket</td></tr>54* <tr><td valign=top><tt> <i>{@link java.nio.channels.MulticastChannel}</i></tt></td>55* <td>Can join Internet Protocol (IP) multicast groups</td></tr>56* <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td>57* <td>Utility methods for channel/stream interoperation</td></tr>58* </table></blockquote>59*60* <p> A <i>channel</i> represents an open connection to an entity such as a61* hardware device, a file, a network socket, or a program component that is62* capable of performing one or more distinct I/O operations, for example reading63* or writing. As specified in the {@link java.nio.channels.Channel} interface,64* channels are either open or closed, and they are both <i>asynchronously65* closeable</i> and <i>interruptible</i>.66*67* <p> The {@link java.nio.channels.Channel} interface is extended by several68* other interfaces.69*70* <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a71* {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes72* from the channel into a buffer; similarly, the {@link73* java.nio.channels.WritableByteChannel} interface specifies a {@link74* java.nio.channels.WritableByteChannel#write write} method that writes bytes75* from a buffer to the channel. The {@link java.nio.channels.ByteChannel}76* interface unifies these two interfaces for the common case of channels that can77* both read and write bytes. The {@link java.nio.channels.SeekableByteChannel}78* interface extends the {@code ByteChannel} interface with methods to {@link79* java.nio.channels.SeekableByteChannel#position() query} and {@link80* java.nio.channels.SeekableByteChannel#position(long) modify} the channel's81* current position, and its {@link java.nio.channels.SeekableByteChannel#size82* size}.83*84* <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link85* java.nio.channels.GatheringByteChannel} interfaces extend the {@link86* java.nio.channels.ReadableByteChannel} and {@link87* java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link88* java.nio.channels.ScatteringByteChannel#read read} and {@link89* java.nio.channels.GatheringByteChannel#write write} methods that take a90* sequence of buffers rather than a single buffer.91*92* <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods93* to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,94* obtain the address to which the socket is bound, and methods to {@link95* java.nio.channels.NetworkChannel#getOption get} and {@link96* java.nio.channels.NetworkChannel#setOption set} socket options. The {@link97* java.nio.channels.MulticastChannel} interface specifies methods to join98* Internet Protocol (IP) multicast groups.99*100* <p> The {@link java.nio.channels.Channels} utility class defines static methods101* that support the interoperation of the stream classes of the <tt>{@link102* java.io}</tt> package with the channel classes of this package. An appropriate103* channel can be constructed from an {@link java.io.InputStream} or an {@link104* java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an105* {@link java.io.OutputStream} can be constructed from a channel. A {@link106* java.io.Reader} can be constructed that uses a given charset to decode bytes107* from a given readable byte channel, and conversely a {@link java.io.Writer} can108* be constructed that uses a given charset to encode characters into bytes and109* write them to a given writable byte channel.110*111* <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">112* <tr><th align="left">File channels</th><th align="left">Description</th></tr>113* <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>114* <td>Reads, writes, maps, and manipulates files</td></tr>115* <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>116* <td>A lock on a (region of a) file</td></tr>117* <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer} </tt></td>118* <td>A direct byte buffer mapped to a region of a file</td></tr>119* </table></blockquote>120*121* <p> The {@link java.nio.channels.FileChannel} class supports the usual122* operations of reading bytes from, and writing bytes to, a channel connected to123* a file, as well as those of querying and modifying the current file position124* and truncating the file to a specific size. It defines methods for acquiring125* locks on the whole file or on a specific region of a file; these methods return126* instances of the {@link java.nio.channels.FileLock} class. Finally, it defines127* methods for forcing updates to the file to be written to the storage device that128* contains it, for efficiently transferring bytes between the file and other129* channels, and for mapping a region of the file directly into memory.130*131* <p> A {@code FileChannel} is created by invoking one of its static {@link132* java.nio.channels.FileChannel#open open} methods, or by invoking the {@code133* getChannel} method of a {@link java.io.FileInputStream}, {@link134* java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a135* file channel connected to the same underlying file as the <tt>{@link java.io}</tt>136* class.137*138* <a name="multiplex"></a>139* <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">140* <tr><th align="left">Multiplexed, non-blocking I/O</th><th align="left"><p>Description</th></tr>141* <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>142* <td>A channel that can be multiplexed</td></tr>143* <tr><td valign=top><tt> {@link java.nio.channels.DatagramChannel}</tt></td>144* <td>A channel to a datagram-oriented socket</td></tr>145* <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SinkChannel}</tt></td>146* <td>The write end of a pipe</td></tr>147* <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SourceChannel}</tt></td>148* <td>The read end of a pipe</td></tr>149* <tr><td valign=top><tt> {@link java.nio.channels.ServerSocketChannel} </tt></td>150* <td>A channel to a stream-oriented listening socket</td></tr>151* <tr><td valign=top><tt> {@link java.nio.channels.SocketChannel}</tt></td>152* <td>A channel for a stream-oriented connecting socket</td></tr>153* <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td>154* <td>A multiplexor of selectable channels</td></tr>155* <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td>156* <td>A token representing the registration <br> of a channel157* with a selector</td></tr>158* <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>159* <td>Two channels that form a unidirectional pipe</td></tr>160* </table></blockquote>161*162* <p> Multiplexed, non-blocking I/O, which is much more scalable than163* thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable164* channels</i>, and <i>selection keys</i>.165*166* <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a167* href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are168* a special type of channel that can be put into <a169* href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform170* multiplexed I/O operations, one or more selectable channels are first created,171* put into non-blocking mode, and {@link172* java.nio.channels.SelectableChannel#register <i>registered</i>}173* with a selector. Registering a channel specifies the set of I/O operations174* that will be tested for readiness by the selector, and returns a <a175* href="SelectionKey.html"><i>selection key</i></a> that represents the176* registration.177*178* <p> Once some channels have been registered with a selector, a <a179* href="Selector.html#selop"><i>selection operation</i></a> can be performed in180* order to discover which channels, if any, have become ready to perform one or181* more of the operations in which interest was previously declared. If a channel182* is ready then the key returned when it was registered will be added to the183* selector's <i>selected-key set</i>. The key set, and the keys within it, can184* be examined in order to determine the operations for which each channel is185* ready. From each key one can retrieve the corresponding channel in order to186* perform whatever I/O operations are required.187*188* <p> That a selection key indicates that its channel is ready for some operation189* is a hint, but not a guarantee, that such an operation can be performed by a190* thread without causing the thread to block. It is imperative that code that191* performs multiplexed I/O be written so as to ignore these hints when they prove192* to be incorrect.193*194* <p> This package defines selectable-channel classes corresponding to the {@link195* java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link196* java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package.197* Minor changes to these classes have been made in order to support sockets that198* are associated with channels. This package also defines a simple class that199* implements unidirectional pipes. In all cases, a new selectable channel is200* created by invoking the static <tt>open</tt> method of the corresponding class.201* If a channel needs an associated socket then a socket will be created as a side202* effect of this operation.203*204* <p> The implementation of selectors, selectable channels, and selection keys205* can be replaced by "plugging in" an alternative definition or instance of the206* {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link207* java.nio.channels.spi}</tt> package. It is not expected that many developers208* will actually make use of this facility; it is provided primarily so that209* sophisticated users can take advantage of operating-system-specific210* I/O-multiplexing mechanisms when very high performance is required.211*212* <p> Much of the bookkeeping and synchronization required to implement the213* multiplexed-I/O abstractions is performed by the {@link214* java.nio.channels.spi.AbstractInterruptibleChannel}, {@link215* java.nio.channels.spi.AbstractSelectableChannel}, {@link216* java.nio.channels.spi.AbstractSelectionKey}, and {@link217* java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link218* java.nio.channels.spi}</tt> package. When defining a custom selector provider,219* only the {@link java.nio.channels.spi.AbstractSelector} and {@link220* java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed221* directly; custom channel classes should extend the appropriate {@link222* java.nio.channels.SelectableChannel} subclasses defined in this package.223*224* <a name="async"></a>225*226* <blockquote><table cellspacing=1 cellpadding=0 summary="Lists asynchronous channels and their descriptions">227* <tr><th align="left">Asynchronous I/O</th><th align="left">Description</th></tr>228* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousFileChannel}</tt></td>229* <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr>230* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousSocketChannel}</tt></td>231* <td>An asynchronous channel to a stream-oriented connecting socket</td></tr>232* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousServerSocketChannel} </tt></td>233* <td>An asynchronous channel to a stream-oriented listening socket</td></tr>234* <tr><td valign=top><tt>{@link java.nio.channels.CompletionHandler}</tt></td>235* <td>A handler for consuming the result of an asynchronous operation</td></tr>236* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousChannelGroup}</tt></td>237* <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr>238* </table></blockquote>239*240* <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a241* special type of channel capable of asynchronous I/O operations. Asynchronous242* channels are non-blocking and define methods to initiate asynchronous243* operations, returning a {@link java.util.concurrent.Future} representing the244* pending result of each operation. The {@code Future} can be used to poll or245* wait for the result of the operation. Asynchronous I/O operations can also246* specify a {@link java.nio.channels.CompletionHandler} to invoke when the247* operation completes. A completion handler is user provided code that is executed248* to consume the result of I/O operation.249*250* <p> This package defines asynchronous-channel classes that are connected to251* a stream-oriented connecting or listening socket, or a datagram-oriented socket.252* It also defines the {@link java.nio.channels.AsynchronousFileChannel} class253* for asynchronous reading, writing, and manipulating a file. As with the {@link254* java.nio.channels.FileChannel} it supports operations to truncate the file255* to a specific size, force updates to the file to be written to the storage256* device, or acquire locks on the whole file or on a specific region of the file.257* Unlike the {@code FileChannel} it does not define methods for mapping a258* region of the file directly into memory. Where memory mapped I/O is required,259* then a {@code FileChannel} can be used.260*261* <p> Asynchronous channels are bound to an asynchronous channel group for the262* purpose of resource sharing. A group has an associated {@link263* java.util.concurrent.ExecutorService} to which tasks are submitted to handle264* I/O events and dispatch to completion handlers that consume the result of265* asynchronous operations performed on channels in the group. The group can266* optionally be specified when creating the channel or the channel can be bound267* to a <em>default group</em>. Sophisticated users may wish to create their268* own asynchronous channel groups or configure the {@code ExecutorService}269* that will be used for the default group.270*271* <p> As with selectors, the implementation of asynchronous channels can be272* replaced by "plugging in" an alternative definition or instance of the {@link273* java.nio.channels.spi.AsynchronousChannelProvider} class defined in the274* <tt>{@link java.nio.channels.spi}</tt> package. It is not expected that many275* developers will actually make use of this facility; it is provided primarily276* so that sophisticated users can take advantage of operating-system-specific277* asynchronous I/O mechanisms when very high performance is required.278*279* <hr width="80%">280* <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor281* or method in any class or interface in this package will cause a {@link282* java.lang.NullPointerException NullPointerException} to be thrown.283*284* @since 1.4285* @author Mark Reinhold286* @author JSR-51 Expert Group287*/288289package java.nio.channels;290291292