Showing the changes to java/pkg/java/nio/channels/AsynchronousSocketChannel.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,648 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2007, 2010, Oracle and/or its affiliates. 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. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package java.nio.channels; | ||
| 27 | |||
| 28 | import java.nio.channels.spi.*; | ||
| 29 | import java.util.concurrent.TimeUnit; | ||
| 30 | import java.util.concurrent.Future; | ||
| 31 | import java.io.IOException; | ||
| 32 | import java.net.SocketOption; | ||
| 33 | import java.net.SocketAddress; | ||
| 34 | import java.nio.ByteBuffer; | ||
| 35 | |||
| 36 | /** | ||
| 37 | * An asynchronous channel for stream-oriented connecting sockets. | ||
| 38 | * | ||
| 39 | * <p> Asynchronous socket channels are created in one of two ways. A newly-created | ||
| 40 | * {@code AsynchronousSocketChannel} is created by invoking one of the {@link | ||
| 41 | * #open open} methods defined by this class. A newly-created channel is open but | ||
| 42 | * not yet connected. A connected {@code AsynchronousSocketChannel} is created | ||
| 43 | * when a connection is made to the socket of an {@link AsynchronousServerSocketChannel}. | ||
| 44 | * It is not possible to create an asynchronous socket channel for an arbitrary, | ||
| 45 | * pre-existing {@link java.net.Socket socket}. | ||
| 46 | * | ||
| 47 | * <p> A newly-created channel is connected by invoking its {@link #connect connect} | ||
| 48 | * method; once connected, a channel remains connected until it is closed. Whether | ||
| 49 | * or not a socket channel is connected may be determined by invoking its {@link | ||
| 50 | * #getRemoteAddress getRemoteAddress} method. An attempt to invoke an I/O | ||
| 51 | * operation upon an unconnected channel will cause a {@link NotYetConnectedException} | ||
| 52 | * to be thrown. | ||
| 53 | * | ||
| 54 | * <p> Channels of this type are safe for use by multiple concurrent threads. | ||
| 55 | * They support concurrent reading and writing, though at most one read operation | ||
| 56 | * and one write operation can be outstanding at any time. | ||
| 57 | * If a thread initiates a read operation before a previous read operation has | ||
| 58 | * completed then a {@link ReadPendingException} will be thrown. Similarly, an | ||
| 59 | * attempt to initiate a write operation before a previous write has completed | ||
| 60 | * will throw a {@link WritePendingException}. | ||
| 61 | * | ||
| 62 | * <p> Socket options are configured using the {@link #setOption(SocketOption,Object) | ||
| 63 | * setOption} method. Asynchronous socket channels support the following options: | ||
| 64 | * <blockquote> | ||
| 65 | * <table border> | ||
| 66 | * <tr> | ||
| 67 | * <th>Option Name</th> | ||
| 68 | * <th>Description</th> | ||
| 69 | * </tr> | ||
| 70 | * <tr> | ||
| 71 | * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td> | ||
| 72 | * <td> The size of the socket send buffer </td> | ||
| 73 | * </tr> | ||
| 74 | * <tr> | ||
| 75 | * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td> | ||
| 76 | * <td> The size of the socket receive buffer </td> | ||
| 77 | * </tr> | ||
| 78 | * <tr> | ||
| 79 | * <td> {@link java.net.StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} </td> | ||
| 80 | * <td> Keep connection alive </td> | ||
| 81 | * </tr> | ||
| 82 | * <tr> | ||
| 83 | * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td> | ||
| 84 | * <td> Re-use address </td> | ||
| 85 | * </tr> | ||
| 86 | * <tr> | ||
| 87 | * <td> {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY} </td> | ||
| 88 | * <td> Disable the Nagle algorithm </td> | ||
| 89 | * </tr> | ||
| 90 | * </table> | ||
| 91 | * </blockquote> | ||
| 92 | * Additional (implementation specific) options may also be supported. | ||
| 93 | * | ||
| 94 | * <h4>Timeouts</h4> | ||
| 95 | * | ||
| 96 | * <p> The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read} | ||
| 97 | * and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write} | ||
| 98 | * methods defined by this class allow a timeout to be specified when initiating | ||
| 99 | * a read or write operation. If the timeout elapses before an operation completes | ||
| 100 | * then the operation completes with the exception {@link | ||
| 101 | * InterruptedByTimeoutException}. A timeout may leave the channel, or the | ||
| 102 | * underlying connection, in an inconsistent state. Where the implementation | ||
| 103 | * cannot guarantee that bytes have not been read from the channel then it puts | ||
| 104 | * the channel into an implementation specific <em>error state</em>. A subsequent | ||
| 105 | * attempt to initiate a {@code read} operation causes an unspecified runtime | ||
| 106 | * exception to be thrown. Similarly if a {@code write} operation times out and | ||
| 107 | * the implementation cannot guarantee bytes have not been written to the | ||
| 108 | * channel then further attempts to {@code write} to the channel cause an | ||
| 109 | * unspecified runtime exception to be thrown. When a timeout elapses then the | ||
| 110 | * state of the {@link ByteBuffer}, or the sequence of buffers, for the I/O | ||
| 111 | * operation is not defined. Buffers should be discarded or at least care must | ||
| 112 | * be taken to ensure that the buffers are not accessed while the channel remains | ||
| 113 | * open. All methods that accept timeout parameters treat values less than or | ||
| 114 | * equal to zero to mean that the I/O operation does not timeout. | ||
| 115 | * | ||
| 116 | * @since 1.7 | ||
| 117 | */ | ||
| 118 | |||
| 119 | public abstract class AsynchronousSocketChannel | ||
| 120 | implements AsynchronousByteChannel, NetworkChannel | ||
| 121 | { | ||
| 122 | private final AsynchronousChannelProvider provider; | ||
| 123 | |||
| 124 | /** | ||
| 125 | * Initializes a new instance of this class. | ||
| 126 | */ | ||
| 127 | protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) { | ||
| 128 | this.provider = provider; | ||
| 129 | } | ||
| 130 | |||
| 131 | /** | ||
| 132 | * Returns the provider that created this channel. | ||
| 133 | */ | ||
| 134 | public final AsynchronousChannelProvider provider() { | ||
| 135 | return provider; | ||
| 136 | } | ||
| 137 | |||
| 138 | /** | ||
| 139 | * Opens an asynchronous socket channel. | ||
| 140 | * | ||
| 141 | * <p> The new channel is created by invoking the {@link | ||
| 142 | * AsynchronousChannelProvider#openAsynchronousSocketChannel | ||
| 143 | * openAsynchronousSocketChannel} method on the {@link | ||
| 144 | * AsynchronousChannelProvider} that created the group. If the group parameter | ||
| 145 | * is {@code null} then the resulting channel is created by the system-wide | ||
| 146 | * default provider, and bound to the <em>default group</em>. | ||
| 147 | * | ||
| 148 | * @param group | ||
| 149 | * The group to which the newly constructed channel should be bound, | ||
| 150 | * or {@code null} for the default group | ||
| 151 | * | ||
| 152 | * @return A new asynchronous socket channel | ||
| 153 | * | ||
| 154 | * @throws ShutdownChannelGroupException | ||
| 155 | * If the channel group is shutdown | ||
| 156 | * @throws IOException | ||
| 157 | * If an I/O error occurs | ||
| 158 | */ | ||
| 159 | public static AsynchronousSocketChannel open(AsynchronousChannelGroup group) | ||
| 160 | throws IOException | ||
| 161 | { | ||
| 162 | AsynchronousChannelProvider provider = (group == null) ? | ||
| 163 | AsynchronousChannelProvider.provider() : group.provider(); | ||
| 164 | return provider.openAsynchronousSocketChannel(group); | ||
| 165 | } | ||
| 166 | |||
| 167 | /** | ||
| 168 | * Opens an asynchronous socket channel. | ||
| 169 | * | ||
| 170 | * <p> This method returns an asynchronous socket channel that is bound to | ||
| 171 | * the <em>default group</em>.This method is equivalent to evaluating the | ||
| 172 | * expression: | ||
| 173 | * <blockquote><pre> | ||
| 174 | * open((AsynchronousChannelGroup)null); | ||
| 175 | * </pre></blockquote> | ||
| 176 | * | ||
| 177 | * @return A new asynchronous socket channel | ||
| 178 | * | ||
| 179 | * @throws IOException | ||
| 180 | * If an I/O error occurs | ||
| 181 | */ | ||
| 182 | public static AsynchronousSocketChannel open() | ||
| 183 | throws IOException | ||
| 184 | { | ||
| 185 | return open(null); | ||
| 186 | } | ||
| 187 | |||
| 188 | |||
| 189 | // -- socket options and related -- | ||
| 190 | |||
| 191 | /** | ||
| 192 | * @throws ConnectionPendingException | ||
| 193 | * If a connection operation is already in progress on this channel | ||
| 194 | * @throws AlreadyBoundException {@inheritDoc} | ||
| 195 | * @throws UnsupportedAddressTypeException {@inheritDoc} | ||
| 196 | * @throws ClosedChannelException {@inheritDoc} | ||
| 197 | * @throws IOException {@inheritDoc} | ||
| 198 | */ | ||
| 199 | @Override | ||
| 200 | public abstract AsynchronousSocketChannel bind(SocketAddress local) | ||
| 201 | throws IOException; | ||
| 202 | |||
| 203 | /** | ||
| 204 | * @throws IllegalArgumentException {@inheritDoc} | ||
| 205 | * @throws ClosedChannelException {@inheritDoc} | ||
| 206 | * @throws IOException {@inheritDoc} | ||
| 207 | */ | ||
| 208 | @Override | ||
| 209 | public abstract <T> AsynchronousSocketChannel setOption(SocketOption<T> name, T value) | ||
| 210 | throws IOException; | ||
| 211 | |||
| 212 | /** | ||
| 213 | * Shutdown the connection for reading without closing the channel. | ||
| 214 | * | ||
| 215 | * <p> Once shutdown for reading then further reads on the channel will | ||
| 216 | * return {@code -1}, the end-of-stream indication. If the input side of the | ||
| 217 | * connection is already shutdown then invoking this method has no effect. | ||
| 218 | * The effect on an outstanding read operation is system dependent and | ||
| 219 | * therefore not specified. The effect, if any, when there is data in the | ||
| 220 | * socket receive buffer that has not been read, or data arrives subsequently, | ||
| 221 | * is also system dependent. | ||
| 222 | * | ||
| 223 | * @return The channel | ||
| 224 | * | ||
| 225 | * @throws NotYetConnectedException | ||
| 226 | * If this channel is not yet connected | ||
| 227 | * @throws ClosedChannelException | ||
| 228 | * If this channel is closed | ||
| 229 | * @throws IOException | ||
| 230 | * If some other I/O error occurs | ||
| 231 | */ | ||
| 232 | public abstract AsynchronousSocketChannel shutdownInput() throws IOException; | ||
| 233 | |||
| 234 | /** | ||
| 235 | * Shutdown the connection for writing without closing the channel. | ||
| 236 | * | ||
| 237 | * <p> Once shutdown for writing then further attempts to write to the | ||
| 238 | * channel will throw {@link ClosedChannelException}. If the output side of | ||
| 239 | * the connection is already shutdown then invoking this method has no | ||
| 240 | * effect. The effect on an outstanding write operation is system dependent | ||
| 241 | * and therefore not specified. | ||
| 242 | * | ||
| 243 | * @return The channel | ||
| 244 | * | ||
| 245 | * @throws NotYetConnectedException | ||
| 246 | * If this channel is not yet connected | ||
| 247 | * @throws ClosedChannelException | ||
| 248 | * If this channel is closed | ||
| 249 | * @throws IOException | ||
| 250 | * If some other I/O error occurs | ||
| 251 | */ | ||
| 252 | public abstract AsynchronousSocketChannel shutdownOutput() throws IOException; | ||
| 253 | |||
| 254 | // -- state -- | ||
| 255 | |||
| 256 | /** | ||
| 257 | * Returns the remote address to which this channel's socket is connected. | ||
| 258 | * | ||
| 259 | * <p> Where the channel is bound and connected to an Internet Protocol | ||
| 260 | * socket address then the return value from this method is of type {@link | ||
| 261 | * java.net.InetSocketAddress}. | ||
| 262 | * | ||
| 263 | * @return The remote address; {@code null} if the channel's socket is not | ||
| 264 | * connected | ||
| 265 | * | ||
| 266 | * @throws ClosedChannelException | ||
| 267 | * If the channel is closed | ||
| 268 | * @throws IOException | ||
| 269 | * If an I/O error occurs | ||
| 270 | */ | ||
| 271 | public abstract SocketAddress getRemoteAddress() throws IOException; | ||
| 272 | |||
| 273 | // -- asynchronous operations -- | ||
| 274 | |||
| 275 | /** | ||
| 276 | * Connects this channel. | ||
| 277 | * | ||
| 278 | * <p> This method initiates an operation to connect this channel. The | ||
| 279 | * {@code handler} parameter is a completion handler that is invoked when | ||
| 280 | * the connection is successfully established or connection cannot be | ||
| 281 | * established. If the connection cannot be established then the channel is | ||
| 282 | * closed. | ||
| 283 | * | ||
| 284 | * <p> This method performs exactly the same security checks as the {@link | ||
| 285 | * java.net.Socket} class. That is, if a security manager has been | ||
| 286 | * installed then this method verifies that its {@link | ||
| 287 | * java.lang.SecurityManager#checkConnect checkConnect} method permits | ||
| 288 | * connecting to the address and port number of the given remote endpoint. | ||
| 289 | * | ||
| 290 | * @param remote | ||
| 291 | * The remote address to which this channel is to be connected | ||
| 292 | * @param attachment | ||
| 293 | * The object to attach to the I/O operation; can be {@code null} | ||
| 294 | * @param handler | ||
| 295 | * The handler for consuming the result | ||
| 296 | * | ||
| 297 | * @throws UnresolvedAddressException | ||
| 298 | * If the given remote address is not fully resolved | ||
| 299 | * @throws UnsupportedAddressTypeException | ||
| 300 | * If the type of the given remote address is not supported | ||
| 301 | * @throws AlreadyConnectedException | ||
| 302 | * If this channel is already connected | ||
| 303 | * @throws ConnectionPendingException | ||
| 304 | * If a connection operation is already in progress on this channel | ||
| 305 | * @throws ShutdownChannelGroupException | ||
| 306 | * If the channel group has terminated | ||
| 307 | * @throws SecurityException | ||
| 308 | * If a security manager has been installed | ||
| 309 | * and it does not permit access to the given remote endpoint | ||
| 310 | * | ||
| 311 | * @see #getRemoteAddress | ||
| 312 | */ | ||
| 313 | public abstract <A> void connect(SocketAddress remote, | ||
| 314 | A attachment, | ||
| 315 | CompletionHandler<Void,? super A> handler); | ||
| 316 | |||
| 317 | /** | ||
| 318 | * Connects this channel. | ||
| 319 | * | ||
| 320 | * <p> This method initiates an operation to connect this channel. This | ||
| 321 | * method behaves in exactly the same manner as the {@link | ||
| 322 | * #connect(SocketAddress, Object, CompletionHandler)} method except that | ||
| 323 | * instead of specifying a completion handler, this method returns a {@code | ||
| 324 | * Future} representing the pending result. The {@code Future}'s {@link | ||
| 325 | * Future#get() get} method returns {@code null} on successful completion. | ||
| 326 | * | ||
| 327 | * @param remote | ||
| 328 | * The remote address to which this channel is to be connected | ||
| 329 | * | ||
| 330 | * @return A {@code Future} object representing the pending result | ||
| 331 | * | ||
| 332 | * @throws UnresolvedAddressException | ||
| 333 | * If the given remote address is not fully resolved | ||
| 334 | * @throws UnsupportedAddressTypeException | ||
| 335 | * If the type of the given remote address is not supported | ||
| 336 | * @throws AlreadyConnectedException | ||
| 337 | * If this channel is already connected | ||
| 338 | * @throws ConnectionPendingException | ||
| 339 | * If a connection operation is already in progress on this channel | ||
| 340 | * @throws SecurityException | ||
| 341 | * If a security manager has been installed | ||
| 342 | * and it does not permit access to the given remote endpoint | ||
| 343 | */ | ||
| 344 | public abstract Future<Void> connect(SocketAddress remote); | ||
| 345 | |||
| 346 | /** | ||
| 347 | * Reads a sequence of bytes from this channel into the given buffer. | ||
| 348 | * | ||
| 349 | * <p> This method initiates an asynchronous read operation to read a | ||
| 350 | * sequence of bytes from this channel into the given buffer. The {@code | ||
| 351 | * handler} parameter is a completion handler that is invoked when the read | ||
| 352 | * operation completes (or fails). The result passed to the completion | ||
| 353 | * handler is the number of bytes read or {@code -1} if no bytes could be | ||
| 354 | * read because the channel has reached end-of-stream. | ||
| 355 | * | ||
| 356 | * <p> If a timeout is specified and the timeout elapses before the operation | ||
| 357 | * completes then the operation completes with the exception {@link | ||
| 358 | * InterruptedByTimeoutException}. Where a timeout occurs, and the | ||
| 359 | * implementation cannot guarantee that bytes have not been read, or will not | ||
| 360 | * be read from the channel into the given buffer, then further attempts to | ||
| 361 | * read from the channel will cause an unspecific runtime exception to be | ||
| 362 | * thrown. | ||
| 363 | * | ||
| 364 | * <p> Otherwise this method works in the same manner as the {@link | ||
| 365 | * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)} | ||
| 366 | * method. | ||
| 367 | * | ||
| 368 | * @param dst | ||
| 369 | * The buffer into which bytes are to be transferred | ||
| 370 | * @param timeout | ||
| 371 | * The maximum time for the I/O operation to complete | ||
| 372 | * @param unit | ||
| 373 | * The time unit of the {@code timeout} argument | ||
| 374 | * @param attachment | ||
| 375 | * The object to attach to the I/O operation; can be {@code null} | ||
| 376 | * @param handler | ||
| 377 | * The handler for consuming the result | ||
| 378 | * | ||
| 379 | * @throws IllegalArgumentException | ||
| 380 | * If the buffer is read-only | ||
| 381 | * @throws ReadPendingException | ||
| 382 | * If a read operation is already in progress on this channel | ||
| 383 | * @throws NotYetConnectedException | ||
| 384 | * If this channel is not yet connected | ||
| 385 | * @throws ShutdownChannelGroupException | ||
| 386 | * If the channel group has terminated | ||
| 387 | */ | ||
| 388 | public abstract <A> void read(ByteBuffer dst, | ||
| 389 | long timeout, | ||
| 390 | TimeUnit unit, | ||
| 391 | A attachment, | ||
| 392 | CompletionHandler<Integer,? super A> handler); | ||
| 393 | |||
| 394 | /** | ||
| 395 | * @throws IllegalArgumentException {@inheritDoc} | ||
| 396 | * @throws ReadPendingException {@inheritDoc} | ||
| 397 | * @throws NotYetConnectedException | ||
| 398 | * If this channel is not yet connected | ||
| 399 | * @throws ShutdownChannelGroupException | ||
| 400 | * If the channel group has terminated | ||
| 401 | */ | ||
| 402 | @Override | ||
| 403 | public final <A> void read(ByteBuffer dst, | ||
| 404 | A attachment, | ||
| 405 | CompletionHandler<Integer,? super A> handler) | ||
| 406 | { | ||
| 407 | read(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler); | ||
| 408 | } | ||
| 409 | |||
| 410 | /** | ||
| 411 | * @throws IllegalArgumentException {@inheritDoc} | ||
| 412 | * @throws ReadPendingException {@inheritDoc} | ||
| 413 | * @throws NotYetConnectedException | ||
| 414 | * If this channel is not yet connected | ||
| 415 | */ | ||
| 416 | @Override | ||
| 417 | public abstract Future<Integer> read(ByteBuffer dst); | ||
| 418 | |||
| 419 | /** | ||
| 420 | * Reads a sequence of bytes from this channel into a subsequence of the | ||
| 421 | * given buffers. This operation, sometimes called a <em>scattering read</em>, | ||
| 422 | * is often useful when implementing network protocols that group data into | ||
| 423 | * segments consisting of one or more fixed-length headers followed by a | ||
| 424 | * variable-length body. The {@code handler} parameter is a completion | ||
| 425 | * handler that is invoked when the read operation completes (or fails). The | ||
| 426 | * result passed to the completion handler is the number of bytes read or | ||
| 427 | * {@code -1} if no bytes could be read because the channel has reached | ||
| 428 | * end-of-stream. | ||
| 429 | * | ||
| 430 | * <p> This method initiates a read of up to <i>r</i> bytes from this channel, | ||
| 431 | * where <i>r</i> is the total number of bytes remaining in the specified | ||
| 432 | * subsequence of the given buffer array, that is, | ||
| 433 | * | ||
| 434 | * <blockquote><pre> | ||
| 435 | * dsts[offset].remaining() | ||
| 436 | * + dsts[offset+1].remaining() | ||
| 437 | * + ... + dsts[offset+length-1].remaining()</pre></blockquote> | ||
| 438 | * | ||
| 439 | * at the moment that the read is attempted. | ||
| 440 | * | ||
| 441 | * <p> Suppose that a byte sequence of length <i>n</i> is read, where | ||
| 442 | * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. | ||
| 443 | * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence | ||
| 444 | * are transferred into buffer <tt>dsts[offset]</tt>, up to the next | ||
| 445 | * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer | ||
| 446 | * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence | ||
| 447 | * is transferred into the given buffers. As many bytes as possible are | ||
| 448 | * transferred into each buffer, hence the final position of each updated | ||
| 449 | * buffer, except the last updated buffer, is guaranteed to be equal to | ||
| 450 | * that buffer's limit. The underlying operating system may impose a limit | ||
| 451 | * on the number of buffers that may be used in an I/O operation. Where the | ||
| 452 | * number of buffers (with bytes remaining), exceeds this limit, then the | ||
| 453 | * I/O operation is performed with the maximum number of buffers allowed by | ||
| 454 | * the operating system. | ||
| 455 | * | ||
| 456 | * <p> If a timeout is specified and the timeout elapses before the operation | ||
| 457 | * completes then it completes with the exception {@link | ||
| 458 | * InterruptedByTimeoutException}. Where a timeout occurs, and the | ||
| 459 | * implementation cannot guarantee that bytes have not been read, or will not | ||
| 460 | * be read from the channel into the given buffers, then further attempts to | ||
| 461 | * read from the channel will cause an unspecific runtime exception to be | ||
| 462 | * thrown. | ||
| 463 | * | ||
| 464 | * @param dsts | ||
| 465 | * The buffers into which bytes are to be transferred | ||
| 466 | * @param offset | ||
| 467 | * The offset within the buffer array of the first buffer into which | ||
| 468 | * bytes are to be transferred; must be non-negative and no larger than | ||
| 469 | * {@code dsts.length} | ||
| 470 | * @param length | ||
| 471 | * The maximum number of buffers to be accessed; must be non-negative | ||
| 472 | * and no larger than {@code dsts.length - offset} | ||
| 473 | * @param timeout | ||
| 474 | * The maximum time for the I/O operation to complete | ||
| 475 | * @param unit | ||
| 476 | * The time unit of the {@code timeout} argument | ||
| 477 | * @param attachment | ||
| 478 | * The object to attach to the I/O operation; can be {@code null} | ||
| 479 | * @param handler | ||
| 480 | * The handler for consuming the result | ||
| 481 | * | ||
| 482 | * @throws IndexOutOfBoundsException | ||
| 483 | * If the pre-conditions for the {@code offset} and {@code length} | ||
| 484 | * parameter aren't met | ||
| 485 | * @throws IllegalArgumentException | ||
| 486 | * If the buffer is read-only | ||
| 487 | * @throws ReadPendingException | ||
| 488 | * If a read operation is already in progress on this channel | ||
| 489 | * @throws NotYetConnectedException | ||
| 490 | * If this channel is not yet connected | ||
| 491 | * @throws ShutdownChannelGroupException | ||
| 492 | * If the channel group has terminated | ||
| 493 | */ | ||
| 494 | public abstract <A> void read(ByteBuffer[] dsts, | ||
| 495 | int offset, | ||
| 496 | int length, | ||
| 497 | long timeout, | ||
| 498 | TimeUnit unit, | ||
| 499 | A attachment, | ||
| 500 | CompletionHandler<Long,? super A> handler); | ||
| 501 | |||
| 502 | /** | ||
| 503 | * Writes a sequence of bytes to this channel from the given buffer. | ||
| 504 | * | ||
| 505 | * <p> This method initiates an asynchronous write operation to write a | ||
| 506 | * sequence of bytes to this channel from the given buffer. The {@code | ||
| 507 | * handler} parameter is a completion handler that is invoked when the write | ||
| 508 | * operation completes (or fails). The result passed to the completion | ||
| 509 | * handler is the number of bytes written. | ||
| 510 | * | ||
| 511 | * <p> If a timeout is specified and the timeout elapses before the operation | ||
| 512 | * completes then it completes with the exception {@link | ||
| 513 | * InterruptedByTimeoutException}. Where a timeout occurs, and the | ||
| 514 | * implementation cannot guarantee that bytes have not been written, or will | ||
| 515 | * not be written to the channel from the given buffer, then further attempts | ||
| 516 | * to write to the channel will cause an unspecific runtime exception to be | ||
| 517 | * thrown. | ||
| 518 | * | ||
| 519 | * <p> Otherwise this method works in the same manner as the {@link | ||
| 520 | * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)} | ||
| 521 | * method. | ||
| 522 | * | ||
| 523 | * @param src | ||
| 524 | * The buffer from which bytes are to be retrieved | ||
| 525 | * @param timeout | ||
| 526 | * The maximum time for the I/O operation to complete | ||
| 527 | * @param unit | ||
| 528 | * The time unit of the {@code timeout} argument | ||
| 529 | * @param attachment | ||
| 530 | * The object to attach to the I/O operation; can be {@code null} | ||
| 531 | * @param handler | ||
| 532 | * The handler for consuming the result | ||
| 533 | * | ||
| 534 | * @throws WritePendingException | ||
| 535 | * If a write operation is already in progress on this channel | ||
| 536 | * @throws NotYetConnectedException | ||
| 537 | * If this channel is not yet connected | ||
| 538 | * @throws ShutdownChannelGroupException | ||
| 539 | * If the channel group has terminated | ||
| 540 | */ | ||
| 541 | public abstract <A> void write(ByteBuffer src, | ||
| 542 | long timeout, | ||
| 543 | TimeUnit unit, | ||
| 544 | A attachment, | ||
| 545 | CompletionHandler<Integer,? super A> handler); | ||
| 546 | |||
| 547 | /** | ||
| 548 | * @throws WritePendingException {@inheritDoc} | ||
| 549 | * @throws NotYetConnectedException | ||
| 550 | * If this channel is not yet connected | ||
| 551 | * @throws ShutdownChannelGroupException | ||
| 552 | * If the channel group has terminated | ||
| 553 | */ | ||
| 554 | @Override | ||
| 555 | public final <A> void write(ByteBuffer src, | ||
| 556 | A attachment, | ||
| 557 | CompletionHandler<Integer,? super A> handler) | ||
| 558 | |||
| 559 | { | ||
| 560 | write(src, 0L, TimeUnit.MILLISECONDS, attachment, handler); | ||
| 561 | } | ||
| 562 | |||
| 563 | /** | ||
| 564 | * @throws WritePendingException {@inheritDoc} | ||
| 565 | * @throws NotYetConnectedException | ||
| 566 | * If this channel is not yet connected | ||
| 567 | */ | ||
| 568 | @Override | ||
| 569 | public abstract Future<Integer> write(ByteBuffer src); | ||
| 570 | |||
| 571 | /** | ||
| 572 | * Writes a sequence of bytes to this channel from a subsequence of the given | ||
| 573 | * buffers. This operation, sometimes called a <em>gathering write</em>, is | ||
| 574 | * often useful when implementing network protocols that group data into | ||
| 575 | * segments consisting of one or more fixed-length headers followed by a | ||
| 576 | * variable-length body. The {@code handler} parameter is a completion | ||
| 577 | * handler that is invoked when the write operation completes (or fails). | ||
| 578 | * The result passed to the completion handler is the number of bytes written. | ||
| 579 | * | ||
| 580 | * <p> This method initiates a write of up to <i>r</i> bytes to this channel, | ||
| 581 | * where <i>r</i> is the total number of bytes remaining in the specified | ||
| 582 | * subsequence of the given buffer array, that is, | ||
| 583 | * | ||
| 584 | * <blockquote><pre> | ||
| 585 | * srcs[offset].remaining() | ||
| 586 | * + srcs[offset+1].remaining() | ||
| 587 | * + ... + srcs[offset+length-1].remaining()</pre></blockquote> | ||
| 588 | * | ||
| 589 | * at the moment that the write is attempted. | ||
| 590 | * | ||
| 591 | * <p> Suppose that a byte sequence of length <i>n</i> is written, where | ||
| 592 | * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. | ||
| 593 | * Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence | ||
| 594 | * are written from buffer <tt>srcs[offset]</tt>, up to the next | ||
| 595 | * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer | ||
| 596 | * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is | ||
| 597 | * written. As many bytes as possible are written from each buffer, hence | ||
| 598 | * the final position of each updated buffer, except the last updated | ||
| 599 | * buffer, is guaranteed to be equal to that buffer's limit. The underlying | ||
| 600 | * operating system may impose a limit on the number of buffers that may be | ||
| 601 | * used in an I/O operation. Where the number of buffers (with bytes | ||
| 602 | * remaining), exceeds this limit, then the I/O operation is performed with | ||
| 603 | * the maximum number of buffers allowed by the operating system. | ||
| 604 | * | ||
| 605 | * <p> If a timeout is specified and the timeout elapses before the operation | ||
| 606 | * completes then it completes with the exception {@link | ||
| 607 | * InterruptedByTimeoutException}. Where a timeout occurs, and the | ||
| 608 | * implementation cannot guarantee that bytes have not been written, or will | ||
| 609 | * not be written to the channel from the given buffers, then further attempts | ||
| 610 | * to write to the channel will cause an unspecific runtime exception to be | ||
| 611 | * thrown. | ||
| 612 | * | ||
| 613 | * @param srcs | ||
| 614 | * The buffers from which bytes are to be retrieved | ||
| 615 | * @param offset | ||
| 616 | * The offset within the buffer array of the first buffer from which | ||
| 617 | * bytes are to be retrieved; must be non-negative and no larger | ||
| 618 | * than {@code srcs.length} | ||
| 619 | * @param length | ||
| 620 | * The maximum number of buffers to be accessed; must be non-negative | ||
| 621 | * and no larger than {@code srcs.length - offset} | ||
| 622 | * @param timeout | ||
| 623 | * The maximum time for the I/O operation to complete | ||
| 624 | * @param unit | ||
| 625 | * The time unit of the {@code timeout} argument | ||
| 626 | * @param attachment | ||
| 627 | * The object to attach to the I/O operation; can be {@code null} | ||
| 628 | * @param handler | ||
| 629 | * The handler for consuming the result | ||
| 630 | * | ||
| 631 | * @throws IndexOutOfBoundsException | ||
| 632 | * If the pre-conditions for the {@code offset} and {@code length} | ||
| 633 | * parameter aren't met | ||
| 634 | * @throws WritePendingException | ||
| 635 | * If a write operation is already in progress on this channel | ||
| 636 | * @throws NotYetConnectedException | ||
| 637 | * If this channel is not yet connected | ||
| 638 | * @throws ShutdownChannelGroupException | ||
| 639 | * If the channel group has terminated | ||
| 640 | */ | ||
| 641 | public abstract <A> void write(ByteBuffer[] srcs, | ||
| 642 | int offset, | ||
| 643 | int length, | ||
| 644 | long timeout, | ||
| 645 | TimeUnit unit, | ||
| 646 | A attachment, | ||
| 647 | CompletionHandler<Long,? super A> handler); | ||
| 648 | } | ||