annotate src/share/classes/java/nio/channels/package.html @ 0:37a05a11f281

Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
rev   line source
duke@0 1 <!--
duke@0 2 Copyright 2001-2005 Sun Microsystems, Inc. All Rights Reserved.
duke@0 4
duke@0 5 This code is free software; you can redistribute it and/or modify it
duke@0 6 under the terms of the GNU General Public License version 2 only, as
duke@0 7 published by the Free Software Foundation. Sun designates this
duke@0 8 particular file as subject to the "Classpath" exception as provided
duke@0 9 by Sun in the LICENSE file that accompanied this code.
duke@0 10
duke@0 11 This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 14 version 2 for more details (a copy is included in the LICENSE file that
duke@0 15 accompanied this code).
duke@0 16
duke@0 17 You should have received a copy of the GNU General Public License version
duke@0 18 2 along with this work; if not, write to the Free Software Foundation,
duke@0 19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 20
duke@0 21 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@0 22 CA 95054 USA or visit if you need additional information or
duke@0 23 have any questions.
duke@0 24 -->
duke@0 25
duke@0 26 <!doctype html public "-//IETF//DTD HTML//EN">
duke@0 27 <html>
duke@0 28 <body bgcolor="white">
duke@0 29
duke@0 30 Defines channels, which represent connections to entities that are capable of
duke@0 31 performing I/O operations, such as files and sockets; defines selectors, for
duke@0 32 multiplexed, non-blocking I/O operations.
duke@0 33
duke@0 34
duke@0 35 <a name="channels">
duke@0 36
duke@0 37 <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions">
duke@0 38 <tr><th><p align="left">Channels</p></th><th><p align="left">Description</p></th></tr>
duke@0 39 <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td>
duke@0 40 <td>A nexus for I/O operations</td></tr>
duke@0 41 <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>
duke@0 42 <td>Can read into a buffer</td></tr>
duke@0 43 <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.ScatteringByteChannel}&nbsp;&nbsp;</i></tt></td>
duke@0 44 <td>Can read into a sequence of&nbsp;buffers</td></tr>
duke@0 45 <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.WritableByteChannel}</i></tt></td>
duke@0 46 <td>Can write from a buffer</td></tr>
duke@0 47 <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td>
duke@0 48 <td>Can write from a sequence of&nbsp;buffers</td></tr>
duke@0 49 <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ByteChannel}</i></tt></td>
duke@0 50 <td>Can read/write to/from a&nbsp;buffer</td></tr>
duke@0 51 <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td>
duke@0 52 <td>Utility methods for channel/stream interoperation</td></tr>
duke@0 53 </table></blockquote>
duke@0 54
duke@0 55 <p> A <i>channel</i> represents an open connection to an entity such as a
duke@0 56 hardware device, a file, a network socket, or a program component that is
duke@0 57 capable of performing one or more distinct I/O operations, for example reading
duke@0 58 or writing. As specified in the {@link java.nio.channels.Channel} interface,
duke@0 59 channels are either open or closed, and they are both <i>asynchronously
duke@0 60 closeable</i> and <i>interruptible</i>.
duke@0 61
duke@0 62 <p> The {@link java.nio.channels.Channel} interface is extended by several
duke@0 63 other interfaces, each of which specifies a new I/O operation.
duke@0 64
duke@0 65 <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a
duke@0 66 {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes
duke@0 67 from the channel into a buffer; similarly, the {@link
duke@0 68 java.nio.channels.WritableByteChannel} interface specifies a {@link
duke@0 69 java.nio.channels.WritableByteChannel#write write} method that writes bytes
duke@0 70 from a buffer to the channel. The {@link java.nio.channels.ByteChannel}
duke@0 71 interface unifies these two interfaces for the common case of channels that can
duke@0 72 both read and write bytes.
duke@0 73
duke@0 74 <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
duke@0 75 java.nio.channels.GatheringByteChannel} interfaces extend the {@link
duke@0 76 java.nio.channels.ReadableByteChannel} and {@link
duke@0 77 java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
duke@0 78 java.nio.channels.ScatteringByteChannel#read read} and {@link
duke@0 79 java.nio.channels.GatheringByteChannel#write write} methods that take a
duke@0 80 sequence of buffers rather than a single buffer.
duke@0 81
duke@0 82 <p> The {@link java.nio.channels.Channels} utility class defines static methods
duke@0 83 that support the interoperation of the stream classes of the <tt>{@link
duke@0 84}</tt> package with the channel classes of this package. An appropriate
duke@0 85 channel can be constructed from an {@link} or an {@link
duke@0 86}, and conversely an {@link} or an
duke@0 87 {@link} can be constructed from a channel. A {@link
duke@0 88} can be constructed that uses a given charset to decode bytes
duke@0 89 from a given readable byte channel, and conversely a {@link} can
duke@0 90 be constructed that uses a given charset to encode characters into bytes and
duke@0 91 write them to a given writable byte channel.
duke@0 92
duke@0 93
duke@0 94 <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">
duke@0 95 <tr><th><p align="left">File channels</p></th><th><p align="left">Description</p></th></tr>
duke@0 96 <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>
duke@0 97 <td>Reads, writes, maps, and manipulates files</td></tr>
duke@0 98 <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>
duke@0 99 <td>A lock on a (region of a) file</td></tr>
duke@0 100 <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer}&nbsp;&nbsp;</tt></td>
duke@0 101 <td>A direct byte buffer mapped to a region of a&nbsp;file</td></tr>
duke@0 102 </table></blockquote>
duke@0 103
duke@0 104 <p> The {@link java.nio.channels.FileChannel} class supports the usual
duke@0 105 operations of reading bytes from, and writing bytes to, a channel connected to
duke@0 106 a file, as well as those of querying and modifying the current file position
duke@0 107 and truncating the file to a specific size. It defines methods for acquiring
duke@0 108 locks on the whole file or on a specific region of a file; these methods return
duke@0 109 instances of the {@link java.nio.channels.FileLock} class. Finally, it defines
duke@0 110 methods for forcing updates to the file to be written to the storage device that
duke@0 111 contains it, for efficiently transferring bytes between the file and other
duke@0 112 channels, and for mapping a region of the file directly into memory. This last
duke@0 113 operation creates an instance of the {@link java.nio.MappedByteBuffer}
duke@0 114 class, which extends the {@link java.nio.ByteBuffer} class with several
duke@0 115 file-related operations.
duke@0 116
duke@0 117 <p> A <tt>getChannel</tt> method has been added to each of the {@link
duke@0 118 FileInputStream}, {@link
duke@0 119 FileOutputStream}, and {@link
duke@0 120 RandomAccessFile} classes of the <tt>{@link
duke@0 121}</tt> package. Invoking this method upon an instance of one of
duke@0 122 these classes will return a file channel connected to the underlying file.
duke@0 123
duke@0 124
duke@0 125 <a name="multiplex">
duke@0 126
duke@0 127 <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">
duke@0 128 <tr><th><p align="left">Multiplexed, non-blocking I/O</p></th><th><p align="left">Description</p></th></tr>
duke@0 129 <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>
duke@0 130 <td>A channel that can be multiplexed</td></tr>
duke@0 131 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.DatagramChannel}</tt></td>
duke@0 132 <td>A channel for a {@link}</td></tr>
duke@0 133 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SinkChannel}</tt></td>
duke@0 134 <td>The write end of a pipe</td></tr>
duke@0 135 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SourceChannel}</tt></td>
duke@0 136 <td>The read end of a pipe</td></tr>
duke@0 137 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.ServerSocketChannel}&nbsp;&nbsp;</tt></td>
duke@0 138 <td>A channel for a {@link}</td></tr>
duke@0 139 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.SocketChannel}</tt></td>
duke@0 140 <td>A channel for a {@link}</td></tr>
duke@0 141 <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td>
duke@0 142 <td>A multiplexor of selectable channels</td></tr>
duke@0 143 <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td>
duke@0 144 <td>A token representing the registration <br> of a channel
duke@0 145 with&nbsp;a&nbsp;selector</td></tr>
duke@0 146 <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>
duke@0 147 <td>Two channels that form a unidirectional&nbsp;pipe</td></tr>
duke@0 148 </table></blockquote>
duke@0 149
duke@0 150 <p> Multiplexed, non-blocking I/O, which is much more scalable than
duke@0 151 thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable
duke@0 152 channels</i>, and <i>selection keys</i>.
duke@0 153
duke@0 154 <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a
duke@0 155 href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are
duke@0 156 a special type of channel that can be put into <a
duke@0 157 href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform
duke@0 158 multiplexed I/O operations, one or more selectable channels are first created,
duke@0 159 put into non-blocking mode, and {@link
duke@0 160 java.nio.channels.SelectableChannel#register </code><i>registered</i><code>}
duke@0 161 with a selector. Registering a channel specifies the set of I/O operations
duke@0 162 that will be tested for readiness by the selector, and returns a <a
duke@0 163 href="SelectionKey.html"><i>selection key</i></a> that represents the
duke@0 164 registration.
duke@0 165
duke@0 166 <p> Once some channels have been registered with a selector, a <a
duke@0 167 href="Selector.html#selop"><i>selection operation</i></a> can be performed in
duke@0 168 order to discover which channels, if any, have become ready to perform one or
duke@0 169 more of the operations in which interest was previously declared. If a channel
duke@0 170 is ready then the key returned when it was registered will be added to the
duke@0 171 selector's <i>selected-key set</i>. The key set, and the keys within it, can
duke@0 172 be examined in order to determine the operations for which each channel is
duke@0 173 ready. From each key one can retrieve the corresponding channel in order to
duke@0 174 perform whatever I/O operations are required.
duke@0 175
duke@0 176 <p> That a selection key indicates that its channel is ready for some operation
duke@0 177 is a hint, but not a guarantee, that such an operation can be performed by a
duke@0 178 thread without causing the thread to block. It is imperative that code that
duke@0 179 performs multiplexed I/O be written so as to ignore these hints when they prove
duke@0 180 to be incorrect.
duke@0 181
duke@0 182 <p> This package defines selectable-channel classes corresponding to the {@link
duke@0 183}, {@link}, and {@link
duke@0 184} classes defined in the <tt>{@link}</tt> package.
duke@0 185 Minor changes to these classes have been made in order to support sockets that
duke@0 186 are associated with channels. This package also defines a simple class that
duke@0 187 implements unidirectional pipes. In all cases, a new selectable channel is
duke@0 188 created by invoking the static <tt>open</tt> method of the corresponding class.
duke@0 189 If a channel needs an associated socket then a socket will be created as a side
duke@0 190 effect of this operation.
duke@0 191
duke@0 192 <p> The implementation of selectors, selectable channels, and selection keys
duke@0 193 can be replaced by "plugging in" an alternative definition or instance of the
duke@0 194 {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link
duke@0 195 java.nio.channels.spi}</tt> package. It is not expected that many developers
duke@0 196 will actually make use of this facility; it is provided primarily so that
duke@0 197 sophisticated users can take advantage of operating-system-specific
duke@0 198 I/O-multiplexing mechanisms when very high performance is required.
duke@0 199
duke@0 200 <p> Much of the bookkeeping and synchronization required to implement the
duke@0 201 multiplexed-I/O abstractions is performed by the {@link
duke@0 202 java.nio.channels.spi.AbstractInterruptibleChannel}, {@link
duke@0 203 java.nio.channels.spi.AbstractSelectableChannel}, {@link
duke@0 204 java.nio.channels.spi.AbstractSelectionKey}, and {@link
duke@0 205 java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link
duke@0 206 java.nio.channels.spi}</tt> package. When defining a custom selector provider,
duke@0 207 only the {@link java.nio.channels.spi.AbstractSelector} and {@link
duke@0 208 java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed
duke@0 209 directly; custom channel classes should extend the appropriate {@link
duke@0 210 java.nio.channels.SelectableChannel} subclasses defined in this package.
duke@0 211
duke@0 212 <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
duke@0 213 or method in any class or interface in this package will cause a {@link
duke@0 214 java.lang.NullPointerException NullPointerException} to be thrown.
duke@0 215
duke@0 216
duke@0 217 @since 1.4
duke@0 218 @author Mark Reinhold
duke@0 219 @author JSR-51 Expert Group
duke@0 220
duke@0 221 </body>
duke@0 222 </html>