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