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