1/*
2 * Copyright (c) 2001, 2017, 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 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
97 * java.nio.channels.SeekableByteChannel#position() query} and {@link
98 * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's
99 * current position, and its {@link java.nio.channels.SeekableByteChannel#size
100 * size}.
101 *
102 * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
103 * java.nio.channels.GatheringByteChannel} interfaces extend the {@link
104 * java.nio.channels.ReadableByteChannel} and {@link
105 * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
106 * java.nio.channels.ScatteringByteChannel#read read} and {@link
107 * java.nio.channels.GatheringByteChannel#write write} methods that take a
108 * sequence of buffers rather than a single buffer.
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
221 * more of the operations in which interest was previously declared.  If a channel
222 * is ready then the key returned when it was registered will be added to the
223 * selector's <i>selected-key set</i>.  The key set, and the keys within it, can
224 * be examined in order to determine the operations for which each channel is
225 * ready.  From each key one can retrieve the corresponding channel in order to
226 * perform whatever I/O operations are required.
227 *
228 * <p> That a selection key indicates that its channel is ready for some operation
229 * is a hint, but not a guarantee, that such an operation can be performed by a
230 * thread without causing the thread to block.  It is imperative that code that
231 * performs multiplexed I/O be written so as to ignore these hints when they prove
232 * to be incorrect.
233 *
234 * <p> This package defines selectable-channel classes corresponding to the {@link
235 * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link
236 * java.net.Socket} classes defined in the {@link java.net} package.
237 * Minor changes to these classes have been made in order to support sockets that
238 * are associated with channels.  This package also defines a simple class that
239 * implements unidirectional pipes.  In all cases, a new selectable channel is
240 * created by invoking the static {@code open} method of the corresponding class.
241 * If a channel needs an associated socket then a socket will be created as a side
242 * effect of this operation.
243 *
244 * <p> The implementation of selectors, selectable channels, and selection keys
245 * can be replaced by "plugging in" an alternative definition or instance of the
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,
311 * then a {@code FileChannel} can be used.
312 *
313 * <p> Asynchronous channels are bound to an asynchronous channel group for the
314 * purpose of resource sharing. A group has an associated {@link
315 * java.util.concurrent.ExecutorService} to which tasks are submitted to handle
316 * I/O events and dispatch to completion handlers that consume the result of
317 * asynchronous operations performed on channels in the group. The group can
318 * optionally be specified when creating the channel or the channel can be bound
319 * to a <em>default group</em>. Sophisticated users may wish to create their
320 * own asynchronous channel groups or configure the {@code ExecutorService}
321 * that will be used for the default group.
322 *
323 * <p> As with selectors, the implementation of asynchronous channels can be
324 * replaced by "plugging in" an alternative definition or instance of the {@link
325 * java.nio.channels.spi.AsynchronousChannelProvider} class defined in the
326 * {@link java.nio.channels.spi} package.  It is not expected that many
327 * developers will actually make use of this facility; it is provided primarily
328 * so that sophisticated users can take advantage of operating-system-specific
329 * asynchronous I/O mechanisms when very high performance is required.
330 *
331 * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
332 * or method in any class or interface in this package will cause a {@link
333 * java.lang.NullPointerException NullPointerException} to be thrown.
334 *
335 * @since 1.4
336 * @author Mark Reinhold
337 * @author JSR-51 Expert Group
338 */
339
340package java.nio.channels;
341