← Back to branch summary

~psmay/+junk/java-iomux

« back to all changes in this revision

Viewing changes to src/us/wxy/iomux/ByteIOInput.java

  • Committer: Peter S. May
  • Date: 2013-04-14 22:07:54 UTC
  • Revision ID: peter_s._may_httppsmay.com-20130414220754-gq0q8p3jo7f1jsy4
BlockingByteInput, and I think this one might actually work.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/us/wxy/iomux/ByteIOInput.java
25
25
 
26
26
 
27
27
/**
28
 
 * An analogue to {@link ByteInput}, but with the added implication that a call requesting a
29
 
 * length of greater than zero will block until at least one byte is available for read.
 
28
 * An analogue to {@link ByteInput}, but with the added implication that a call requesting a length
 
29
 * of greater than zero will block until at least one byte is available for read.
30
30
 * <p>
31
31
 * Each overload of {@code readBytes} returns the number of bytes copied. Unless the requested
32
32
 * length is 0, the return value should never be 0 unless the end of data has been permanently
40
40
 */
41
41
public interface ByteIOInput {
42
42
 
 
43
  /**
 
44
   * Reads data out of this object into an array.
 
45
   * 
 
46
   * @param dest An array to copy data into
 
47
   * @param offset The start index of {@code dest} to begin copying
 
48
   * @param length The maximum number of bytes to attempt to copy
 
49
   * @return The number of bytes actually copied, which may be {@code length} or less, if less data
 
50
   *         is available, or 0 only if either {@code length} is 0 or no more data can be read
 
51
   * @throws IOException If an I/O error occurs while waiting for data
 
52
   */
43
53
  public abstract int readBytes(byte[] dest, int offset, int length) throws IOException;
44
54
 
 
55
  /**
 
56
   * Reads data out of this object into a {@link ByteArrayOutput}. This is equivalent to
 
57
   * {@code readBytes(dest, Integer.MAX_VALUE)}.
 
58
   * 
 
59
   * @param dest An {@link ByteArrayOutput} to copy data into
 
60
   * @return The number of bytes actually copied, which is 0 only if no more data can be read
 
61
   * @throws IOException If an I/O error occurs while waiting for data
 
62
   */
45
63
  public abstract int readBytes(ByteArrayOutput dest) throws IOException;
46
64
 
 
65
  /**
 
66
   * Reads data out of this object into a {@link ByteArrayOutput}.
 
67
   * 
 
68
   * @param dest An {@link ByteArrayOutput} to copy data into
 
69
   * @param length The maximum number of bytes to attempt to copy
 
70
   * @return The number of bytes actually copied, which may be {@code length} or less, if less data
 
71
   *         is available, or 0 only if either {@code length} is 0 or no more data can be read
 
72
   * @throws IOException If an I/O error occurs while waiting for data
 
73
   */
47
74
  public abstract int readBytes(ByteArrayOutput dest, int length) throws IOException;
48
75
 
 
76
  /**
 
77
   * Reads data out of this object into an output stream. This is equivalent to
 
78
   * {@code readBytes(dest, Integer.MAX_VALUE)}.
 
79
   * 
 
80
   * @param dest An {@link OutputStream} to copy data into
 
81
   * @return The number of bytes actually copied, which is 0 only if no more data can be read
 
82
   * @throws IOException If an I/O error occurs while waiting for data or writing to {@code dest}
 
83
   */
49
84
  public abstract int readBytes(OutputStream dest) throws IOException;
50
85
 
 
86
  /**
 
87
   * Reads data out of this object into an output stream.
 
88
   * 
 
89
   * @param dest An {@link OutputStream} to copy data into
 
90
   * @param length The maximum number of bytes to attempt to copy
 
91
   * @return The number of bytes actually copied, which may be {@code length} or less, if less data
 
92
   *         is available, or 0 only if either {@code length} is 0 or no more data can be read
 
93
   * @throws IOException If an I/O error occurs while waiting for data or writing to {@code dest}
 
94
   */
51
95
  public abstract int readBytes(OutputStream dest, int length) throws IOException;
52
 
 
53
96
}