1. /*
  2. * @(#)FilterInputStream.java 1.22 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.io;
  8. /**
  9. * A <code>FilterInputStream</code> contains
  10. * some other input stream, which it uses as
  11. * its basic source of data, possibly transforming
  12. * the data along the way or providing additional
  13. * functionality. The class <code>FilterInputStream</code>
  14. * itself simply overrides all methods of
  15. * <code>InputStream</code> with versions that
  16. * pass all requests to the contained input
  17. * stream. Subclasses of <code>FilterInputStream</code>
  18. * may further override some of these methods
  19. * and may also provide additional methods
  20. * and fields.
  21. *
  22. * @author Jonathan Payne
  23. * @version 1.22, 11/29/01
  24. * @since JDK1.0
  25. */
  26. public
  27. class FilterInputStream extends InputStream {
  28. /**
  29. * The input stream to be filtered.
  30. */
  31. protected InputStream in;
  32. /**
  33. * Creates a <code>FilterInputStream</code>
  34. * by assigning the argument <code>in</code>
  35. * to the field <code>this.in</code> so as
  36. * to remember it for later use.
  37. *
  38. * @param in the underlying input stream, or <code>null</code> if
  39. * this instance is to be created without an underlying stream.
  40. */
  41. protected FilterInputStream(InputStream in) {
  42. this.in = in;
  43. }
  44. /**
  45. * Reads the next byte of data from this input stream. The value
  46. * byte is returned as an <code>int</code> in the range
  47. * <code>0</code> to <code>255</code>. If no byte is available
  48. * because the end of the stream has been reached, the value
  49. * <code>-1</code> is returned. This method blocks until input data
  50. * is available, the end of the stream is detected, or an exception
  51. * is thrown.
  52. * <p>
  53. * This method
  54. * simply performs <code>in.read()</code> and returns the result.
  55. *
  56. * @return the next byte of data, or <code>-1</code> if the end of the
  57. * stream is reached.
  58. * @exception IOException if an I/O error occurs.
  59. * @see java.io.FilterInputStream#in
  60. */
  61. public int read() throws IOException {
  62. return in.read();
  63. }
  64. /**
  65. * Reads up to <code>byte.length</code> bytes of data from this
  66. * input stream into an array of bytes. This method blocks until some
  67. * input is available.
  68. * <p>
  69. * This method simply performs the call
  70. * <code>read(b, 0, b.length)</code> and returns
  71. * the result. It is important that it does
  72. * <i>not</i> do <code>in.read(b)</code> instead;
  73. * certain subclasses of <code>FilterInputStream</code>
  74. * depend on the implementation strategy actually
  75. * used.
  76. *
  77. * @param b the buffer into which the data is read.
  78. * @return the total number of bytes read into the buffer, or
  79. * <code>-1</code> if there is no more data because the end of
  80. * the stream has been reached.
  81. * @exception IOException if an I/O error occurs.
  82. * @see java.io.FilterInputStream#read(byte[], int, int)
  83. */
  84. public int read(byte b[]) throws IOException {
  85. return read(b, 0, b.length);
  86. }
  87. /**
  88. * Reads up to <code>len</code> bytes of data from this input stream
  89. * into an array of bytes. This method blocks until some input is
  90. * available.
  91. * <p>
  92. * This method simply performs <code>in.read(b, off, len)</code>
  93. * and returns the result.
  94. *
  95. * @param b the buffer into which the data is read.
  96. * @param off the start offset of the data.
  97. * @param len the maximum number of bytes read.
  98. * @return the total number of bytes read into the buffer, or
  99. * <code>-1</code> if there is no more data because the end of
  100. * the stream has been reached.
  101. * @exception IOException if an I/O error occurs.
  102. * @see java.io.FilterInputStream#in
  103. */
  104. public int read(byte b[], int off, int len) throws IOException {
  105. return in.read(b, off, len);
  106. }
  107. /**
  108. * Skips over and discards <code>n</code> bytes of data from the
  109. * input stream. The <code>skip</code> method may, for a variety of
  110. * reasons, end up skipping over some smaller number of bytes,
  111. * possibly <code>0</code>. The actual number of bytes skipped is
  112. * returned.
  113. * <p>
  114. * This method
  115. * simply performs <code>in.skip(n)</code>.
  116. *
  117. * @param n the number of bytes to be skipped.
  118. * @return the actual number of bytes skipped.
  119. * @exception IOException if an I/O error occurs.
  120. */
  121. public long skip(long n) throws IOException {
  122. return in.skip(n);
  123. }
  124. /**
  125. * Returns the number of bytes that can be read from this input
  126. * stream without blocking.
  127. * <p>
  128. * This method
  129. * simply performs <code>in.available(n)</code> and
  130. * returns the result.
  131. *
  132. * @return the number of bytes that can be read from the input stream
  133. * without blocking.
  134. * @exception IOException if an I/O error occurs.
  135. * @see java.io.FilterInputStream#in
  136. */
  137. public int available() throws IOException {
  138. return in.available();
  139. }
  140. /**
  141. * Closes this input stream and releases any system resources
  142. * associated with the stream.
  143. * This
  144. * method simply performs <code>in.close()</code>.
  145. *
  146. * @exception IOException if an I/O error occurs.
  147. * @see java.io.FilterInputStream#in
  148. */
  149. public void close() throws IOException {
  150. in.close();
  151. }
  152. /**
  153. * Marks the current position in this input stream. A subsequent
  154. * call to the <code>reset</code> method repositions this stream at
  155. * the last marked position so that subsequent reads re-read the same bytes.
  156. * <p>
  157. * The <code>readlimit</code> argument tells this input stream to
  158. * allow that many bytes to be read before the mark position gets
  159. * invalidated.
  160. * <p>
  161. * This method simply performs <code>in.mark(readlimit)</code>.
  162. *
  163. * @param readlimit the maximum limit of bytes that can be read before
  164. * the mark position becomes invalid.
  165. * @see java.io.FilterInputStream#in
  166. * @see java.io.FilterInputStream#reset()
  167. */
  168. public synchronized void mark(int readlimit) {
  169. in.mark(readlimit);
  170. }
  171. /**
  172. * Repositions this stream to the position at the time the
  173. * <code>mark</code> method was last called on this input stream.
  174. * <p>
  175. * This method
  176. * simply performs <code>in.reset()</code>.
  177. * <p>
  178. * Stream marks are intended to be used in
  179. * situations where you need to read ahead a little to see what's in
  180. * the stream. Often this is most easily done by invoking some
  181. * general parser. If the stream is of the type handled by the
  182. * parse, it just chugs along happily. If the stream is not of
  183. * that type, the parser should toss an exception when it fails.
  184. * If this happens within readlimit bytes, it allows the outer
  185. * code to reset the stream and try another parser.
  186. *
  187. * @exception IOException if the stream has not been marked or if the
  188. * mark has been invalidated.
  189. * @see java.io.FilterInputStream#in
  190. * @see java.io.FilterInputStream#mark(int)
  191. */
  192. public synchronized void reset() throws IOException {
  193. in.reset();
  194. }
  195. /**
  196. * Tests if this input stream supports the <code>mark</code>
  197. * and <code>reset</code> methods.
  198. * This method
  199. * simply performs <code>in.markSupported()</code>.
  200. *
  201. * @return <code>true</code> if this stream type supports the
  202. * <code>mark</code> and <code>reset</code> method;
  203. * <code>false</code> otherwise.
  204. * @see java.io.FilterInputStream#in
  205. * @see java.io.InputStream#mark(int)
  206. * @see java.io.InputStream#reset()
  207. */
  208. public boolean markSupported() {
  209. return in.markSupported();
  210. }
  211. }