View Javadoc
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      * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<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      */
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      * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<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      */
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 }