1. /*
  2. * @(#)GatheringByteChannel.java 1.12 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.nio.channels;
  8. import java.io.IOException;
  9. import java.nio.ByteBuffer;
  10. /**
  11. * A channel that can write bytes from a sequence of buffers.
  12. *
  13. * <p> A <i>gathering</i> write operation writes, in a single invocation, a
  14. * sequence of bytes from one or more of a given sequence of buffers.
  15. * Gathering writes are often useful when implementing network protocols or
  16. * file formats that, for example, group data into segments consisting of one
  17. * or more fixed-length headers followed by a variable-length body. Similar
  18. * <i>scattering</i> read operations are defined in the {@link
  19. * ScatteringByteChannel} interface. </p>
  20. *
  21. *
  22. * @author Mark Reinhold
  23. * @author JSR-51 Expert Group
  24. * @version 1.12, 03/12/19
  25. * @since 1.4
  26. */
  27. public interface GatheringByteChannel
  28. extends WritableByteChannel
  29. {
  30. /**
  31. * Writes a sequence of bytes to this channel from a subsequence of the
  32. * given buffers.
  33. *
  34. * <p> An attempt is made to write up to <i>r</i> bytes to this channel,
  35. * where <i>r</i> is the total number of bytes remaining in the specified
  36. * subsequence of the given buffer array, that is,
  37. *
  38. * <blockquote><pre>
  39. * srcs[offset].remaining()
  40. * + srcs[offset+1].remaining()
  41. * + ... + srcs[offset+length-1].remaining()</pre></blockquote>
  42. *
  43. * at the moment that this method is invoked.
  44. *
  45. * <p> Suppose that a byte sequence of length <i>n</i> is written, where
  46. * <tt>0</tt> <tt><=</tt> <i>n</i> <tt><=</tt> <i>r</i>.
  47. * Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence
  48. * are written from buffer <tt>srcs[offset]</tt>, up to the next
  49. * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer
  50. * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is
  51. * written. As many bytes as possible are written from each buffer, hence
  52. * the final position of each updated buffer, except the last updated
  53. * buffer, is guaranteed to be equal to that buffer's limit.
  54. *
  55. * <p> Unless otherwise specified, a write operation will return only after
  56. * writing all of the <i>r</i> requested bytes. Some types of channels,
  57. * depending upon their state, may write only some of the bytes or possibly
  58. * none at all. A socket channel in non-blocking mode, for example, cannot
  59. * write any more bytes than are free in the socket's output buffer.
  60. *
  61. * <p> This method may be invoked at any time. If another thread has
  62. * already initiated a write operation upon this channel, however, then an
  63. * invocation of this method will block until the first operation is
  64. * complete. </p>
  65. *
  66. * @param srcs
  67. * The buffers from which bytes are to be retrieved
  68. *
  69. * @param offset
  70. * The offset within the buffer array of the first buffer from
  71. * which bytes are to be retrieved; must be non-negative and no
  72. * larger than <tt>srcs.length</tt>
  73. *
  74. * @param length
  75. * The maximum number of buffers to be accessed; must be
  76. * non-negative and no larger than
  77. * <tt>srcs.length</tt> - <tt>offset</tt>
  78. *
  79. * @return The number of bytes written, possibly zero
  80. *
  81. * @throws IndexOutOfBoundsException
  82. * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
  83. * parameters do not hold
  84. *
  85. * @throws NonWritableChannelException
  86. * If this channel was not opened for writing
  87. *
  88. * @throws ClosedChannelException
  89. * If this channel is closed
  90. *
  91. * @throws AsynchronousCloseException
  92. * If another thread closes this channel
  93. * while the write operation is in progress
  94. *
  95. * @throws ClosedByInterruptException
  96. * If another thread interrupts the current thread
  97. * while the write operation is in progress, thereby
  98. * closing the channel and setting the current thread's
  99. * interrupt status
  100. *
  101. * @throws IOException
  102. * If some other I/O error occurs
  103. */
  104. public long write(ByteBuffer[] srcs, int offset, int length)
  105. throws IOException;
  106. /**
  107. * Writes a sequence of bytes to this channel from the given buffers.
  108. *
  109. * <p> An invocation of this method of the form <tt>c.write(srcs)</tt>
  110. * behaves in exactly the same manner as the invocation
  111. *
  112. * <blockquote><pre>
  113. * c.write(srcs, 0, srcs.length);</pre></blockquote>
  114. *
  115. * @param srcs
  116. * The buffers from which bytes are to be retrieved
  117. *
  118. * @return The number of bytes written, possibly zero
  119. *
  120. * @throws NonWritableChannelException
  121. * If this channel was not opened for writing
  122. *
  123. * @throws ClosedChannelException
  124. * If this channel is closed
  125. *
  126. * @throws AsynchronousCloseException
  127. * If another thread closes this channel
  128. * while the write operation is in progress
  129. *
  130. * @throws ClosedByInterruptException
  131. * If another thread interrupts the current thread
  132. * while the write operation is in progress, thereby
  133. * closing the channel and setting the current thread's
  134. * interrupt status
  135. *
  136. * @throws IOException
  137. * If some other I/O error occurs
  138. */
  139. public long write(ByteBuffer[] srcs) throws IOException;
  140. }