1. /*
  2. * @(#)ScatteringByteChannel.java 1.13 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 read bytes into a sequence of buffers.
  12. *
  13. * <p> A <i>scattering</i> read operation reads, in a single invocation, a
  14. * sequence of bytes into one or more of a given sequence of buffers.
  15. * Scattering reads 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>gathering</i> write operations are defined in the {@link
  19. * GatheringByteChannel} interface. </p>
  20. *
  21. *
  22. * @author Mark Reinhold
  23. * @author JSR-51 Expert Group
  24. * @version 1.13, 03/12/19
  25. * @since 1.4
  26. */
  27. public interface ScatteringByteChannel
  28. extends ReadableByteChannel
  29. {
  30. /**
  31. * Reads a sequence of bytes from this channel into a subsequence of the
  32. * given buffers.
  33. *
  34. * <p> An invocation of this method attempts to read up to <i>r</i> bytes
  35. * from this channel, where <i>r</i> is the total number of bytes remaining
  36. * the specified subsequence of the given buffer array, that is,
  37. *
  38. * <blockquote><pre>
  39. * dsts[offset].remaining()
  40. * + dsts[offset+1].remaining()
  41. * + ... + dsts[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 read, where
  46. * <tt>0</tt> <tt><=</tt> <i>n</i> <tt><=</tt> <i>r</i>.
  47. * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
  48. * are transferred into buffer <tt>dsts[offset]</tt>, up to the next
  49. * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
  50. * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence
  51. * is transferred into the given buffers. As many bytes as possible are
  52. * transferred into each buffer, hence the final position of each updated
  53. * buffer, except the last updated buffer, is guaranteed to be equal to
  54. * that buffer's limit.
  55. *
  56. * <p> This method may be invoked at any time. If another thread has
  57. * already initiated a read operation upon this channel, however, then an
  58. * invocation of this method will block until the first operation is
  59. * complete. </p>
  60. *
  61. * @param dsts
  62. * The buffers into which bytes are to be transferred
  63. *
  64. * @param offset
  65. * The offset within the buffer array of the first buffer into
  66. * which bytes are to be transferred; must be non-negative and no
  67. * larger than <tt>dsts.length</tt>
  68. *
  69. * @param length
  70. * The maximum number of buffers to be accessed; must be
  71. * non-negative and no larger than
  72. * <tt>dsts.length</tt> - <tt>offset</tt>
  73. *
  74. * @return The number of bytes read, possibly zero,
  75. * or <tt>-1</tt> if the channel has reached end-of-stream
  76. *
  77. * @throws IndexOutOfBoundsException
  78. * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
  79. * parameters do not hold
  80. *
  81. * @throws NonReadableChannelException
  82. * If this channel was not opened for reading
  83. *
  84. * @throws ClosedChannelException
  85. * If this channel is closed
  86. *
  87. * @throws AsynchronousCloseException
  88. * If another thread closes this channel
  89. * while the read operation is in progress
  90. *
  91. * @throws ClosedByInterruptException
  92. * If another thread interrupts the current thread
  93. * while the read operation is in progress, thereby
  94. * closing the channel and setting the current thread's
  95. * interrupt status
  96. *
  97. * @throws IOException
  98. * If some other I/O error occurs
  99. */
  100. public long read(ByteBuffer[] dsts, int offset, int length)
  101. throws IOException;
  102. /**
  103. * Reads a sequence of bytes from this channel into the given buffers.
  104. *
  105. * <p> An invocation of this method of the form <tt>c.read(dsts)</tt>
  106. * behaves in exactly the same manner as the invocation
  107. *
  108. * <blockquote><pre>
  109. * c.read(dsts, 0, srcs.length);</pre></blockquote>
  110. *
  111. * @param dsts
  112. * The buffers into which bytes are to be transferred
  113. *
  114. * @return The number of bytes read, possibly zero,
  115. * or <tt>-1</tt> if the channel has reached end-of-stream
  116. *
  117. * @throws NonReadableChannelException
  118. * If this channel was not opened for reading
  119. *
  120. * @throws ClosedChannelException
  121. * If this channel is closed
  122. *
  123. * @throws AsynchronousCloseException
  124. * If another thread closes this channel
  125. * while the read operation is in progress
  126. *
  127. * @throws ClosedByInterruptException
  128. * If another thread interrupts the current thread
  129. * while the read operation is in progress, thereby
  130. * closing the channel and setting the current thread's
  131. * interrupt status
  132. *
  133. * @throws IOException
  134. * If some other I/O error occurs
  135. */
  136. public long read(ByteBuffer[] dsts) throws IOException;
  137. }