001: /*
002: * @(#)FilterInputStream.java 1.30 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.io;
029:
030: /**
031: * A <code>FilterInputStream</code> contains
032: * some other input stream, which it uses as
033: * its basic source of data, possibly transforming
034: * the data along the way or providing additional
035: * functionality. The class <code>FilterInputStream</code>
036: * itself simply overrides all methods of
037: * <code>InputStream</code> with versions that
038: * pass all requests to the contained input
039: * stream. Subclasses of <code>FilterInputStream</code>
040: * may further override some of these methods
041: * and may also provide additional methods
042: * and fields.
043: *
044: * @author Jonathan Payne
045: * @version 1.23, 02/02/00
046: * @since JDK1.0
047: */
048: public class FilterInputStream extends InputStream {
049: /**
050: * The input stream to be filtered.
051: */
052: protected InputStream in;
053:
054: /**
055: * Creates a <code>FilterInputStream</code>
056: * by assigning the argument <code>in</code>
057: * to the field <code>this.in</code> so as
058: * to remember it for later use.
059: *
060: * @param in the underlying input stream, or <code>null</code> if
061: * this instance is to be created without an underlying stream.
062: */
063: protected FilterInputStream(InputStream in) {
064: this .in = in;
065: }
066:
067: /**
068: * Reads the next byte of data from this input stream. The value
069: * byte is returned as an <code>int</code> in the range
070: * <code>0</code> to <code>255</code>. If no byte is available
071: * because the end of the stream has been reached, the value
072: * <code>-1</code> is returned. This method blocks until input data
073: * is available, the end of the stream is detected, or an exception
074: * is thrown.
075: * <p>
076: * This method
077: * simply performs <code>in.read()</code> and returns the result.
078: *
079: * @return the next byte of data, or <code>-1</code> if the end of the
080: * stream is reached.
081: * @exception IOException if an I/O error occurs.
082: * @see java.io.FilterInputStream#in
083: */
084: public int read() throws IOException {
085: return in.read();
086: }
087:
088: /**
089: * Reads up to <code>byte.length</code> bytes of data from this
090: * input stream into an array of bytes. This method blocks until some
091: * input is available.
092: * <p>
093: * This method simply performs the call
094: * <code>read(b, 0, b.length)</code> and returns
095: * the result. It is important that it does
096: * <i>not</i> do <code>in.read(b)</code> instead;
097: * certain subclasses of <code>FilterInputStream</code>
098: * depend on the implementation strategy actually
099: * used.
100: *
101: * @param b the buffer into which the data is read.
102: * @return the total number of bytes read into the buffer, or
103: * <code>-1</code> if there is no more data because the end of
104: * the stream has been reached.
105: * @exception IOException if an I/O error occurs.
106: * @see java.io.FilterInputStream#read(byte[], int, int)
107: */
108: public int read(byte b[]) throws IOException {
109: return read(b, 0, b.length);
110: }
111:
112: /**
113: * Reads up to <code>len</code> bytes of data from this input stream
114: * into an array of bytes. This method blocks until some input is
115: * available.
116: * <p>
117: * This method simply performs <code>in.read(b, off, len)</code>
118: * and returns the result.
119: *
120: * @param b the buffer into which the data is read.
121: * @param off the start offset of the data.
122: * @param len the maximum number of bytes read.
123: * @return the total number of bytes read into the buffer, or
124: * <code>-1</code> if there is no more data because the end of
125: * the stream has been reached.
126: * @exception IOException if an I/O error occurs.
127: * @see java.io.FilterInputStream#in
128: */
129: public int read(byte b[], int off, int len) throws IOException {
130: return in.read(b, off, len);
131: }
132:
133: /**
134: * Skips over and discards <code>n</code> bytes of data from the
135: * input stream. The <code>skip</code> method may, for a variety of
136: * reasons, end up skipping over some smaller number of bytes,
137: * possibly <code>0</code>. The actual number of bytes skipped is
138: * returned.
139: * <p>
140: * This method
141: * simply performs <code>in.skip(n)</code>.
142: *
143: * @param n the number of bytes to be skipped.
144: * @return the actual number of bytes skipped.
145: * @exception IOException if an I/O error occurs.
146: */
147: public long skip(long n) throws IOException {
148: return in.skip(n);
149: }
150:
151: /**
152: * Returns the number of bytes that can be read from this input
153: * stream without blocking.
154: * <p>
155: * This method
156: * simply performs <code>in.available()</code> and
157: * returns the result.
158: *
159: * @return the number of bytes that can be read from the input stream
160: * without blocking.
161: * @exception IOException if an I/O error occurs.
162: * @see java.io.FilterInputStream#in
163: */
164: public int available() throws IOException {
165: return in.available();
166: }
167:
168: /**
169: * Closes this input stream and releases any system resources
170: * associated with the stream.
171: * This
172: * method simply performs <code>in.close()</code>.
173: *
174: * @exception IOException if an I/O error occurs.
175: * @see java.io.FilterInputStream#in
176: */
177: public void close() throws IOException {
178: in.close();
179: }
180:
181: /**
182: * Marks the current position in this input stream. A subsequent
183: * call to the <code>reset</code> method repositions this stream at
184: * the last marked position so that subsequent reads re-read the same bytes.
185: * <p>
186: * The <code>readlimit</code> argument tells this input stream to
187: * allow that many bytes to be read before the mark position gets
188: * invalidated.
189: * <p>
190: * This method simply performs <code>in.mark(readlimit)</code>.
191: *
192: * @param readlimit the maximum limit of bytes that can be read before
193: * the mark position becomes invalid.
194: * @see java.io.FilterInputStream#in
195: * @see java.io.FilterInputStream#reset()
196: */
197: public synchronized void mark(int readlimit) {
198: in.mark(readlimit);
199: }
200:
201: /**
202: * Repositions this stream to the position at the time the
203: * <code>mark</code> method was last called on this input stream.
204: * <p>
205: * This method
206: * simply performs <code>in.reset()</code>.
207: * <p>
208: * Stream marks are intended to be used in
209: * situations where you need to read ahead a little to see what's in
210: * the stream. Often this is most easily done by invoking some
211: * general parser. If the stream is of the type handled by the
212: * parse, it just chugs along happily. If the stream is not of
213: * that type, the parser should toss an exception when it fails.
214: * If this happens within readlimit bytes, it allows the outer
215: * code to reset the stream and try another parser.
216: *
217: * @exception IOException if the stream has not been marked or if the
218: * mark has been invalidated.
219: * @see java.io.FilterInputStream#in
220: * @see java.io.FilterInputStream#mark(int)
221: */
222: public synchronized void reset() throws IOException {
223: in.reset();
224: }
225:
226: /**
227: * Tests if this input stream supports the <code>mark</code>
228: * and <code>reset</code> methods.
229: * This method
230: * simply performs <code>in.markSupported()</code>.
231: *
232: * @return <code>true</code> if this stream type supports the
233: * <code>mark</code> and <code>reset</code> method;
234: * <code>false</code> otherwise.
235: * @see java.io.FilterInputStream#in
236: * @see java.io.InputStream#mark(int)
237: * @see java.io.InputStream#reset()
238: */
239: public boolean markSupported() {
240: return in.markSupported();
241: }
242: }
|