25 |
25 |
26 package java.nio.channels; |
26 package java.nio.channels; |
27 |
27 |
28 import java.io.IOException; |
28 import java.io.IOException; |
29 import java.net.Socket; |
29 import java.net.Socket; |
|
30 import java.net.SocketOption; |
30 import java.net.SocketAddress; |
31 import java.net.SocketAddress; |
31 import java.nio.ByteBuffer; |
32 import java.nio.ByteBuffer; |
32 import java.nio.channels.spi.*; |
33 import java.nio.channels.spi.*; |
33 |
34 |
34 |
|
35 /** |
35 /** |
36 * A selectable channel for stream-oriented connecting sockets. |
36 * A selectable channel for stream-oriented connecting sockets. |
37 * |
37 * |
38 * <p> Socket channels are not a complete abstraction of connecting network |
|
39 * sockets. Binding, shutdown, and the manipulation of socket options must be |
|
40 * done through an associated {@link java.net.Socket} object obtained by |
|
41 * invoking the {@link #socket() socket} method. It is not possible to create |
|
42 * a channel for an arbitrary, pre-existing socket, nor is it possible to |
|
43 * specify the {@link java.net.SocketImpl} object to be used by a socket |
|
44 * associated with a socket channel. |
|
45 * |
|
46 * <p> A socket channel is created by invoking one of the {@link #open open} |
38 * <p> A socket channel is created by invoking one of the {@link #open open} |
47 * methods of this class. A newly-created socket channel is open but not yet |
39 * methods of this class. It is not possible to create a channel for an arbitrary, |
|
40 * pre-existing socket. A newly-created socket channel is open but not yet |
48 * connected. An attempt to invoke an I/O operation upon an unconnected |
41 * connected. An attempt to invoke an I/O operation upon an unconnected |
49 * channel will cause a {@link NotYetConnectedException} to be thrown. A |
42 * channel will cause a {@link NotYetConnectedException} to be thrown. A |
50 * socket channel can be connected by invoking its {@link #connect connect} |
43 * socket channel can be connected by invoking its {@link #connect connect} |
51 * method; once connected, a socket channel remains connected until it is |
44 * method; once connected, a socket channel remains connected until it is |
52 * closed. Whether or not a socket channel is connected may be determined by |
45 * closed. Whether or not a socket channel is connected may be determined by |
56 * channel may be created and the process of establishing the link to the |
49 * channel may be created and the process of establishing the link to the |
57 * remote socket may be initiated via the {@link #connect connect} method for |
50 * remote socket may be initiated via the {@link #connect connect} method for |
58 * later completion by the {@link #finishConnect finishConnect} method. |
51 * later completion by the {@link #finishConnect finishConnect} method. |
59 * Whether or not a connection operation is in progress may be determined by |
52 * Whether or not a connection operation is in progress may be determined by |
60 * invoking the {@link #isConnectionPending isConnectionPending} method. |
53 * invoking the {@link #isConnectionPending isConnectionPending} method. |
61 * |
|
62 * <p> The input and output sides of a socket channel may independently be |
|
63 * <i>shut down</i> without actually closing the channel. Shutting down the |
|
64 * input side of a channel by invoking the {@link java.net.Socket#shutdownInput |
|
65 * shutdownInput} method of an associated socket object will cause further |
|
66 * reads on the channel to return <tt>-1</tt>, the end-of-stream indication. |
|
67 * Shutting down the output side of the channel by invoking the {@link |
|
68 * java.net.Socket#shutdownOutput shutdownOutput} method of an associated |
|
69 * socket object will cause further writes on the channel to throw a {@link |
|
70 * ClosedChannelException}. |
|
71 * |
54 * |
72 * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar |
55 * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar |
73 * to the asynchronous close operation specified in the {@link Channel} class. |
56 * to the asynchronous close operation specified in the {@link Channel} class. |
74 * If the input side of a socket is shut down by one thread while another |
57 * If the input side of a socket is shut down by one thread while another |
75 * thread is blocked in a read operation on the socket's channel, then the read |
58 * thread is blocked in a read operation on the socket's channel, then the read |
77 * will return <tt>-1</tt>. If the output side of a socket is shut down by one |
60 * will return <tt>-1</tt>. If the output side of a socket is shut down by one |
78 * thread while another thread is blocked in a write operation on the socket's |
61 * thread while another thread is blocked in a write operation on the socket's |
79 * channel, then the blocked thread will receive an {@link |
62 * channel, then the blocked thread will receive an {@link |
80 * AsynchronousCloseException}. |
63 * AsynchronousCloseException}. |
81 * |
64 * |
|
65 * <p> Socket options are configured using the {@link #setOption(SocketOption,Object) |
|
66 * setOption} method. Socket channels support the following options: |
|
67 * <blockquote> |
|
68 * <table border> |
|
69 * <tr> |
|
70 * <th>Option Name</th> |
|
71 * <th>Description</th> |
|
72 * </tr> |
|
73 * <tr> |
|
74 * <td> {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF} </td> |
|
75 * <td> The size of the socket send buffer </td> |
|
76 * </tr> |
|
77 * <tr> |
|
78 * <td> {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF} </td> |
|
79 * <td> The size of the socket receive buffer </td> |
|
80 * </tr> |
|
81 * <tr> |
|
82 * <td> {@link java.net.StandardSocketOption#SO_KEEPALIVE SO_KEEPALIVE} </td> |
|
83 * <td> Keep connection alive </td> |
|
84 * </tr> |
|
85 * <tr> |
|
86 * <td> {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} </td> |
|
87 * <td> Re-use address </td> |
|
88 * </tr> |
|
89 * <tr> |
|
90 * <td> {@link java.net.StandardSocketOption#SO_LINGER SO_LINGER} </td> |
|
91 * <td> Linger on close if data is present (when configured in blocking mode |
|
92 * only) </td> |
|
93 * </tr> |
|
94 * <tr> |
|
95 * <td> {@link java.net.StandardSocketOption#TCP_NODELAY TCP_NODELAY} </td> |
|
96 * <td> Disable the Nagle algorithm </td> |
|
97 * </tr> |
|
98 * </table> |
|
99 * </blockquote> |
|
100 * Additional (implementation specific) options may also be supported. |
|
101 * |
82 * <p> Socket channels are safe for use by multiple concurrent threads. They |
102 * <p> Socket channels are safe for use by multiple concurrent threads. They |
83 * support concurrent reading and writing, though at most one thread may be |
103 * support concurrent reading and writing, though at most one thread may be |
84 * reading and at most one thread may be writing at any given time. The {@link |
104 * reading and at most one thread may be writing at any given time. The {@link |
85 * #connect connect} and {@link #finishConnect finishConnect} methods are |
105 * #connect connect} and {@link #finishConnect finishConnect} methods are |
86 * mutually synchronized against each other, and an attempt to initiate a read |
106 * mutually synchronized against each other, and an attempt to initiate a read |
87 * or write operation while an invocation of one of these methods is in |
107 * or write operation while an invocation of one of these methods is in |
88 * progress will block until that invocation is complete. </p> |
108 * progress will block until that invocation is complete. </p> |
89 * |
109 * |
90 * |
|
91 * @author Mark Reinhold |
110 * @author Mark Reinhold |
92 * @author JSR-51 Expert Group |
111 * @author JSR-51 Expert Group |
93 * @since 1.4 |
112 * @since 1.4 |
94 */ |
113 */ |
95 |
114 |
96 public abstract class SocketChannel |
115 public abstract class SocketChannel |
97 extends AbstractSelectableChannel |
116 extends AbstractSelectableChannel |
98 implements ByteChannel, ScatteringByteChannel, GatheringByteChannel |
117 implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, NetworkChannel |
99 { |
118 { |
100 |
119 |
101 /** |
120 /** |
102 * Initializes a new instance of this class. |
121 * Initializes a new instance of this class. |
103 */ |
122 */ |
190 |
209 |
191 |
210 |
192 // -- Socket-specific operations -- |
211 // -- Socket-specific operations -- |
193 |
212 |
194 /** |
213 /** |
|
214 * @throws ConnectionPendingException |
|
215 * If a non-blocking connection operation is already in progress on |
|
216 * this channel |
|
217 * @throws AlreadyBoundException {@inheritDoc} |
|
218 * @throws UnsupportedAddressTypeException {@inheritDoc} |
|
219 * @throws ClosedChannelException {@inheritDoc} |
|
220 * @throws IOException {@inheritDoc} |
|
221 * |
|
222 * @since 1.7 |
|
223 */ |
|
224 @Override |
|
225 public abstract SocketChannel bind(SocketAddress local) |
|
226 throws IOException; |
|
227 |
|
228 /** |
|
229 * @throws IllegalArgumentException {@inheritDoc} |
|
230 * @throws ClosedChannelException {@inheritDoc} |
|
231 * @throws IOException {@inheritDoc} |
|
232 * |
|
233 * @since 1.7 |
|
234 */ |
|
235 @Override |
|
236 public abstract <T> SocketChannel setOption(SocketOption<T> name, T value) |
|
237 throws IOException; |
|
238 |
|
239 /** |
|
240 * Shutdown the connection for reading without closing the channel. |
|
241 * |
|
242 * <p> Once shutdown for reading then further reads on the channel will |
|
243 * return {@code -1}, the end-of-stream indication. If the input side of the |
|
244 * connection is already shutdown then invoking this method has no effect. |
|
245 * |
|
246 * @return The channel |
|
247 * |
|
248 * @throws NotYetConnectedException |
|
249 * If this channel is not yet connected |
|
250 * @throws ClosedChannelException |
|
251 * If this channel is closed |
|
252 * @throws IOException |
|
253 * If some other I/O error occurs |
|
254 * |
|
255 * @since 1.7 |
|
256 */ |
|
257 public abstract SocketChannel shutdownInput() throws IOException; |
|
258 |
|
259 /** |
|
260 * Shutdown the connection for writing without closing the channel. |
|
261 * |
|
262 * <p> Once shutdown for writing then further attempts to write to the |
|
263 * channel will throw {@link ClosedChannelException}. If the output side of |
|
264 * the connection is already shutdown then invoking this method has no |
|
265 * effect. |
|
266 * |
|
267 * @return The channel |
|
268 * |
|
269 * @throws NotYetConnectedException |
|
270 * If this channel is not yet connected |
|
271 * @throws ClosedChannelException |
|
272 * If this channel is closed |
|
273 * @throws IOException |
|
274 * If some other I/O error occurs |
|
275 * |
|
276 * @since 1.7 |
|
277 */ |
|
278 public abstract SocketChannel shutdownOutput() throws IOException; |
|
279 |
|
280 /** |
195 * Retrieves a socket associated with this channel. |
281 * Retrieves a socket associated with this channel. |
196 * |
282 * |
197 * <p> The returned object will not declare any public methods that are not |
283 * <p> The returned object will not declare any public methods that are not |
198 * declared in the {@link java.net.Socket} class. </p> |
284 * declared in the {@link java.net.Socket} class. </p> |
199 * |
285 * |
200 * @return A socket associated with this channel |
286 * @return A socket associated with this channel |
201 */ |
287 */ |
202 public abstract Socket socket(); |
288 public abstract Socket socket(); |
203 |
289 |
204 /** |
290 /** |
205 * Tells whether or not this channel's network socket is connected. </p> |
291 * Tells whether or not this channel's network socket is connected. |
206 * |
292 * |
207 * @return <tt>true</tt> if, and only if, this channel's network socket |
293 * @return <tt>true</tt> if, and only if, this channel's network socket |
208 * is connected |
294 * is {@link #isOpen open} and connected |
209 */ |
295 */ |
210 public abstract boolean isConnected(); |
296 public abstract boolean isConnected(); |
211 |
297 |
212 /** |
298 /** |
213 * Tells whether or not a connection operation is in progress on this |
299 * Tells whether or not a connection operation is in progress on this |
337 * @throws IOException |
423 * @throws IOException |
338 * If some other I/O error occurs |
424 * If some other I/O error occurs |
339 */ |
425 */ |
340 public abstract boolean finishConnect() throws IOException; |
426 public abstract boolean finishConnect() throws IOException; |
341 |
427 |
|
428 /** |
|
429 * Returns the remote address to which this channel's socket is connected. |
|
430 * |
|
431 * <p> Where the channel is bound and connected to an Internet Protocol |
|
432 * socket address then the return value from this method is of type {@link |
|
433 * java.net.InetSocketAddress}. |
|
434 * |
|
435 * @return The remote address; {@code null} if the channel is not {@link |
|
436 * #isOpen open} or the channel's socket is not connected |
|
437 * |
|
438 * @throws IOException |
|
439 * If an I/O error occurs |
|
440 * |
|
441 * @since 1.7 |
|
442 */ |
|
443 public abstract SocketAddress getConnectedAddress() throws IOException; |
342 |
444 |
343 // -- ByteChannel operations -- |
445 // -- ByteChannel operations -- |
344 |
446 |
345 /** |
447 /** |
346 * @throws NotYetConnectedException |
448 * @throws NotYetConnectedException |