1 /* 2 * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 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 name="channels"></a> 32 * 33 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions"> 34 * <tr><th align="left">Channels</th><th align="left">Description</th></tr> 35 * <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td> 36 * <td>A nexus for I/O operations</td></tr> 37 * <tr><td valign=top><tt> <i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td> 38 * <td>Can read into a buffer</td></tr> 39 * <tr><td valign=top><tt> <i>{@link java.nio.channels.ScatteringByteChannel} </i></tt></td> 40 * <td>Can read into a sequence of buffers</td></tr> 41 * <tr><td valign=top><tt> <i>{@link java.nio.channels.WritableByteChannel}</i></tt></td> 42 * <td>Can write from a buffer</td></tr> 43 * <tr><td valign=top><tt> <i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td> 44 * <td>Can write from a sequence of buffers</td></tr> 45 * <tr><td valign=top><tt> <i>{@link java.nio.channels.ByteChannel}</i></tt></td> 46 * <td>Can read/write to/from a buffer</td></tr> 47 * <tr><td valign=top><tt> <i>{@link java.nio.channels.SeekableByteChannel}</i></tt></td> 48 * <td>A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes</td></tr> 49 * <tr><td valign=top><tt> <i>{@link java.nio.channels.AsynchronousChannel}</i></tt></td> 50 * <td>Supports asynchronous I/O operations.</td></tr> 51 * <tr><td valign=top><tt> <i>{@link java.nio.channels.AsynchronousByteChannel}</i></tt></td> 52 * <td>Can read and write bytes asynchronously</td></tr> 53 * <tr><td valign=top><tt> <i>{@link java.nio.channels.NetworkChannel}</i></tt></td> 54 * <td>A channel to a network socket</td></tr> 55 * <tr><td valign=top><tt> <i>{@link java.nio.channels.MulticastChannel}</i></tt></td> 56 * <td>Can join Internet Protocol (IP) multicast groups</td></tr> 57 * <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td> 58 * <td>Utility methods for channel/stream interoperation</td></tr> 59 * </table></blockquote> 60 * 61 * <p> A <i>channel</i> represents an open connection to an entity such as a 62 * hardware device, a file, a network socket, or a program component that is 63 * capable of performing one or more distinct I/O operations, for example reading 64 * or writing. As specified in the {@link java.nio.channels.Channel} interface, 65 * channels are either open or closed, and they are both <i>asynchronously 66 * closeable</i> and <i>interruptible</i>. 67 * 68 * <p> The {@link java.nio.channels.Channel} interface is extended by several 69 * other interfaces. 70 * 71 * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a 72 * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes 73 * from the channel into a buffer; similarly, the {@link 74 * java.nio.channels.WritableByteChannel} interface specifies a {@link 75 * java.nio.channels.WritableByteChannel#write write} method that writes bytes 76 * from a buffer to the channel. The {@link java.nio.channels.ByteChannel} 77 * interface unifies these two interfaces for the common case of channels that can 78 * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel} 79 * interface extends the {@code ByteChannel} interface with methods to {@link 80 * java.nio.channels.SeekableByteChannel#position() query} and {@link 81 * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's 82 * current position, and its {@link java.nio.channels.SeekableByteChannel#size 83 * size}. 84 * 85 * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link 86 * java.nio.channels.GatheringByteChannel} interfaces extend the {@link 87 * java.nio.channels.ReadableByteChannel} and {@link 88 * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link 89 * java.nio.channels.ScatteringByteChannel#read read} and {@link 90 * java.nio.channels.GatheringByteChannel#write write} methods that take a 91 * sequence of buffers rather than a single buffer. 92 * 93 * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods 94 * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket, 95 * obtain the address to which the socket is bound, and methods to {@link 96 * java.nio.channels.NetworkChannel#getOption get} and {@link 97 * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link 98 * java.nio.channels.MulticastChannel} interface specifies methods to join 99 * Internet Protocol (IP) multicast groups. 100 * 101 * <p> The {@link java.nio.channels.Channels} utility class defines static methods 102 * that support the interoperation of the stream classes of the <tt>{@link 103 * java.io}</tt> package with the channel classes of this package. An appropriate 104 * channel can be constructed from an {@link java.io.InputStream} or an {@link 105 * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an 106 * {@link java.io.OutputStream} can be constructed from a channel. A {@link 107 * java.io.Reader} can be constructed that uses a given charset to decode bytes 108 * from a given readable byte channel, and conversely a {@link java.io.Writer} can 109 * be constructed that uses a given charset to encode characters into bytes and 110 * write them to a given writable byte channel. 111 * 112 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions"> 113 * <tr><th align="left">File channels</th><th align="left">Description</th></tr> 114 * <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td> 115 * <td>Reads, writes, maps, and manipulates files</td></tr> 116 * <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td> 117 * <td>A lock on a (region of a) file</td></tr> 118 * <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer} </tt></td> 119 * <td>A direct byte buffer mapped to a region of a file</td></tr> 120 * </table></blockquote> 121 * 122 * <p> The {@link java.nio.channels.FileChannel} class supports the usual 123 * operations of reading bytes from, and writing bytes to, a channel connected to 124 * a file, as well as those of querying and modifying the current file position 125 * and truncating the file to a specific size. It defines methods for acquiring 126 * locks on the whole file or on a specific region of a file; these methods return 127 * instances of the {@link java.nio.channels.FileLock} class. Finally, it defines 128 * methods for forcing updates to the file to be written to the storage device that 129 * contains it, for efficiently transferring bytes between the file and other 130 * channels, and for mapping a region of the file directly into memory. 131 * 132 * <p> A {@code FileChannel} is created by invoking one of its static {@link 133 * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code 134 * getChannel} method of a {@link java.io.FileInputStream}, {@link 135 * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a 136 * file channel connected to the same underlying file as the <tt>{@link java.io}</tt> 137 * class. 138 * 139 * <a name="multiplex"></a> 140 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions"> 141 * <tr><th align="left">Multiplexed, non-blocking I/O</th><th align="left"><p>Description</th></tr> 142 * <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td> 143 * <td>A channel that can be multiplexed</td></tr> 144 * <tr><td valign=top><tt> {@link java.nio.channels.DatagramChannel}</tt></td> 145 * <td>A channel to a datagram-oriented socket</td></tr> 146 * <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SinkChannel}</tt></td> 147 * <td>The write end of a pipe</td></tr> 148 * <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SourceChannel}</tt></td> 149 * <td>The read end of a pipe</td></tr> 150 * <tr><td valign=top><tt> {@link java.nio.channels.ServerSocketChannel} </tt></td> 151 * <td>A channel to a stream-oriented listening socket</td></tr> 152 * <tr><td valign=top><tt> {@link java.nio.channels.SocketChannel}</tt></td> 153 * <td>A channel for a stream-oriented connecting socket</td></tr> 154 * <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td> 155 * <td>A multiplexor of selectable channels</td></tr> 156 * <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td> 157 * <td>A token representing the registration <br> of a channel 158 * with a selector</td></tr> 159 * <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td> 160 * <td>Two channels that form a unidirectional pipe</td></tr> 161 * </table></blockquote> 162 * 163 * <p> Multiplexed, non-blocking I/O, which is much more scalable than 164 * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable 165 * channels</i>, and <i>selection keys</i>. 166 * 167 * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a 168 * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are 169 * a special type of channel that can be put into <a 170 * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform 171 * multiplexed I/O operations, one or more selectable channels are first created, 172 * put into non-blocking mode, and {@link 173 * java.nio.channels.SelectableChannel#register <i>registered</i>} 174 * with a selector. Registering a channel specifies the set of I/O operations 175 * that will be tested for readiness by the selector, and returns a <a 176 * href="SelectionKey.html"><i>selection key</i></a> that represents the 177 * registration. 178 * 179 * <p> Once some channels have been registered with a selector, a <a 180 * href="Selector.html#selop"><i>selection operation</i></a> can be performed in 181 * order to discover which channels, if any, have become ready to perform one or 182 * more of the operations in which interest was previously declared. If a channel 183 * is ready then the key returned when it was registered will be added to the 184 * selector's <i>selected-key set</i>. The key set, and the keys within it, can 185 * be examined in order to determine the operations for which each channel is 186 * ready. From each key one can retrieve the corresponding channel in order to 187 * perform whatever I/O operations are required. 188 * 189 * <p> That a selection key indicates that its channel is ready for some operation 190 * is a hint, but not a guarantee, that such an operation can be performed by a 191 * thread without causing the thread to block. It is imperative that code that 192 * performs multiplexed I/O be written so as to ignore these hints when they prove 193 * to be incorrect. 194 * 195 * <p> This package defines selectable-channel classes corresponding to the {@link 196 * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link 197 * java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package. 198 * Minor changes to these classes have been made in order to support sockets that 199 * are associated with channels. This package also defines a simple class that 200 * implements unidirectional pipes. In all cases, a new selectable channel is 201 * created by invoking the static <tt>open</tt> method of the corresponding class. 202 * If a channel needs an associated socket then a socket will be created as a side 203 * effect of this operation. 204 * 205 * <p> The implementation of selectors, selectable channels, and selection keys 206 * can be replaced by "plugging in" an alternative definition or instance of the 207 * {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link 208 * java.nio.channels.spi}</tt> package. It is not expected that many developers 209 * will actually make use of this facility; it is provided primarily so that 210 * sophisticated users can take advantage of operating-system-specific 211 * I/O-multiplexing mechanisms when very high performance is required. 212 * 213 * <p> Much of the bookkeeping and synchronization required to implement the 214 * multiplexed-I/O abstractions is performed by the {@link 215 * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link 216 * java.nio.channels.spi.AbstractSelectableChannel}, {@link 217 * java.nio.channels.spi.AbstractSelectionKey}, and {@link 218 * java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link 219 * java.nio.channels.spi}</tt> package. When defining a custom selector provider, 220 * only the {@link java.nio.channels.spi.AbstractSelector} and {@link 221 * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed 222 * directly; custom channel classes should extend the appropriate {@link 223 * java.nio.channels.SelectableChannel} subclasses defined in this package. 224 * 225 * <a name="async"></a> 226 * 227 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists asynchronous channels and their descriptions"> 228 * <tr><th align="left">Asynchronous I/O</th><th align="left">Description</th></tr> 229 * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousFileChannel}</tt></td> 230 * <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr> 231 * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousSocketChannel}</tt></td> 232 * <td>An asynchronous channel to a stream-oriented connecting socket</td></tr> 233 * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousServerSocketChannel} </tt></td> 234 * <td>An asynchronous channel to a stream-oriented listening socket</td></tr> 235 * <tr><td valign=top><tt>{@link java.nio.channels.CompletionHandler}</tt></td> 236 * <td>A handler for consuming the result of an asynchronous operation</td></tr> 237 * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousChannelGroup}</tt></td> 238 * <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr> 239 * </table></blockquote> 240 * 241 * <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a 242 * special type of channel capable of asynchronous I/O operations. Asynchronous 243 * channels are non-blocking and define methods to initiate asynchronous 244 * operations, returning a {@link java.util.concurrent.Future} representing the 245 * pending result of each operation. The {@code Future} can be used to poll or 246 * wait for the result of the operation. Asynchronous I/O operations can also 247 * specify a {@link java.nio.channels.CompletionHandler} to invoke when the 248 * operation completes. A completion handler is user provided code that is executed 249 * to consume the result of I/O operation. 250 * 251 * <p> This package defines asynchronous-channel classes that are connected to 252 * a stream-oriented connecting or listening socket, or a datagram-oriented socket. 253 * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class 254 * for asynchronous reading, writing, and manipulating a file. As with the {@link 255 * java.nio.channels.FileChannel} it supports operations to truncate the file 256 * to a specific size, force updates to the file to be written to the storage 257 * device, or acquire locks on the whole file or on a specific region of the file. 258 * Unlike the {@code FileChannel} it does not define methods for mapping a 259 * region of the file directly into memory. Where memory mapped I/O is required, 260 * then a {@code FileChannel} can be used. 261 * 262 * <p> Asynchronous channels are bound to an asynchronous channel group for the 263 * purpose of resource sharing. A group has an associated {@link 264 * java.util.concurrent.ExecutorService} to which tasks are submitted to handle 265 * I/O events and dispatch to completion handlers that consume the result of 266 * asynchronous operations performed on channels in the group. The group can 267 * optionally be specified when creating the channel or the channel can be bound 268 * to a <em>default group</em>. Sophisticated users may wish to create their 269 * own asynchronous channel groups or configure the {@code ExecutorService} 270 * that will be used for the default group. 271 * 272 * <p> As with selectors, the implementation of asynchronous channels can be 273 * replaced by "plugging in" an alternative definition or instance of the {@link 274 * java.nio.channels.spi.AsynchronousChannelProvider} class defined in the 275 * <tt>{@link java.nio.channels.spi}</tt> package. It is not expected that many 276 * developers will actually make use of this facility; it is provided primarily 277 * so that sophisticated users can take advantage of operating-system-specific 278 * asynchronous I/O mechanisms when very high performance is required. 279 * 280 * <hr width="80%"> 281 * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor 282 * or method in any class or interface in this package will cause a {@link 283 * java.lang.NullPointerException NullPointerException} to be thrown. 284 * 285 * @since 1.4 286 * @author Mark Reinhold 287 * @author JSR-51 Expert Group 288 */ 289 290 package java.nio.channels; 291