KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > FilterInputStream


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