13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * Defines channels, which represent connections to entities that are capable of 28 * performing I/O operations, such as files and sockets; defines selectors, for 29 * multiplexed, non-blocking I/O operations. 30 * 31 * <a id="channels"></a> 32 * 33 * <blockquote><table class="borderless"> 34 * <caption style="display:none">Lists channels and their descriptions</caption> 35 * <tr><th style="text-align:left">Channels</th> 36 * <th style="text-align:left">Description</th></tr> 37 * <tr><td style="vertical-align:top"><i>{@link java.nio.channels.Channel}</i></td> 38 * <td>A nexus for I/O operations</td></tr> 39 * <tr><td style="vertical-align:top"> 40 * <i>{@link java.nio.channels.ReadableByteChannel}</i></td> 41 * <td>Can read into a buffer</td></tr> 42 * <tr><td style="vertical-align:top"> 43 * <i>{@link java.nio.channels.ScatteringByteChannel} </i></td> 44 * <td>Can read into a sequence of buffers</td></tr> 45 * <tr><td style="vertical-align:top"> 46 * <i>{@link java.nio.channels.WritableByteChannel}</i></td> 47 * <td>Can write from a buffer</td></tr> 48 * <tr><td style="vertical-align:top"> 49 * <i>{@link java.nio.channels.GatheringByteChannel}</i></td> 50 * <td>Can write from a sequence of buffers</td></tr> 51 * <tr><td style="vertical-align:top"> 52 * <i>{@link java.nio.channels.ByteChannel}</i></td> 53 * <td>Can read/write to/from a buffer</td></tr> 54 * <tr><td style="vertical-align:top"> 55 * <i>{@link java.nio.channels.SeekableByteChannel}</i></td> 56 * <td>A {@code ByteChannel} connected to an entity that contains a variable-length 57 * sequence of bytes</td></tr> 58 * <tr><td style="vertical-align:top"> 59 * <i>{@link java.nio.channels.AsynchronousChannel}</i></td> 60 * <td>Supports asynchronous I/O operations.</td></tr> 61 * <tr><td style="vertical-align:top"> 62 * <i>{@link java.nio.channels.AsynchronousByteChannel}</i></td> 63 * <td>Can read and write bytes asynchronously</td></tr> 64 * <tr><td style="vertical-align:top"> 65 * <i>{@link java.nio.channels.NetworkChannel}</i></td> 66 * <td>A channel to a network socket</td></tr> 67 * <tr><td style="vertical-align:top"> 68 * <i>{@link java.nio.channels.MulticastChannel}</i></td> 69 * <td>Can join Internet Protocol (IP) multicast groups</td></tr> 70 * <tr><td style="vertical-align:top">{@link java.nio.channels.Channels}</td> 71 * <td>Utility methods for channel/stream interoperation</td></tr> 72 * </table></blockquote> 73 * 74 * <p> A <i>channel</i> represents an open connection to an entity such as a 75 * hardware device, a file, a network socket, or a program component that is 76 * capable of performing one or more distinct I/O operations, for example reading 77 * or writing. As specified in the {@link java.nio.channels.Channel} interface, 78 * channels are either open or closed, and they are both <i>asynchronously 79 * closeable</i> and <i>interruptible</i>. 80 * 81 * <p> The {@link java.nio.channels.Channel} interface is extended by several 82 * other interfaces. 83 * 84 * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a 85 * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes 86 * from the channel into a buffer; similarly, the {@link 87 * java.nio.channels.WritableByteChannel} interface specifies a {@link 88 * java.nio.channels.WritableByteChannel#write write} method that writes bytes 89 * from a buffer to the channel. The {@link java.nio.channels.ByteChannel} 90 * interface unifies these two interfaces for the common case of channels that can 91 * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel} 92 * interface extends the {@code ByteChannel} interface with methods to {@link 105 * 106 * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods 107 * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket, 108 * obtain the address to which the socket is bound, and methods to {@link 109 * java.nio.channels.NetworkChannel#getOption get} and {@link 110 * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link 111 * java.nio.channels.MulticastChannel} interface specifies methods to join 112 * Internet Protocol (IP) multicast groups. 113 * 114 * <p> The {@link java.nio.channels.Channels} utility class defines static methods 115 * that support the interoperation of the stream classes of the {@link 116 * java.io} package with the channel classes of this package. An appropriate 117 * channel can be constructed from an {@link java.io.InputStream} or an {@link 118 * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an 119 * {@link java.io.OutputStream} can be constructed from a channel. A {@link 120 * java.io.Reader} can be constructed that uses a given charset to decode bytes 121 * from a given readable byte channel, and conversely a {@link java.io.Writer} can 122 * be constructed that uses a given charset to encode characters into bytes and 123 * write them to a given writable byte channel. 124 * 125 * <blockquote><table class="borderless"> 126 * <caption style="display:none"> 127 * Lists file channels and their descriptions</caption> 128 * <tr><th style="text-align:left">File channels</th> 129 * <th style="text-align:left">Description</th></tr> 130 * <tr><td style="vertical-align:top"> 131 * {@link java.nio.channels.FileChannel}</td> 132 * <td>Reads, writes, maps, and manipulates files</td></tr> 133 * <tr><td style="vertical-align:top"> 134 * {@link java.nio.channels.FileLock}</td> 135 * <td>A lock on a (region of a) file</td></tr> 136 * <tr><td style="vertical-align:top"> 137 * {@link java.nio.MappedByteBuffer} </td> 138 * <td>A direct byte buffer mapped to a region of a file</td></tr> 139 * </table></blockquote> 140 * 141 * <p> The {@link java.nio.channels.FileChannel} class supports the usual 142 * operations of reading bytes from, and writing bytes to, a channel connected to 143 * a file, as well as those of querying and modifying the current file position 144 * and truncating the file to a specific size. It defines methods for acquiring 145 * locks on the whole file or on a specific region of a file; these methods return 146 * instances of the {@link java.nio.channels.FileLock} class. Finally, it defines 147 * methods for forcing updates to the file to be written to the storage device that 148 * contains it, for efficiently transferring bytes between the file and other 149 * channels, and for mapping a region of the file directly into memory. 150 * 151 * <p> A {@code FileChannel} is created by invoking one of its static {@link 152 * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code 153 * getChannel} method of a {@link java.io.FileInputStream}, {@link 154 * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a 155 * file channel connected to the same underlying file as the {@link java.io} 156 * class. 157 * 158 * <a id="multiplex"></a> 159 * <blockquote><table class="borderless"> 160 * <caption style="display:none"> 161 * Lists multiplexed, non-blocking channels and their descriptions</caption> 162 * <tr><th style="text-align:left">Multiplexed, non-blocking I/O</th> 163 * <th style="text-align:left">Description</th></tr> 164 * <tr><td style="vertical-align:top">{@link java.nio.channels.SelectableChannel}</td> 165 * <td>A channel that can be multiplexed</td></tr> 166 * <tr><td style="vertical-align:top"> 167 * {@link java.nio.channels.DatagramChannel}</td> 168 * <td>A channel to a datagram-oriented socket</td></tr> 169 * <tr><td style="vertical-align:top"> 170 * {@link java.nio.channels.Pipe.SinkChannel}</td> 171 * <td>The write end of a pipe</td></tr> 172 * <tr><td style="vertical-align:top"> 173 * {@link java.nio.channels.Pipe.SourceChannel}</td> 174 * <td>The read end of a pipe</td></tr> 175 * <tr><td style="vertical-align:top"> 176 * {@link java.nio.channels.ServerSocketChannel} </td> 177 * <td>A channel to a stream-oriented listening socket</td></tr> 178 * <tr><td style="vertical-align:top"> 179 * {@link java.nio.channels.SocketChannel}</td> 180 * <td>A channel for a stream-oriented connecting socket</td></tr> 181 * <tr><td style="vertical-align:top">{@link java.nio.channels.Selector}</td> 182 * <td>A multiplexor of selectable channels</td></tr> 183 * <tr><td style="vertical-align:top">{@link java.nio.channels.SelectionKey}</td> 184 * <td>A token representing the registration <br> of a channel 185 * with a selector</td></tr> 186 * <tr><td style="vertical-align:top">{@link java.nio.channels.Pipe}</td> 187 * <td>Two channels that form a unidirectional pipe</td></tr> 188 * </table></blockquote> 189 * 190 * <p> Multiplexed, non-blocking I/O, which is much more scalable than 191 * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable 192 * channels</i>, and <i>selection keys</i>. 193 * 194 * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a 195 * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are 196 * a special type of channel that can be put into <a 197 * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform 198 * multiplexed I/O operations, one or more selectable channels are first created, 199 * put into non-blocking mode, and {@link 200 * java.nio.channels.SelectableChannel#register <i>registered</i>} 201 * with a selector. Registering a channel specifies the set of I/O operations 202 * that will be tested for readiness by the selector, and returns a <a 203 * href="SelectionKey.html"><i>selection key</i></a> that represents the 204 * registration. 205 * 206 * <p> Once some channels have been registered with a selector, a <a 207 * href="Selector.html#selop"><i>selection operation</i></a> can be performed in 208 * order to discover which channels, if any, have become ready to perform one or 234 * {@link java.nio.channels.spi.SelectorProvider} class defined in the {@link 235 * java.nio.channels.spi} package. It is not expected that many developers 236 * will actually make use of this facility; it is provided primarily so that 237 * sophisticated users can take advantage of operating-system-specific 238 * I/O-multiplexing mechanisms when very high performance is required. 239 * 240 * <p> Much of the bookkeeping and synchronization required to implement the 241 * multiplexed-I/O abstractions is performed by the {@link 242 * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link 243 * java.nio.channels.spi.AbstractSelectableChannel}, {@link 244 * java.nio.channels.spi.AbstractSelectionKey}, and {@link 245 * java.nio.channels.spi.AbstractSelector} classes in the {@link 246 * java.nio.channels.spi} package. When defining a custom selector provider, 247 * only the {@link java.nio.channels.spi.AbstractSelector} and {@link 248 * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed 249 * directly; custom channel classes should extend the appropriate {@link 250 * java.nio.channels.SelectableChannel} subclasses defined in this package. 251 * 252 * <a id="async"></a> 253 * 254 * <blockquote><table class="borderless"> 255 * <caption style="display:none"> 256 * Lists asynchronous channels and their descriptions</caption> 257 * <tr><th style="text-align:left"> 258 * Asynchronous I/O</th><th style="text-align:left">Description</th></tr> 259 * <tr><td style="vertical-align:top"> 260 * {@link java.nio.channels.AsynchronousFileChannel}</td> 261 * <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr> 262 * <tr><td style="vertical-align:top"> 263 * {@link java.nio.channels.AsynchronousSocketChannel}</td> 264 * <td>An asynchronous channel to a stream-oriented connecting socket</td></tr> 265 * <tr><td style="vertical-align:top"> 266 * {@link java.nio.channels.AsynchronousServerSocketChannel} </td> 267 * <td>An asynchronous channel to a stream-oriented listening socket</td></tr> 268 * <tr><td style="vertical-align:top"> 269 * {@link java.nio.channels.CompletionHandler}</td> 270 * <td>A handler for consuming the result of an asynchronous operation</td></tr> 271 * <tr><td style="vertical-align:top"> 272 * {@link java.nio.channels.AsynchronousChannelGroup}</td> 273 * <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr> 274 * </table></blockquote> 275 * 276 * <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a 277 * special type of channel capable of asynchronous I/O operations. Asynchronous 278 * channels are non-blocking and define methods to initiate asynchronous 279 * operations, returning a {@link java.util.concurrent.Future} representing the 280 * pending result of each operation. The {@code Future} can be used to poll or 281 * wait for the result of the operation. Asynchronous I/O operations can also 282 * specify a {@link java.nio.channels.CompletionHandler} to invoke when the 283 * operation completes. A completion handler is user provided code that is executed 284 * to consume the result of I/O operation. 285 * 286 * <p> This package defines asynchronous-channel classes that are connected to 287 * a stream-oriented connecting or listening socket, or a datagram-oriented socket. 288 * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class 289 * for asynchronous reading, writing, and manipulating a file. As with the {@link 290 * java.nio.channels.FileChannel} it supports operations to truncate the file 291 * to a specific size, force updates to the file to be written to the storage 292 * device, or acquire locks on the whole file or on a specific region of the file. 293 * Unlike the {@code FileChannel} it does not define methods for mapping a 294 * region of the file directly into memory. Where memory mapped I/O is required, | 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * Defines channels, which represent connections to entities that are capable of 28 * performing I/O operations, such as files and sockets; defines selectors, for 29 * multiplexed, non-blocking I/O operations. 30 * 31 * <a id="channels"></a> 32 * 33 * <table class="striped" style="text-align:left; margin-left:2em"> 34 * <caption style="display:none">Lists channels and their descriptions</caption> 35 * <thead> 36 * <tr><th scope="col">Channels</th> 37 * <th scope="col">Description</th></tr> 38 * </thead> 39 * <tbody> 40 * <tr><th scope="row"><i>{@link java.nio.channels.Channel}</i></th> 41 * <td>A nexus for I/O operations</td></tr> 42 * <tr><th scope="row"> 43 * <span style="padding-left:1em"><i>{@link java.nio.channels.ReadableByteChannel}</i></span></th> 44 * <td>Can read into a buffer</td></tr> 45 * <tr><th scope="row"> 46 * <span style="padding-left:2em"><i>{@link java.nio.channels.ScatteringByteChannel}</i></span></th> 47 * <td>Can read into a sequence of buffers</td></tr> 48 * <tr><th scope="row"> 49 * <span style="padding-left:1em"><i>{@link java.nio.channels.WritableByteChannel}</i></span></th> 50 * <td>Can write from a buffer</td></tr> 51 * <tr><th scope="row"> 52 * <span style="padding-left:2em"><i>{@link java.nio.channels.GatheringByteChannel}</i></span></th> 53 * <td>Can write from a sequence of buffers</td></tr> 54 * <tr><th scope="row"> 55 * <span style="padding-left:1em"><i>{@link java.nio.channels.ByteChannel}</i></span></th> 56 * <td>Can read/write to/from a buffer</td></tr> 57 * <tr><th scope="row"> 58 * <span style="padding-left:2em"><i>{@link java.nio.channels.SeekableByteChannel}</i></span></th> 59 * <td>A {@code ByteChannel} connected to an entity that contains a variable-length 60 * sequence of bytes</td></tr> 61 * <tr><th scope="row"> 62 * <span style="padding-left:1em"><i>{@link java.nio.channels.AsynchronousChannel}</i></span></th> 63 * <td>Supports asynchronous I/O operations.</td></tr> 64 * <tr><th scope="row"> 65 * <span style="padding-left:2em"><i>{@link java.nio.channels.AsynchronousByteChannel}</i></span></th> 66 * <td>Can read and write bytes asynchronously</td></tr> 67 * <tr><th scope="row"> 68 * <span style="padding-left:1em"><i>{@link java.nio.channels.NetworkChannel}</i></span></th> 69 * <td>A channel to a network socket</td></tr> 70 * <tr><th scope="row"> 71 * <span style="padding-left:2em"><i>{@link java.nio.channels.MulticastChannel}</i></span></th> 72 * <td>Can join Internet Protocol (IP) multicast groups</td></tr> 73 * <tr><th scope="row">{@link java.nio.channels.Channels}</th> 74 * <td>Utility methods for channel/stream interoperation</td></tr> 75 * </tbody> 76 * </table> 77 * 78 * <p> A <i>channel</i> represents an open connection to an entity such as a 79 * hardware device, a file, a network socket, or a program component that is 80 * capable of performing one or more distinct I/O operations, for example reading 81 * or writing. As specified in the {@link java.nio.channels.Channel} interface, 82 * channels are either open or closed, and they are both <i>asynchronously 83 * closeable</i> and <i>interruptible</i>. 84 * 85 * <p> The {@link java.nio.channels.Channel} interface is extended by several 86 * other interfaces. 87 * 88 * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a 89 * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes 90 * from the channel into a buffer; similarly, the {@link 91 * java.nio.channels.WritableByteChannel} interface specifies a {@link 92 * java.nio.channels.WritableByteChannel#write write} method that writes bytes 93 * from a buffer to the channel. The {@link java.nio.channels.ByteChannel} 94 * interface unifies these two interfaces for the common case of channels that can 95 * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel} 96 * interface extends the {@code ByteChannel} interface with methods to {@link 109 * 110 * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods 111 * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket, 112 * obtain the address to which the socket is bound, and methods to {@link 113 * java.nio.channels.NetworkChannel#getOption get} and {@link 114 * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link 115 * java.nio.channels.MulticastChannel} interface specifies methods to join 116 * Internet Protocol (IP) multicast groups. 117 * 118 * <p> The {@link java.nio.channels.Channels} utility class defines static methods 119 * that support the interoperation of the stream classes of the {@link 120 * java.io} package with the channel classes of this package. An appropriate 121 * channel can be constructed from an {@link java.io.InputStream} or an {@link 122 * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an 123 * {@link java.io.OutputStream} can be constructed from a channel. A {@link 124 * java.io.Reader} can be constructed that uses a given charset to decode bytes 125 * from a given readable byte channel, and conversely a {@link java.io.Writer} can 126 * be constructed that uses a given charset to encode characters into bytes and 127 * write them to a given writable byte channel. 128 * 129 * <table class="striped" style="margin-left:2em; text-align:left"> 130 * <caption style="display:none"> 131 * Lists file channels and their descriptions</caption> 132 * <thead> 133 * <tr><th scope="col">File channels</th> 134 * <th scope="col">Description</th></tr> 135 * </thead> 136 * <tbody> 137 * <tr><th scope="row"> 138 * {@link java.nio.channels.FileChannel}</th> 139 * <td>Reads, writes, maps, and manipulates files</td></tr> 140 * <tr><th scope="row"> 141 * {@link java.nio.channels.FileLock}</th> 142 * <td>A lock on a (region of a) file</td></tr> 143 * <tr><th scope="row"> 144 * {@link java.nio.MappedByteBuffer}</th> 145 * <td>A direct byte buffer mapped to a region of a file</td></tr> 146 * </tbody> 147 * </table> 148 * 149 * <p> The {@link java.nio.channels.FileChannel} class supports the usual 150 * operations of reading bytes from, and writing bytes to, a channel connected to 151 * a file, as well as those of querying and modifying the current file position 152 * and truncating the file to a specific size. It defines methods for acquiring 153 * locks on the whole file or on a specific region of a file; these methods return 154 * instances of the {@link java.nio.channels.FileLock} class. Finally, it defines 155 * methods for forcing updates to the file to be written to the storage device that 156 * contains it, for efficiently transferring bytes between the file and other 157 * channels, and for mapping a region of the file directly into memory. 158 * 159 * <p> A {@code FileChannel} is created by invoking one of its static {@link 160 * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code 161 * getChannel} method of a {@link java.io.FileInputStream}, {@link 162 * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a 163 * file channel connected to the same underlying file as the {@link java.io} 164 * class. 165 * 166 * <a id="multiplex"></a> 167 * <table class="striped" style="margin-left:2em; text-align:left"> 168 * <caption style="display:none"> 169 * Lists multiplexed, non-blocking channels and their descriptions</caption> 170 * <thead> 171 * <tr><th scope="col">Multiplexed, non-blocking I/O</th> 172 * <th scope="col">Description</th></tr> 173 * </thead> 174 * <tbody> 175 * <tr><th scope="row">{@link java.nio.channels.SelectableChannel}</th> 176 * <td>A channel that can be multiplexed</td></tr> 177 * <tr><th scope="row"> 178 * <span style="padding-left:2em">{@link java.nio.channels.DatagramChannel}</span></th> 179 * <td>A channel to a datagram-oriented socket</td></tr> 180 * <tr><th scope="row"> 181 * <span style="padding-left:2em">{@link java.nio.channels.Pipe.SinkChannel}</span></th> 182 * <td>The write end of a pipe</td></tr> 183 * <tr><th scope="row"> 184 * <span style="padding-left:2em">{@link java.nio.channels.Pipe.SourceChannel}</span></th> 185 * <td>The read end of a pipe</td></tr> 186 * <tr><th scope="row"> 187 * <span style="padding-left:2em">{@link java.nio.channels.ServerSocketChannel}</span></th> 188 * <td>A channel to a stream-oriented listening socket</td></tr> 189 * <tr><th scope="row"> 190 * <span style="padding-left:2em">{@link java.nio.channels.SocketChannel}</span></th> 191 * <td>A channel for a stream-oriented connecting socket</td></tr> 192 * <tr><th scope="row">{@link java.nio.channels.Selector}</th> 193 * <td>A multiplexor of selectable channels</td></tr> 194 * <tr><th scope="row">{@link java.nio.channels.SelectionKey}</th> 195 * <td>A token representing the registration of a channel 196 * with a selector</td></tr> 197 * <tr><th scope="row">{@link java.nio.channels.Pipe}</th> 198 * <td>Two channels that form a unidirectional pipe</td></tr> 199 * </tbody> 200 * </table> 201 * 202 * <p> Multiplexed, non-blocking I/O, which is much more scalable than 203 * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable 204 * channels</i>, and <i>selection keys</i>. 205 * 206 * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a 207 * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are 208 * a special type of channel that can be put into <a 209 * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform 210 * multiplexed I/O operations, one or more selectable channels are first created, 211 * put into non-blocking mode, and {@link 212 * java.nio.channels.SelectableChannel#register <i>registered</i>} 213 * with a selector. Registering a channel specifies the set of I/O operations 214 * that will be tested for readiness by the selector, and returns a <a 215 * href="SelectionKey.html"><i>selection key</i></a> that represents the 216 * registration. 217 * 218 * <p> Once some channels have been registered with a selector, a <a 219 * href="Selector.html#selop"><i>selection operation</i></a> can be performed in 220 * order to discover which channels, if any, have become ready to perform one or 246 * {@link java.nio.channels.spi.SelectorProvider} class defined in the {@link 247 * java.nio.channels.spi} package. It is not expected that many developers 248 * will actually make use of this facility; it is provided primarily so that 249 * sophisticated users can take advantage of operating-system-specific 250 * I/O-multiplexing mechanisms when very high performance is required. 251 * 252 * <p> Much of the bookkeeping and synchronization required to implement the 253 * multiplexed-I/O abstractions is performed by the {@link 254 * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link 255 * java.nio.channels.spi.AbstractSelectableChannel}, {@link 256 * java.nio.channels.spi.AbstractSelectionKey}, and {@link 257 * java.nio.channels.spi.AbstractSelector} classes in the {@link 258 * java.nio.channels.spi} package. When defining a custom selector provider, 259 * only the {@link java.nio.channels.spi.AbstractSelector} and {@link 260 * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed 261 * directly; custom channel classes should extend the appropriate {@link 262 * java.nio.channels.SelectableChannel} subclasses defined in this package. 263 * 264 * <a id="async"></a> 265 * 266 * <table class="striped" style="padding-left:2em; text-align:left"> 267 * <caption style="display:none"> 268 * Lists asynchronous channels and their descriptions</caption> 269 * <thead> 270 * <tr><th scope="col">Asynchronous I/O</th> 271 * <th scope="col">Description</th></tr> 272 * </thead> 273 * <tbody> 274 * <tr><th scope="row"> 275 * {@link java.nio.channels.AsynchronousFileChannel}</th> 276 * <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr> 277 * <tr><th scope="row"> 278 * {@link java.nio.channels.AsynchronousSocketChannel}</th> 279 * <td>An asynchronous channel to a stream-oriented connecting socket</td></tr> 280 * <tr><th scope="row"> 281 * {@link java.nio.channels.AsynchronousServerSocketChannel}</th> 282 * <td>An asynchronous channel to a stream-oriented listening socket</td></tr> 283 * <tr><th scope="row"> 284 * {@link java.nio.channels.CompletionHandler}</th> 285 * <td>A handler for consuming the result of an asynchronous operation</td></tr> 286 * <tr><th scope="row"> 287 * {@link java.nio.channels.AsynchronousChannelGroup}</th> 288 * <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr> 289 * </tbody> 290 * </table> 291 * 292 * <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a 293 * special type of channel capable of asynchronous I/O operations. Asynchronous 294 * channels are non-blocking and define methods to initiate asynchronous 295 * operations, returning a {@link java.util.concurrent.Future} representing the 296 * pending result of each operation. The {@code Future} can be used to poll or 297 * wait for the result of the operation. Asynchronous I/O operations can also 298 * specify a {@link java.nio.channels.CompletionHandler} to invoke when the 299 * operation completes. A completion handler is user provided code that is executed 300 * to consume the result of I/O operation. 301 * 302 * <p> This package defines asynchronous-channel classes that are connected to 303 * a stream-oriented connecting or listening socket, or a datagram-oriented socket. 304 * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class 305 * for asynchronous reading, writing, and manipulating a file. As with the {@link 306 * java.nio.channels.FileChannel} it supports operations to truncate the file 307 * to a specific size, force updates to the file to be written to the storage 308 * device, or acquire locks on the whole file or on a specific region of the file. 309 * Unlike the {@code FileChannel} it does not define methods for mapping a 310 * region of the file directly into memory. Where memory mapped I/O is required, |