1 /* 2 * Copyright (c) 2007, 2013, 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 summary="Socket options"> 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 * <h2>Timeouts</h2> 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 * @param provider 128 * The provider that created this channel 129 */ AsynchronousSocketChannel(AsynchronousChannelProvider provider)130 protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) { 131 this.provider = provider; 132 } 133 134 /** 135 * Returns the provider that created this channel. 136 * 137 * @return The provider that created this channel 138 */ provider()139 public final AsynchronousChannelProvider provider() { 140 return provider; 141 } 142 143 /** 144 * Opens an asynchronous socket channel. 145 * 146 * <p> The new channel is created by invoking the {@link 147 * AsynchronousChannelProvider#openAsynchronousSocketChannel 148 * openAsynchronousSocketChannel} method on the {@link 149 * AsynchronousChannelProvider} that created the group. If the group parameter 150 * is {@code null} then the resulting channel is created by the system-wide 151 * default provider, and bound to the <em>default group</em>. 152 * 153 * @param group 154 * The group to which the newly constructed channel should be bound, 155 * or {@code null} for the default group 156 * 157 * @return A new asynchronous socket channel 158 * 159 * @throws ShutdownChannelGroupException 160 * If the channel group is shutdown 161 * @throws IOException 162 * If an I/O error occurs 163 */ open(AsynchronousChannelGroup group)164 public static AsynchronousSocketChannel open(AsynchronousChannelGroup group) 165 throws IOException 166 { 167 AsynchronousChannelProvider provider = (group == null) ? 168 AsynchronousChannelProvider.provider() : group.provider(); 169 return provider.openAsynchronousSocketChannel(group); 170 } 171 172 /** 173 * Opens an asynchronous socket channel. 174 * 175 * <p> This method returns an asynchronous socket channel that is bound to 176 * the <em>default group</em>.This method is equivalent to evaluating the 177 * expression: 178 * <blockquote><pre> 179 * open((AsynchronousChannelGroup)null); 180 * </pre></blockquote> 181 * 182 * @return A new asynchronous socket channel 183 * 184 * @throws IOException 185 * If an I/O error occurs 186 */ open()187 public static AsynchronousSocketChannel open() 188 throws IOException 189 { 190 return open(null); 191 } 192 193 194 // -- socket options and related -- 195 196 /** 197 * @throws ConnectionPendingException 198 * If a connection operation is already in progress on this channel 199 * @throws AlreadyBoundException {@inheritDoc} 200 * @throws UnsupportedAddressTypeException {@inheritDoc} 201 * @throws ClosedChannelException {@inheritDoc} 202 * @throws IOException {@inheritDoc} 203 * @throws SecurityException 204 * If a security manager has been installed and its 205 * {@link SecurityManager#checkListen checkListen} method denies 206 * the operation 207 */ 208 @Override bind(SocketAddress local)209 public abstract AsynchronousSocketChannel bind(SocketAddress local) 210 throws IOException; 211 212 /** 213 * @throws IllegalArgumentException {@inheritDoc} 214 * @throws ClosedChannelException {@inheritDoc} 215 * @throws IOException {@inheritDoc} 216 */ 217 @Override setOption(SocketOption<T> name, T value)218 public abstract <T> AsynchronousSocketChannel setOption(SocketOption<T> name, T value) 219 throws IOException; 220 221 /** 222 * Shutdown the connection for reading without closing the channel. 223 * 224 * <p> Once shutdown for reading then further reads on the channel will 225 * return {@code -1}, the end-of-stream indication. If the input side of the 226 * connection is already shutdown then invoking this method has no effect. 227 * The effect on an outstanding read operation is system dependent and 228 * therefore not specified. The effect, if any, when there is data in the 229 * socket receive buffer that has not been read, or data arrives subsequently, 230 * is also system dependent. 231 * 232 * @return The channel 233 * 234 * @throws NotYetConnectedException 235 * If this channel is not yet connected 236 * @throws ClosedChannelException 237 * If this channel is closed 238 * @throws IOException 239 * If some other I/O error occurs 240 */ shutdownInput()241 public abstract AsynchronousSocketChannel shutdownInput() throws IOException; 242 243 /** 244 * Shutdown the connection for writing without closing the channel. 245 * 246 * <p> Once shutdown for writing then further attempts to write to the 247 * channel will throw {@link ClosedChannelException}. If the output side of 248 * the connection is already shutdown then invoking this method has no 249 * effect. The effect on an outstanding write operation is system dependent 250 * and therefore not specified. 251 * 252 * @return The channel 253 * 254 * @throws NotYetConnectedException 255 * If this channel is not yet connected 256 * @throws ClosedChannelException 257 * If this channel is closed 258 * @throws IOException 259 * If some other I/O error occurs 260 */ shutdownOutput()261 public abstract AsynchronousSocketChannel shutdownOutput() throws IOException; 262 263 // -- state -- 264 265 /** 266 * Returns the remote address to which this channel's socket is connected. 267 * 268 * <p> Where the channel is bound and connected to an Internet Protocol 269 * socket address then the return value from this method is of type {@link 270 * java.net.InetSocketAddress}. 271 * 272 * @return The remote address; {@code null} if the channel's socket is not 273 * connected 274 * 275 * @throws ClosedChannelException 276 * If the channel is closed 277 * @throws IOException 278 * If an I/O error occurs 279 */ getRemoteAddress()280 public abstract SocketAddress getRemoteAddress() throws IOException; 281 282 // -- asynchronous operations -- 283 284 /** 285 * Connects this channel. 286 * 287 * <p> This method initiates an operation to connect this channel. The 288 * {@code handler} parameter is a completion handler that is invoked when 289 * the connection is successfully established or connection cannot be 290 * established. If the connection cannot be established then the channel is 291 * closed. 292 * 293 * <p> This method performs exactly the same security checks as the {@link 294 * java.net.Socket} class. That is, if a security manager has been 295 * installed then this method verifies that its {@link 296 * java.lang.SecurityManager#checkConnect checkConnect} method permits 297 * connecting to the address and port number of the given remote endpoint. 298 * 299 * @param <A> 300 * The type of the attachment 301 * @param remote 302 * The remote address to which this channel is to be connected 303 * @param attachment 304 * The object to attach to the I/O operation; can be {@code null} 305 * @param handler 306 * The handler for consuming the result 307 * 308 * @throws UnresolvedAddressException 309 * If the given remote address is not fully resolved 310 * @throws UnsupportedAddressTypeException 311 * If the type of the given remote address is not supported 312 * @throws AlreadyConnectedException 313 * If this channel is already connected 314 * @throws ConnectionPendingException 315 * If a connection operation is already in progress on this channel 316 * @throws ShutdownChannelGroupException 317 * If the channel group has terminated 318 * @throws SecurityException 319 * If a security manager has been installed 320 * and it does not permit access to the given remote endpoint 321 * 322 * @see #getRemoteAddress 323 */ connect(SocketAddress remote, A attachment, CompletionHandler<Void,? super A> handler)324 public abstract <A> void connect(SocketAddress remote, 325 A attachment, 326 CompletionHandler<Void,? super A> handler); 327 328 /** 329 * Connects this channel. 330 * 331 * <p> This method initiates an operation to connect this channel. This 332 * method behaves in exactly the same manner as the {@link 333 * #connect(SocketAddress, Object, CompletionHandler)} method except that 334 * instead of specifying a completion handler, this method returns a {@code 335 * Future} representing the pending result. The {@code Future}'s {@link 336 * Future#get() get} method returns {@code null} on successful completion. 337 * 338 * @param remote 339 * The remote address to which this channel is to be connected 340 * 341 * @return A {@code Future} object representing the pending result 342 * 343 * @throws UnresolvedAddressException 344 * If the given remote address is not fully resolved 345 * @throws UnsupportedAddressTypeException 346 * If the type of the given remote address is not supported 347 * @throws AlreadyConnectedException 348 * If this channel is already connected 349 * @throws ConnectionPendingException 350 * If a connection operation is already in progress on this channel 351 * @throws SecurityException 352 * If a security manager has been installed 353 * and it does not permit access to the given remote endpoint 354 */ connect(SocketAddress remote)355 public abstract Future<Void> connect(SocketAddress remote); 356 357 /** 358 * Reads a sequence of bytes from this channel into the given buffer. 359 * 360 * <p> This method initiates an asynchronous read operation to read a 361 * sequence of bytes from this channel into the given buffer. The {@code 362 * handler} parameter is a completion handler that is invoked when the read 363 * operation completes (or fails). The result passed to the completion 364 * handler is the number of bytes read or {@code -1} if no bytes could be 365 * read because the channel has reached end-of-stream. 366 * 367 * <p> If a timeout is specified and the timeout elapses before the operation 368 * completes then the operation completes with the exception {@link 369 * InterruptedByTimeoutException}. Where a timeout occurs, and the 370 * implementation cannot guarantee that bytes have not been read, or will not 371 * be read from the channel into the given buffer, then further attempts to 372 * read from the channel will cause an unspecific runtime exception to be 373 * thrown. 374 * 375 * <p> Otherwise this method works in the same manner as the {@link 376 * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)} 377 * method. 378 * 379 * @param <A> 380 * The type of the attachment 381 * @param dst 382 * The buffer into which bytes are to be transferred 383 * @param timeout 384 * The maximum time for the I/O operation to complete 385 * @param unit 386 * The time unit of the {@code timeout} argument 387 * @param attachment 388 * The object to attach to the I/O operation; can be {@code null} 389 * @param handler 390 * The handler for consuming the result 391 * 392 * @throws IllegalArgumentException 393 * If the buffer is read-only 394 * @throws ReadPendingException 395 * If a read operation is already in progress on this channel 396 * @throws NotYetConnectedException 397 * If this channel is not yet connected 398 * @throws ShutdownChannelGroupException 399 * If the channel group has terminated 400 */ read(ByteBuffer dst, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler)401 public abstract <A> void read(ByteBuffer dst, 402 long timeout, 403 TimeUnit unit, 404 A attachment, 405 CompletionHandler<Integer,? super A> handler); 406 407 /** 408 * @throws IllegalArgumentException {@inheritDoc} 409 * @throws ReadPendingException {@inheritDoc} 410 * @throws NotYetConnectedException 411 * If this channel is not yet connected 412 * @throws ShutdownChannelGroupException 413 * If the channel group has terminated 414 */ 415 @Override read(ByteBuffer dst, A attachment, CompletionHandler<Integer,? super A> handler)416 public final <A> void read(ByteBuffer dst, 417 A attachment, 418 CompletionHandler<Integer,? super A> handler) 419 { 420 read(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler); 421 } 422 423 /** 424 * @throws IllegalArgumentException {@inheritDoc} 425 * @throws ReadPendingException {@inheritDoc} 426 * @throws NotYetConnectedException 427 * If this channel is not yet connected 428 */ 429 @Override read(ByteBuffer dst)430 public abstract Future<Integer> read(ByteBuffer dst); 431 432 /** 433 * Reads a sequence of bytes from this channel into a subsequence of the 434 * given buffers. This operation, sometimes called a <em>scattering read</em>, 435 * is often useful when implementing network protocols that group data into 436 * segments consisting of one or more fixed-length headers followed by a 437 * variable-length body. The {@code handler} parameter is a completion 438 * handler that is invoked when the read operation completes (or fails). The 439 * result passed to the completion handler is the number of bytes read or 440 * {@code -1} if no bytes could be read because the channel has reached 441 * end-of-stream. 442 * 443 * <p> This method initiates a read of up to <i>r</i> bytes from this channel, 444 * where <i>r</i> is the total number of bytes remaining in the specified 445 * subsequence of the given buffer array, that is, 446 * 447 * <blockquote><pre> 448 * dsts[offset].remaining() 449 * + dsts[offset+1].remaining() 450 * + ... + dsts[offset+length-1].remaining()</pre></blockquote> 451 * 452 * at the moment that the read is attempted. 453 * 454 * <p> Suppose that a byte sequence of length <i>n</i> is read, where 455 * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. 456 * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence 457 * are transferred into buffer <tt>dsts[offset]</tt>, up to the next 458 * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer 459 * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence 460 * is transferred into the given buffers. As many bytes as possible are 461 * transferred into each buffer, hence the final position of each updated 462 * buffer, except the last updated buffer, is guaranteed to be equal to 463 * that buffer's limit. The underlying operating system may impose a limit 464 * on the number of buffers that may be used in an I/O operation. Where the 465 * number of buffers (with bytes remaining), exceeds this limit, then the 466 * I/O operation is performed with the maximum number of buffers allowed by 467 * the operating system. 468 * 469 * <p> If a timeout is specified and the timeout elapses before the operation 470 * completes then it completes with the exception {@link 471 * InterruptedByTimeoutException}. Where a timeout occurs, and the 472 * implementation cannot guarantee that bytes have not been read, or will not 473 * be read from the channel into the given buffers, then further attempts to 474 * read from the channel will cause an unspecific runtime exception to be 475 * thrown. 476 * 477 * @param <A> 478 * The type of the attachment 479 * @param dsts 480 * The buffers into which bytes are to be transferred 481 * @param offset 482 * The offset within the buffer array of the first buffer into which 483 * bytes are to be transferred; must be non-negative and no larger than 484 * {@code dsts.length} 485 * @param length 486 * The maximum number of buffers to be accessed; must be non-negative 487 * and no larger than {@code dsts.length - offset} 488 * @param timeout 489 * The maximum time for the I/O operation to complete 490 * @param unit 491 * The time unit of the {@code timeout} argument 492 * @param attachment 493 * The object to attach to the I/O operation; can be {@code null} 494 * @param handler 495 * The handler for consuming the result 496 * 497 * @throws IndexOutOfBoundsException 498 * If the pre-conditions for the {@code offset} and {@code length} 499 * parameter aren't met 500 * @throws IllegalArgumentException 501 * If the buffer is read-only 502 * @throws ReadPendingException 503 * If a read operation is already in progress on this channel 504 * @throws NotYetConnectedException 505 * If this channel is not yet connected 506 * @throws ShutdownChannelGroupException 507 * If the channel group has terminated 508 */ read(ByteBuffer[] dsts, int offset, int length, long timeout, TimeUnit unit, A attachment, CompletionHandler<Long,? super A> handler)509 public abstract <A> void read(ByteBuffer[] dsts, 510 int offset, 511 int length, 512 long timeout, 513 TimeUnit unit, 514 A attachment, 515 CompletionHandler<Long,? super A> handler); 516 517 /** 518 * Writes a sequence of bytes to this channel from the given buffer. 519 * 520 * <p> This method initiates an asynchronous write operation to write a 521 * sequence of bytes to this channel from the given buffer. The {@code 522 * handler} parameter is a completion handler that is invoked when the write 523 * operation completes (or fails). The result passed to the completion 524 * handler is the number of bytes written. 525 * 526 * <p> If a timeout is specified and the timeout elapses before the operation 527 * completes then it completes with the exception {@link 528 * InterruptedByTimeoutException}. Where a timeout occurs, and the 529 * implementation cannot guarantee that bytes have not been written, or will 530 * not be written to the channel from the given buffer, then further attempts 531 * to write to the channel will cause an unspecific runtime exception to be 532 * thrown. 533 * 534 * <p> Otherwise this method works in the same manner as the {@link 535 * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)} 536 * method. 537 * 538 * @param <A> 539 * The type of the attachment 540 * @param src 541 * The buffer from which bytes are to be retrieved 542 * @param timeout 543 * The maximum time for the I/O operation to complete 544 * @param unit 545 * The time unit of the {@code timeout} argument 546 * @param attachment 547 * The object to attach to the I/O operation; can be {@code null} 548 * @param handler 549 * The handler for consuming the result 550 * 551 * @throws WritePendingException 552 * If a write operation is already in progress on this channel 553 * @throws NotYetConnectedException 554 * If this channel is not yet connected 555 * @throws ShutdownChannelGroupException 556 * If the channel group has terminated 557 */ write(ByteBuffer src, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler)558 public abstract <A> void write(ByteBuffer src, 559 long timeout, 560 TimeUnit unit, 561 A attachment, 562 CompletionHandler<Integer,? super A> handler); 563 564 /** 565 * @throws WritePendingException {@inheritDoc} 566 * @throws NotYetConnectedException 567 * If this channel is not yet connected 568 * @throws ShutdownChannelGroupException 569 * If the channel group has terminated 570 */ 571 @Override write(ByteBuffer src, A attachment, CompletionHandler<Integer,? super A> handler)572 public final <A> void write(ByteBuffer src, 573 A attachment, 574 CompletionHandler<Integer,? super A> handler) 575 576 { 577 write(src, 0L, TimeUnit.MILLISECONDS, attachment, handler); 578 } 579 580 /** 581 * @throws WritePendingException {@inheritDoc} 582 * @throws NotYetConnectedException 583 * If this channel is not yet connected 584 */ 585 @Override write(ByteBuffer src)586 public abstract Future<Integer> write(ByteBuffer src); 587 588 /** 589 * Writes a sequence of bytes to this channel from a subsequence of the given 590 * buffers. This operation, sometimes called a <em>gathering write</em>, is 591 * often useful when implementing network protocols that group data into 592 * segments consisting of one or more fixed-length headers followed by a 593 * variable-length body. The {@code handler} parameter is a completion 594 * handler that is invoked when the write operation completes (or fails). 595 * The result passed to the completion handler is the number of bytes written. 596 * 597 * <p> This method initiates a write of up to <i>r</i> bytes to this channel, 598 * where <i>r</i> is the total number of bytes remaining in the specified 599 * subsequence of the given buffer array, that is, 600 * 601 * <blockquote><pre> 602 * srcs[offset].remaining() 603 * + srcs[offset+1].remaining() 604 * + ... + srcs[offset+length-1].remaining()</pre></blockquote> 605 * 606 * at the moment that the write is attempted. 607 * 608 * <p> Suppose that a byte sequence of length <i>n</i> is written, where 609 * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. 610 * Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence 611 * are written from buffer <tt>srcs[offset]</tt>, up to the next 612 * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer 613 * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is 614 * written. As many bytes as possible are written from each buffer, hence 615 * the final position of each updated buffer, except the last updated 616 * buffer, is guaranteed to be equal to that buffer's limit. The underlying 617 * operating system may impose a limit on the number of buffers that may be 618 * used in an I/O operation. Where the number of buffers (with bytes 619 * remaining), exceeds this limit, then the I/O operation is performed with 620 * the maximum number of buffers allowed by the operating system. 621 * 622 * <p> If a timeout is specified and the timeout elapses before the operation 623 * completes then it completes with the exception {@link 624 * InterruptedByTimeoutException}. Where a timeout occurs, and the 625 * implementation cannot guarantee that bytes have not been written, or will 626 * not be written to the channel from the given buffers, then further attempts 627 * to write to the channel will cause an unspecific runtime exception to be 628 * thrown. 629 * 630 * @param <A> 631 * The type of the attachment 632 * @param srcs 633 * The buffers from which bytes are to be retrieved 634 * @param offset 635 * The offset within the buffer array of the first buffer from which 636 * bytes are to be retrieved; must be non-negative and no larger 637 * than {@code srcs.length} 638 * @param length 639 * The maximum number of buffers to be accessed; must be non-negative 640 * and no larger than {@code srcs.length - offset} 641 * @param timeout 642 * The maximum time for the I/O operation to complete 643 * @param unit 644 * The time unit of the {@code timeout} argument 645 * @param attachment 646 * The object to attach to the I/O operation; can be {@code null} 647 * @param handler 648 * The handler for consuming the result 649 * 650 * @throws IndexOutOfBoundsException 651 * If the pre-conditions for the {@code offset} and {@code length} 652 * parameter aren't met 653 * @throws WritePendingException 654 * If a write operation is already in progress on this channel 655 * @throws NotYetConnectedException 656 * If this channel is not yet connected 657 * @throws ShutdownChannelGroupException 658 * If the channel group has terminated 659 */ write(ByteBuffer[] srcs, int offset, int length, long timeout, TimeUnit unit, A attachment, CompletionHandler<Long,? super A> handler)660 public abstract <A> void write(ByteBuffer[] srcs, 661 int offset, 662 int length, 663 long timeout, 664 TimeUnit unit, 665 A attachment, 666 CompletionHandler<Long,? super A> handler); 667 668 /** 669 * {@inheritDoc} 670 * <p> 671 * If there is a security manager set, its {@code checkConnect} method is 672 * called with the local address and {@code -1} as its arguments to see 673 * if the operation is allowed. If the operation is not allowed, 674 * a {@code SocketAddress} representing the 675 * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the 676 * local port of the channel's socket is returned. 677 * 678 * @return The {@code SocketAddress} that the socket is bound to, or the 679 * {@code SocketAddress} representing the loopback address if 680 * denied by the security manager, or {@code null} if the 681 * channel's socket is not bound 682 * 683 * @throws ClosedChannelException {@inheritDoc} 684 * @throws IOException {@inheritDoc} 685 */ getLocalAddress()686 public abstract SocketAddress getLocalAddress() throws IOException; 687 } 688