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 | +} | |