J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2000-2001 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 | package java.nio.channels; |
| 27 | |
| 28 | import java.io.IOException; |
| 29 | import java.net.Socket; |
| 30 | import java.net.SocketAddress; |
| 31 | import java.nio.ByteBuffer; |
| 32 | import java.nio.channels.spi.*; |
| 33 | |
| 34 | |
| 35 | /** |
| 36 | * A selectable channel for stream-oriented connecting sockets. |
| 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} |
| 47 | * methods of this class. A newly-created socket channel is open but not yet |
| 48 | * connected. An attempt to invoke an I/O operation upon an unconnected |
| 49 | * channel will cause a {@link NotYetConnectedException} to be thrown. A |
| 50 | * socket channel can be connected by invoking its {@link #connect connect} |
| 51 | * 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 |
| 53 | * invoking its {@link #isConnected isConnected} method. |
| 54 | * |
| 55 | * <p> Socket channels support <i>non-blocking connection:</i> A socket |
| 56 | * 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 |
| 58 | * later completion by the {@link #finishConnect finishConnect} method. |
| 59 | * Whether or not a connection operation is in progress may be determined by |
| 60 | * 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 | * |
| 72 | * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar |
| 73 | * 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 |
| 75 | * thread is blocked in a read operation on the socket's channel, then the read |
| 76 | * operation in the blocked thread will complete without reading any bytes and |
| 77 | * 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 |
| 79 | * channel, then the blocked thread will receive an {@link |
| 80 | * AsynchronousCloseException}. |
| 81 | * |
| 82 | * <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 |
| 84 | * reading and at most one thread may be writing at any given time. The {@link |
| 85 | * #connect connect} and {@link #finishConnect finishConnect} methods are |
| 86 | * 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 |
| 88 | * progress will block until that invocation is complete. </p> |
| 89 | * |
| 90 | * |
| 91 | * @author Mark Reinhold |
| 92 | * @author JSR-51 Expert Group |
| 93 | * @since 1.4 |
| 94 | */ |
| 95 | |
| 96 | public abstract class SocketChannel |
| 97 | extends AbstractSelectableChannel |
| 98 | implements ByteChannel, ScatteringByteChannel, GatheringByteChannel |
| 99 | { |
| 100 | |
| 101 | /** |
| 102 | * Initializes a new instance of this class. |
| 103 | */ |
| 104 | protected SocketChannel(SelectorProvider provider) { |
| 105 | super(provider); |
| 106 | } |
| 107 | |
| 108 | /** |
| 109 | * Opens a socket channel. |
| 110 | * |
| 111 | * <p> The new channel is created by invoking the {@link |
| 112 | * java.nio.channels.spi.SelectorProvider#openSocketChannel |
| 113 | * openSocketChannel} method of the system-wide default {@link |
| 114 | * java.nio.channels.spi.SelectorProvider} object. </p> |
| 115 | * |
| 116 | * @return A new socket channel |
| 117 | * |
| 118 | * @throws IOException |
| 119 | * If an I/O error occurs |
| 120 | */ |
| 121 | public static SocketChannel open() throws IOException { |
| 122 | return SelectorProvider.provider().openSocketChannel(); |
| 123 | } |
| 124 | |
| 125 | /** |
| 126 | * Opens a socket channel and connects it to a remote address. |
| 127 | * |
| 128 | * <p> This convenience method works as if by invoking the {@link #open()} |
| 129 | * method, invoking the {@link #connect(SocketAddress) connect} method upon |
| 130 | * the resulting socket channel, passing it <tt>remote</tt>, and then |
| 131 | * returning that channel. </p> |
| 132 | * |
| 133 | * @param remote |
| 134 | * The remote address to which the new channel is to be connected |
| 135 | * |
| 136 | * @throws AsynchronousCloseException |
| 137 | * If another thread closes this channel |
| 138 | * while the connect operation is in progress |
| 139 | * |
| 140 | * @throws ClosedByInterruptException |
| 141 | * If another thread interrupts the current thread |
| 142 | * while the connect operation is in progress, thereby |
| 143 | * closing the channel and setting the current thread's |
| 144 | * interrupt status |
| 145 | * |
| 146 | * @throws UnresolvedAddressException |
| 147 | * If the given remote address is not fully resolved |
| 148 | * |
| 149 | * @throws UnsupportedAddressTypeException |
| 150 | * If the type of the given remote address is not supported |
| 151 | * |
| 152 | * @throws SecurityException |
| 153 | * If a security manager has been installed |
| 154 | * and it does not permit access to the given remote endpoint |
| 155 | * |
| 156 | * @throws IOException |
| 157 | * If some other I/O error occurs |
| 158 | */ |
| 159 | public static SocketChannel open(SocketAddress remote) |
| 160 | throws IOException |
| 161 | { |
| 162 | SocketChannel sc = open(); |
| 163 | try { |
| 164 | sc.connect(remote); |
| 165 | } finally { |
| 166 | if (!sc.isConnected()) { |
| 167 | try { sc.close(); } catch (IOException x) { } |
| 168 | } |
| 169 | } |
| 170 | assert sc.isConnected(); |
| 171 | return sc; |
| 172 | } |
| 173 | |
| 174 | /** |
| 175 | * Returns an operation set identifying this channel's supported |
| 176 | * operations. |
| 177 | * |
| 178 | * <p> Socket channels support connecting, reading, and writing, so this |
| 179 | * method returns <tt>(</tt>{@link SelectionKey#OP_CONNECT} |
| 180 | * <tt>|</tt> {@link SelectionKey#OP_READ} <tt>|</tt> {@link |
| 181 | * SelectionKey#OP_WRITE}<tt>)</tt>. </p> |
| 182 | * |
| 183 | * @return The valid-operation set |
| 184 | */ |
| 185 | public final int validOps() { |
| 186 | return (SelectionKey.OP_READ |
| 187 | | SelectionKey.OP_WRITE |
| 188 | | SelectionKey.OP_CONNECT); |
| 189 | } |
| 190 | |
| 191 | |
| 192 | // -- Socket-specific operations -- |
| 193 | |
| 194 | /** |
| 195 | * Retrieves a socket associated with this channel. |
| 196 | * |
| 197 | * <p> The returned object will not declare any public methods that are not |
| 198 | * declared in the {@link java.net.Socket} class. </p> |
| 199 | * |
| 200 | * @return A socket associated with this channel |
| 201 | */ |
| 202 | public abstract Socket socket(); |
| 203 | |
| 204 | /** |
| 205 | * Tells whether or not this channel's network socket is connected. </p> |
| 206 | * |
| 207 | * @return <tt>true</tt> if, and only if, this channel's network socket |
| 208 | * is connected |
| 209 | */ |
| 210 | public abstract boolean isConnected(); |
| 211 | |
| 212 | /** |
| 213 | * Tells whether or not a connection operation is in progress on this |
| 214 | * channel. </p> |
| 215 | * |
| 216 | * @return <tt>true</tt> if, and only if, a connection operation has been |
| 217 | * initiated on this channel but not yet completed by invoking the |
| 218 | * {@link #finishConnect finishConnect} method |
| 219 | */ |
| 220 | public abstract boolean isConnectionPending(); |
| 221 | |
| 222 | /** |
| 223 | * Connects this channel's socket. |
| 224 | * |
| 225 | * <p> If this channel is in non-blocking mode then an invocation of this |
| 226 | * method initiates a non-blocking connection operation. If the connection |
| 227 | * is established immediately, as can happen with a local connection, then |
| 228 | * this method returns <tt>true</tt>. Otherwise this method returns |
| 229 | * <tt>false</tt> and the connection operation must later be completed by |
| 230 | * invoking the {@link #finishConnect finishConnect} method. |
| 231 | * |
| 232 | * <p> If this channel is in blocking mode then an invocation of this |
| 233 | * method will block until the connection is established or an I/O error |
| 234 | * occurs. |
| 235 | * |
| 236 | * <p> This method performs exactly the same security checks as the {@link |
| 237 | * java.net.Socket} class. That is, if a security manager has been |
| 238 | * installed then this method verifies that its {@link |
| 239 | * java.lang.SecurityManager#checkConnect checkConnect} method permits |
| 240 | * connecting to the address and port number of the given remote endpoint. |
| 241 | * |
| 242 | * <p> This method may be invoked at any time. If a read or write |
| 243 | * operation upon this channel is invoked while an invocation of this |
| 244 | * method is in progress then that operation will first block until this |
| 245 | * invocation is complete. If a connection attempt is initiated but fails, |
| 246 | * that is, if an invocation of this method throws a checked exception, |
| 247 | * then the channel will be closed. </p> |
| 248 | * |
| 249 | * @param remote |
| 250 | * The remote address to which this channel is to be connected |
| 251 | * |
| 252 | * @return <tt>true</tt> if a connection was established, |
| 253 | * <tt>false</tt> if this channel is in non-blocking mode |
| 254 | * and the connection operation is in progress |
| 255 | * |
| 256 | * @throws AlreadyConnectedException |
| 257 | * If this channel is already connected |
| 258 | * |
| 259 | * @throws ConnectionPendingException |
| 260 | * If a non-blocking connection operation is already in progress |
| 261 | * on this channel |
| 262 | * |
| 263 | * @throws ClosedChannelException |
| 264 | * If this channel is closed |
| 265 | * |
| 266 | * @throws AsynchronousCloseException |
| 267 | * If another thread closes this channel |
| 268 | * while the connect operation is in progress |
| 269 | * |
| 270 | * @throws ClosedByInterruptException |
| 271 | * If another thread interrupts the current thread |
| 272 | * while the connect operation is in progress, thereby |
| 273 | * closing the channel and setting the current thread's |
| 274 | * interrupt status |
| 275 | * |
| 276 | * @throws UnresolvedAddressException |
| 277 | * If the given remote address is not fully resolved |
| 278 | * |
| 279 | * @throws UnsupportedAddressTypeException |
| 280 | * If the type of the given remote address is not supported |
| 281 | * |
| 282 | * @throws SecurityException |
| 283 | * If a security manager has been installed |
| 284 | * and it does not permit access to the given remote endpoint |
| 285 | * |
| 286 | * @throws IOException |
| 287 | * If some other I/O error occurs |
| 288 | */ |
| 289 | public abstract boolean connect(SocketAddress remote) throws IOException; |
| 290 | |
| 291 | /** |
| 292 | * Finishes the process of connecting a socket channel. |
| 293 | * |
| 294 | * <p> A non-blocking connection operation is initiated by placing a socket |
| 295 | * channel in non-blocking mode and then invoking its {@link #connect |
| 296 | * connect} method. Once the connection is established, or the attempt has |
| 297 | * failed, the socket channel will become connectable and this method may |
| 298 | * be invoked to complete the connection sequence. If the connection |
| 299 | * operation failed then invoking this method will cause an appropriate |
| 300 | * {@link java.io.IOException} to be thrown. |
| 301 | * |
| 302 | * <p> If this channel is already connected then this method will not block |
| 303 | * and will immediately return <tt>true</tt>. If this channel is in |
| 304 | * non-blocking mode then this method will return <tt>false</tt> if the |
| 305 | * connection process is not yet complete. If this channel is in blocking |
| 306 | * mode then this method will block until the connection either completes |
| 307 | * or fails, and will always either return <tt>true</tt> or throw a checked |
| 308 | * exception describing the failure. |
| 309 | * |
| 310 | * <p> This method may be invoked at any time. If a read or write |
| 311 | * operation upon this channel is invoked while an invocation of this |
| 312 | * method is in progress then that operation will first block until this |
| 313 | * invocation is complete. If a connection attempt fails, that is, if an |
| 314 | * invocation of this method throws a checked exception, then the channel |
| 315 | * will be closed. </p> |
| 316 | * |
| 317 | * @return <tt>true</tt> if, and only if, this channel's socket is now |
| 318 | * connected |
| 319 | * |
| 320 | * @throws NoConnectionPendingException |
| 321 | * If this channel is not connected and a connection operation |
| 322 | * has not been initiated |
| 323 | * |
| 324 | * @throws ClosedChannelException |
| 325 | * If this channel is closed |
| 326 | * |
| 327 | * @throws AsynchronousCloseException |
| 328 | * If another thread closes this channel |
| 329 | * while the connect operation is in progress |
| 330 | * |
| 331 | * @throws ClosedByInterruptException |
| 332 | * If another thread interrupts the current thread |
| 333 | * while the connect operation is in progress, thereby |
| 334 | * closing the channel and setting the current thread's |
| 335 | * interrupt status |
| 336 | * |
| 337 | * @throws IOException |
| 338 | * If some other I/O error occurs |
| 339 | */ |
| 340 | public abstract boolean finishConnect() throws IOException; |
| 341 | |
| 342 | |
| 343 | // -- ByteChannel operations -- |
| 344 | |
| 345 | /** |
| 346 | * @throws NotYetConnectedException |
| 347 | * If this channel is not yet connected |
| 348 | */ |
| 349 | public abstract int read(ByteBuffer dst) throws IOException; |
| 350 | |
| 351 | /** |
| 352 | * @throws NotYetConnectedException |
| 353 | * If this channel is not yet connected |
| 354 | */ |
| 355 | public abstract long read(ByteBuffer[] dsts, int offset, int length) |
| 356 | throws IOException; |
| 357 | |
| 358 | /** |
| 359 | * @throws NotYetConnectedException |
| 360 | * If this channel is not yet connected |
| 361 | */ |
| 362 | public final long read(ByteBuffer[] dsts) throws IOException { |
| 363 | return read(dsts, 0, dsts.length); |
| 364 | } |
| 365 | |
| 366 | /** |
| 367 | * @throws NotYetConnectedException |
| 368 | * If this channel is not yet connected |
| 369 | */ |
| 370 | public abstract int write(ByteBuffer src) throws IOException; |
| 371 | |
| 372 | /** |
| 373 | * @throws NotYetConnectedException |
| 374 | * If this channel is not yet connected |
| 375 | */ |
| 376 | public abstract long write(ByteBuffer[] srcs, int offset, int length) |
| 377 | throws IOException; |
| 378 | |
| 379 | /** |
| 380 | * @throws NotYetConnectedException |
| 381 | * If this channel is not yet connected |
| 382 | */ |
| 383 | public final long write(ByteBuffer[] srcs) throws IOException { |
| 384 | return write(srcs, 0, srcs.length); |
| 385 | } |
| 386 | |
| 387 | } |