A gathering write operation writes, in a single invocation, a + * sequence of bytes from one or more of a given sequence of buffers. + * Gathering writes are often useful when implementing network protocols or + * file formats that, for example, group data into segments consisting of one + * or more fixed-length headers followed by a variable-length body. Similar + * scattering read operations are defined in the {@link + * ScatteringByteChannel} interface.
+ * + * + * @author Mark Reinhold + * @author JSR-51 Expert Group + * @since 1.4 + */ + +public interface GatheringByteChannel + extends WritableByteChannel +{ + + /** + * Writes a sequence of bytes to this channel from a subsequence of the + * given buffers. + * + *An attempt is made to write up to r bytes to this channel, + * where r is the total number of bytes remaining in the specified + * subsequence of the given buffer array, that is, + * + *
+ * + * at the moment that this method is invoked. + * + *+ * srcs[offset].remaining() + * + srcs[offset+1].remaining() + * + ... + srcs[offset+length-1].remaining()
Suppose that a byte sequence of length n is written, where + * {@code 0} {@code <=} n {@code <=} r. + * Up to the first {@code srcs[offset].remaining()} bytes of this sequence + * are written from buffer {@code srcs[offset]}, up to the next + * {@code srcs[offset+1].remaining()} bytes are written from buffer + * {@code srcs[offset+1]}, and so forth, until the entire byte sequence is + * written. As many bytes as possible are written from each buffer, hence + * the final position of each updated buffer, except the last updated + * buffer, is guaranteed to be equal to that buffer's limit. + * + *
Unless otherwise specified, a write operation will return only after + * writing all of the r requested bytes. Some types of channels, + * depending upon their state, may write only some of the bytes or possibly + * none at all. A socket channel in non-blocking mode, for example, cannot + * write any more bytes than are free in the socket's output buffer. + * + *
This method may be invoked at any time. If another thread has + * already initiated a write operation upon this channel, however, then an + * invocation of this method will block until the first operation is + * complete.
+ * + * @param srcs + * The buffers from which bytes are to be retrieved + * + * @param offset + * The offset within the buffer array of the first buffer from + * which bytes are to be retrieved; must be non-negative and no + * larger than {@code srcs.length} + * + * @param length + * The maximum number of buffers to be accessed; must be + * non-negative and no larger than + * {@code srcs.length} - {@code offset} + * + * @return The number of bytes written, possibly zero + * + * @throws IndexOutOfBoundsException + * If the preconditions on the {@code offset} and {@code length} + * parameters do not hold + * + * @throws NonWritableChannelException + * If this channel was not opened for writing + * + * @throws ClosedChannelException + * If this channel is closed + * + * @throws AsynchronousCloseException + * If another thread closes this channel + * while the write operation is in progress + * + * @throws ClosedByInterruptException + * If another thread interrupts the current thread + * while the write operation is in progress, thereby + * closing the channel and setting the current thread's + * interrupt status + * + * @throws IOException + * If some other I/O error occurs + */ + public long write(ByteBuffer[] srcs, int offset, int length) + throws IOException; + + + /** + * Writes a sequence of bytes to this channel from the given buffers. + * + *An invocation of this method of the form {@code c.write(srcs)} + * behaves in exactly the same manner as the invocation + * + *
+ * + * @param srcs + * The buffers from which bytes are to be retrieved + * + * @return The number of bytes written, possibly zero + * + * @throws NonWritableChannelException + * If this channel was not opened for writing + * + * @throws ClosedChannelException + * If this channel is closed + * + * @throws AsynchronousCloseException + * If another thread closes this channel + * while the write operation is in progress + * + * @throws ClosedByInterruptException + * If another thread interrupts the current thread + * while the write operation is in progress, thereby + * closing the channel and setting the current thread's + * interrupt status + * + * @throws IOException + * If some other I/O error occurs + */ + public long write(ByteBuffer[] srcs) throws IOException; + +}+ * c.write(srcs, 0, srcs.length);