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