| blob | 27d924c6e35fd5dd3e56a3cf21047242de266921 |
1 /*
2 * Copyright (c) 2001, 2010, 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 */
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><p align="left">Channels</p></th><th><p align="left">Description</p></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.NetworkChannel}</i></tt></td>
50 * <td>A channel to a network socket</td></tr>
51 * <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td>
52 * <td>Utility methods for channel/stream interoperation</td></tr>
53 * </table></blockquote>
54 *
55 * <p> A <i>channel</i> represents an open connection to an entity such as a
56 * hardware device, a file, a network socket, or a program component that is
57 * capable of performing one or more distinct I/O operations, for example reading
58 * or writing. As specified in the {@link java.nio.channels.Channel} interface,
59 * channels are either open or closed, and they are both <i>asynchronously
60 * closeable</i> and <i>interruptible</i>.
61 *
62 * <p> The {@link java.nio.channels.Channel} interface is extended by several
63 * other interfaces.
64 *
65 * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a
66 * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes
67 * from the channel into a buffer; similarly, the {@link
68 * java.nio.channels.WritableByteChannel} interface specifies a {@link
69 * java.nio.channels.WritableByteChannel#write write} method that writes bytes
70 * from a buffer to the channel. The {@link java.nio.channels.ByteChannel}
71 * interface unifies these two interfaces for the common case of channels that can
72 * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel}
73 * interface extends the {@code ByteChannel} interface with methods to {@link
74 * java.nio.channels.SeekableByteChannel#position() query} and {@link
75 * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's
76 * current position, and its {@link java.nio.channels.SeekableByteChannel#size
77 * size}.
78 *
79 * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
80 * java.nio.channels.GatheringByteChannel} interfaces extend the {@link
81 * java.nio.channels.ReadableByteChannel} and {@link
82 * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
83 * java.nio.channels.ScatteringByteChannel#read read} and {@link
84 * java.nio.channels.GatheringByteChannel#write write} methods that take a
85 * sequence of buffers rather than a single buffer.
86 *
87 * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods
88 * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,
89 * obtain the address to which the socket is bound, and methods to {@link
90 * java.nio.channels.NetworkChannel#getOption get} and {@link
91 * java.nio.channels.NetworkChannel#setOption set} socket options.
92 *
93 * <p> The {@link java.nio.channels.Channels} utility class defines static methods
94 * that support the interoperation of the stream classes of the <tt>{@link
95 * java.io}</tt> package with the channel classes of this package. An appropriate
96 * channel can be constructed from an {@link java.io.InputStream} or an {@link
97 * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an
98 * {@link java.io.OutputStream} can be constructed from a channel. A {@link
99 * java.io.Reader} can be constructed that uses a given charset to decode bytes
100 * from a given readable byte channel, and conversely a {@link java.io.Writer} can
101 * be constructed that uses a given charset to encode characters into bytes and
102 * write them to a given writable byte channel.
103 *
104 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">
105 * <tr><th><p align="left">File channels</p></th><th><p align="left">Description</p></th></tr>
106 * <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>
107 * <td>Reads, writes, maps, and manipulates files</td></tr>
108 * <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>
109 * <td>A lock on a (region of a) file</td></tr>
110 * <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer} </tt></td>
111 * <td>A direct byte buffer mapped to a region of a file</td></tr>
112 * </table></blockquote>
113 *
114 * <p> The {@link java.nio.channels.FileChannel} class supports the usual
115 * operations of reading bytes from, and writing bytes to, a channel connected to
116 * a file, as well as those of querying and modifying the current file position
117 * and truncating the file to a specific size. It defines methods for acquiring
118 * locks on the whole file or on a specific region of a file; these methods return
119 * instances of the {@link java.nio.channels.FileLock} class. Finally, it defines
120 * methods for forcing updates to the file to be written to the storage device that
121 * contains it, for efficiently transferring bytes between the file and other
122 * channels, and for mapping a region of the file directly into memory.
123 *
124 * <p> A {@code FileChannel} is created by invoking the {@code
125 * getChannel} method of a {@link java.io.FileInputStream}, {@link
126 * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a
127 * file channel connected to the same underlying file as the <tt>{@link java.io}</tt>
128 * class.
129 *
130 * <a name="multiplex"></a>
131 * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">
132 * <tr><th><p align="left">Multiplexed, non-blocking I/O</p></th><th><p align="left">Description</p></th></tr>
133 * <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>
134 * <td>A channel that can be multiplexed</td></tr>
135 * <tr><td valign=top><tt> {@link java.nio.channels.DatagramChannel}</tt></td>
136 * <td>A channel to a datagram-oriented socket</td></tr>
137 * <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SinkChannel}</tt></td>
138 * <td>The write end of a pipe</td></tr>
139 * <tr><td valign=top><tt> {@link java.nio.channels.Pipe.SourceChannel}</tt></td>
140 * <td>The read end of a pipe</td></tr>
141 * <tr><td valign=top><tt> {@link java.nio.channels.ServerSocketChannel} </tt></td>
142 * <td>A channel to a stream-oriented listening socket</td></tr>
143 * <tr><td valign=top><tt> {@link java.nio.channels.SocketChannel}</tt></td>
144 * <td>A channel for a stream-oriented connecting socket</td></tr>
145 * <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td>
146 * <td>A multiplexor of selectable channels</td></tr>
147 * <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td>
148 * <td>A token representing the registration <br> of a channel
149 * with a selector</td></tr>
150 * <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>
151 * <td>Two channels that form a unidirectional pipe</td></tr>
152 * </table></blockquote>
153 *
154 * <p> Multiplexed, non-blocking I/O, which is much more scalable than
155 * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable
156 * channels</i>, and <i>selection keys</i>.
157 *
158 * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a
159 * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are
160 * a special type of channel that can be put into <a
161 * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform
162 * multiplexed I/O operations, one or more selectable channels are first created,
163 * put into non-blocking mode, and {@link
164 * java.nio.channels.SelectableChannel#register <i>registered</i>}
165 * with a selector. Registering a channel specifies the set of I/O operations
166 * that will be tested for readiness by the selector, and returns a <a
167 * href="SelectionKey.html"><i>selection key</i></a> that represents the
168 * registration.
169 *
170 * <p> Once some channels have been registered with a selector, a <a
171 * href="Selector.html#selop"><i>selection operation</i></a> can be performed in
172 * order to discover which channels, if any, have become ready to perform one or
173 * more of the operations in which interest was previously declared. If a channel
174 * is ready then the key returned when it was registered will be added to the
175 * selector's <i>selected-key set</i>. The key set, and the keys within it, can
176 * be examined in order to determine the operations for which each channel is
177 * ready. From each key one can retrieve the corresponding channel in order to
178 * perform whatever I/O operations are required.
179 *
180 * <p> That a selection key indicates that its channel is ready for some operation
181 * is a hint, but not a guarantee, that such an operation can be performed by a
182 * thread without causing the thread to block. It is imperative that code that
183 * performs multiplexed I/O be written so as to ignore these hints when they prove
184 * to be incorrect.
185 *
186 * <p> This package defines selectable-channel classes corresponding to the {@link
187 * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link
188 * java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package.
189 * Minor changes to these classes have been made in order to support sockets that
190 * are associated with channels. This package also defines a simple class that
191 * implements unidirectional pipes. In all cases, a new selectable channel is
192 * created by invoking the static <tt>open</tt> method of the corresponding class.
193 * If a channel needs an associated socket then a socket will be created as a side
194 * effect of this operation.
195 *
196 * <p> The implementation of selectors, selectable channels, and selection keys
197 * can be replaced by "plugging in" an alternative definition or instance of the
198 * {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link
199 * java.nio.channels.spi}</tt> package. It is not expected that many developers
200 * will actually make use of this facility; it is provided primarily so that
201 * sophisticated users can take advantage of operating-system-specific
202 * I/O-multiplexing mechanisms when very high performance is required.
203 *
204 * <p> Much of the bookkeeping and synchronization required to implement the
205 * multiplexed-I/O abstractions is performed by the {@link
206 * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link
207 * java.nio.channels.spi.AbstractSelectableChannel}, {@link
208 * java.nio.channels.spi.AbstractSelectionKey}, and {@link
209 * java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link
210 * java.nio.channels.spi}</tt> package. When defining a custom selector provider,
211 * only the {@link java.nio.channels.spi.AbstractSelector} and {@link
212 * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed
213 * directly; custom channel classes should extend the appropriate {@link
214 * java.nio.channels.SelectableChannel} subclasses defined in this package.
215 *
216 *
217 * <hr width="80%">
218 * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
219 * or method in any class or interface in this package will cause a {@link
220 * java.lang.NullPointerException NullPointerException} to be thrown.
221 *
222 * @since 1.4
223 * @author Mark Reinhold
224 * @author JSR-51 Expert Group
225 */