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 */
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 */
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 */
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 */
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
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
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 */
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 */
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 */
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 */
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 */
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 */
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
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
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 * {@code 0} {@code <} <i>n</i> {@code <=} <i>r</i>.
456 * Up to the first {@code dsts[offset].remaining()} bytes of this sequence
457 * are transferred into buffer {@code dsts[offset]}, up to the next
458 * {@code dsts[offset+1].remaining()} bytes are transferred into buffer
459 * {@code dsts[offset+1]}, 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 */
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 */
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
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
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 * {@code 0} {@code <} <i>n</i> {@code <=} <i>r</i>.
610 * Up to the first {@code srcs[offset].remaining()} bytes of this sequence
611 * are written from buffer {@code srcs[offset]}, up to the next
612 * {@code srcs[offset+1].remaining()} bytes are written from buffer
613 * {@code srcs[offset+1]}, 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 */
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 */
686 public abstract SocketAddress getLocalAddress() throws IOException;
687 }