Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / java / nio / channels / package.html
blob: 151378f78fd1d20bd794a2d2f3f683c0ea838818 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]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
30Defines channels, which represent connections to entities that are capable of
31performing I/O operations, such as files and sockets; defines selectors, for
32multiplexed, 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>&nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>
42 <td>Can read into a buffer</td></tr>
43 <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.ScatteringByteChannel}&nbsp;&nbsp;</i></tt></td>
44 <td>Can read into a sequence of&nbsp;buffers</td></tr>
45 <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.WritableByteChannel}</i></tt></td>
46 <td>Can write from a buffer</td></tr>
47 <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td>
48 <td>Can write from a sequence of&nbsp;buffers</td></tr>
49 <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ByteChannel}</i></tt></td>
50 <td>Can read/write to/from a&nbsp;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
56hardware device, a file, a network socket, or a program component that is
57capable of performing one or more distinct I/O operations, for example reading
58or writing. As specified in the {@link java.nio.channels.Channel} interface,
59channels are either open or closed, and they are both <i>asynchronously
60closeable</i> and <i>interruptible</i>.
61
62<p> The {@link java.nio.channels.Channel} interface is extended by several
63other 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
67from the channel into a buffer; similarly, the {@link
68java.nio.channels.WritableByteChannel} interface specifies a {@link
69java.nio.channels.WritableByteChannel#write write} method that writes bytes
70from a buffer to the channel. The {@link java.nio.channels.ByteChannel}
71interface unifies these two interfaces for the common case of channels that can
72both read and write bytes.
73
74<p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
75java.nio.channels.GatheringByteChannel} interfaces extend the {@link
76java.nio.channels.ReadableByteChannel} and {@link
77java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
78java.nio.channels.ScatteringByteChannel#read read} and {@link
79java.nio.channels.GatheringByteChannel#write write} methods that take a
80sequence of buffers rather than a single buffer.
81
82<p> The {@link java.nio.channels.Channels} utility class defines static methods
83that support the interoperation of the stream classes of the <tt>{@link
84java.io}</tt> package with the channel classes of this package. An appropriate
85channel can be constructed from an {@link java.io.InputStream} or an {@link
86java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an
87{@link java.io.OutputStream} can be constructed from a channel. A {@link
88java.io.Reader} can be constructed that uses a given charset to decode bytes
89from a given readable byte channel, and conversely a {@link java.io.Writer} can
90be constructed that uses a given charset to encode characters into bytes and
91write 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}&nbsp;&nbsp;</tt></td>
101 <td>A direct byte buffer mapped to a region of a&nbsp;file</td></tr>
102</table></blockquote>
103
104<p> The {@link java.nio.channels.FileChannel} class supports the usual
105operations of reading bytes from, and writing bytes to, a channel connected to
106a file, as well as those of querying and modifying the current file position
107and truncating the file to a specific size. It defines methods for acquiring
108locks on the whole file or on a specific region of a file; these methods return
109instances of the {@link java.nio.channels.FileLock} class. Finally, it defines
110methods for forcing updates to the file to be written to the storage device that
111contains it, for efficiently transferring bytes between the file and other
112channels, and for mapping a region of the file directly into memory. This last
113operation creates an instance of the {@link java.nio.MappedByteBuffer}
114class, which extends the {@link java.nio.ByteBuffer} class with several
115file-related operations.
116
117<p> A <tt>getChannel</tt> method has been added to each of the {@link
118java.io.FileInputStream#getChannel FileInputStream}, {@link
119java.io.FileOutputStream#getChannel FileOutputStream}, and {@link
120java.io.RandomAccessFile#getChannel RandomAccessFile} classes of the <tt>{@link
121java.io java.io}</tt> package. Invoking this method upon an instance of one of
122these 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>&nbsp;&nbsp;{@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>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SinkChannel}</tt></td>
134 <td>The write end of a pipe</td></tr>
135 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SourceChannel}</tt></td>
136 <td>The read end of a pipe</td></tr>
137 <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.ServerSocketChannel}&nbsp;&nbsp;</tt></td>
138 <td>A channel for a {@link java.net.ServerSocket java.net.ServerSocket}</td></tr>
139 <tr><td valign=top><tt>&nbsp;&nbsp;{@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&nbsp;a&nbsp;selector</td></tr>
146 <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>
147 <td>Two channels that form a unidirectional&nbsp;pipe</td></tr>
148</table></blockquote>
149
150<p> Multiplexed, non-blocking I/O, which is much more scalable than
151thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable
152channels</i>, and <i>selection keys</i>.
153
154<p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a
155href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are
156a special type of channel that can be put into <a
157href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform
158multiplexed I/O operations, one or more selectable channels are first created,
159put into non-blocking mode, and {@link
160java.nio.channels.SelectableChannel#register </code><i>registered</i><code>}
161with a selector. Registering a channel specifies the set of I/O operations
162that will be tested for readiness by the selector, and returns a <a
163href="SelectionKey.html"><i>selection key</i></a> that represents the
164registration.
165
166<p> Once some channels have been registered with a selector, a <a
167href="Selector.html#selop"><i>selection operation</i></a> can be performed in
168order to discover which channels, if any, have become ready to perform one or
169more of the operations in which interest was previously declared. If a channel
170is ready then the key returned when it was registered will be added to the
171selector's <i>selected-key set</i>. The key set, and the keys within it, can
172be examined in order to determine the operations for which each channel is
173ready. From each key one can retrieve the corresponding channel in order to
174perform whatever I/O operations are required.
175
176<p> That a selection key indicates that its channel is ready for some operation
177is a hint, but not a guarantee, that such an operation can be performed by a
178thread without causing the thread to block. It is imperative that code that
179performs multiplexed I/O be written so as to ignore these hints when they prove
180to be incorrect.
181
182<p> This package defines selectable-channel classes corresponding to the {@link
183java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link
184java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package.
185Minor changes to these classes have been made in order to support sockets that
186are associated with channels. This package also defines a simple class that
187implements unidirectional pipes. In all cases, a new selectable channel is
188created by invoking the static <tt>open</tt> method of the corresponding class.
189If a channel needs an associated socket then a socket will be created as a side
190effect of this operation.
191
192<p> The implementation of selectors, selectable channels, and selection keys
193can 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
195java.nio.channels.spi}</tt> package. It is not expected that many developers
196will actually make use of this facility; it is provided primarily so that
197sophisticated users can take advantage of operating-system-specific
198I/O-multiplexing mechanisms when very high performance is required.
199
200<p> Much of the bookkeeping and synchronization required to implement the
201multiplexed-I/O abstractions is performed by the {@link
202java.nio.channels.spi.AbstractInterruptibleChannel}, {@link
203java.nio.channels.spi.AbstractSelectableChannel}, {@link
204java.nio.channels.spi.AbstractSelectionKey}, and {@link
205java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link
206java.nio.channels.spi}</tt> package. When defining a custom selector provider,
207only the {@link java.nio.channels.spi.AbstractSelector} and {@link
208java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed
209directly; custom channel classes should extend the appropriate {@link
210java.nio.channels.SelectableChannel} subclasses defined in this package.
211
212<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
213or method in any class or interface in this package will cause a {@link
214java.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>