View Javadoc

1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one or more
3    *  contributor license agreements.  See the NOTICE file distributed with
4    *  this work for additional information regarding copyright ownership.
5    *  The ASF licenses this file to You under the Apache License, Version 2.0
6    *  (the "License"); you may not use this file except in compliance with
7    *  the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  package org.helyx.basics4me.io;
19  
20  import java.io.IOException;
21  import java.io.InputStream;
22  
23  /**
24   * FilteredInputStream is a class which takes an input stream and
25   * <em>filters</em> the input in some way. The filtered view may be a buffered
26   * view or one which uncompresses data before returning bytes read.
27   * FilterInputStreams are meant for byte streams.
28   * 
29   */
30  public class FilterInputStream extends InputStream {
31  
32      /**
33       * The target InputStream which is being filtered.
34       */
35      protected InputStream in;
36  
37      /**
38       * Constructs a new FilterInputStream on the InputStream <code>in</code>.
39       * All reads are now filtered through this stream.
40       * 
41       * @param in
42       *            The non-null InputStream to filter reads on.
43       */
44      protected FilterInputStream(InputStream in) {
45          super();
46          this.in = in;
47      }
48  
49      /**
50       * Answers a int representing the number of bytes that are available before
51       * this FilterInputStream will block. This method returns the number of
52       * bytes available in the target stream.
53       * 
54       * @return the number of bytes available before blocking.
55       * 
56       * @throws IOException
57       *             If an error occurs in this stream.
58       */
59  
60      public int available() throws IOException {
61          return in.available();
62      }
63  
64      /**
65       * Close this FilterInputStream. This implementation closes the target
66       * stream.
67       * 
68       * @throws IOException
69       *             If an error occurs attempting to close this stream.
70       */
71  
72      public void close() throws IOException {
73          in.close();
74      }
75  
76      /**
77       * Set a Mark position in this FilterInputStream. The parameter
78       * <code>readLimit</code> indicates how many bytes can be read before a
79       * mark is invalidated. Sending reset() will reposition the Stream back to
80       * the marked position provided <code>readLimit</code> has not been
81       * surpassed.
82       * <p>
83       * This implementation sets a mark in the target stream.
84       * 
85       * @param readlimit
86       *            the number of bytes to be able to read before invalidating the
87       *            mark.
88       */
89  
90      public synchronized void mark(int readlimit) {
91          in.mark(readlimit);
92      }
93  
94      /**
95       * Answers a boolean indicating whether or not this FilterInputStream
96       * supports mark() and reset(). This implementation answers whether or not
97       * the target stream supports marking.
98       * 
99       * @return <code>true</code> if mark() and reset() are supported,
100      *         <code>false</code> otherwise.
101      */
102 
103     public boolean markSupported() {
104         return in.markSupported();
105     }
106 
107     /**
108      * Reads a single byte from this FilterInputStream and returns the result as
109      * an int. The low-order byte is returned or -1 of the end of stream was
110      * encountered. This implementation returns a byte from the target stream.
111      * 
112      * @return the byte read or -1 if end of stream.
113      * 
114      * @throws IOException
115      *             If the stream is already closed or another IOException
116      *             occurs.
117      */
118 
119     public int read() throws IOException {
120         return in.read();
121     }
122 
123     /**
124      * Reads bytes from this FilterInputStream and stores them in byte array
125      * <code>buffer</code>. Answer the number of bytes actually read or -1 if
126      * no bytes were read and end of stream was encountered. This implementation
127      * reads bytes from the target stream.
128      * 
129      * @param buffer
130      *            the byte array in which to store the read bytes.
131      * @return the number of bytes actually read or -1 if end of stream.
132      * 
133      * @throws IOException
134      *             If the stream is already closed or another IOException
135      *             occurs.
136      */
137 
138     public int read(byte[] buffer) throws IOException {
139         return read(buffer, 0, buffer.length);
140     }
141 
142     /**
143      * Reads at most <code>count</code> bytes from this FilterInputStream and
144      * stores them in byte array <code>buffer</code> starting at
145      * <code>offset</code>. Answer the number of bytes actually read or -1 if
146      * no bytes were read and end of stream was encountered. This implementation
147      * reads bytes from the target stream.
148      * 
149      * @param buffer
150      *            the byte array in which to store the read bytes.
151      * @param offset
152      *            the offset in <code>buffer</code> to store the read bytes.
153      * @param count
154      *            the maximum number of bytes to store in <code>buffer</code>.
155      * @return the number of bytes actually read or -1 if end of stream.
156      * 
157      * @throws IOException
158      *             If the stream is already closed or another IOException
159      *             occurs.
160      */
161 
162     public int read(byte[] buffer, int offset, int count) throws IOException {
163         return in.read(buffer, offset, count);
164     }
165 
166     /**
167      * Reset this FilterInputStream to the last marked location. If the
168      * <code>readlimit</code> has been passed or no <code>mark</code> has
169      * been set, throw IOException. This implementation resets the target
170      * stream.
171      * 
172      * @throws IOException
173      *             If the stream is already closed or another IOException
174      *             occurs.
175      */
176 
177     public synchronized void reset() throws IOException {
178         in.reset();
179     }
180 
181     /**
182      * Skips <code>count</code> number of bytes in this InputStream.
183      * Subsequent <code>read()</code>'s will not return these bytes unless
184      * <code>reset()</code> is used. This implementation skips
185      * <code>count</code> number of bytes in the target stream.
186      * 
187      * @param count
188      *            the number of bytes to skip.
189      * @return the number of bytes actually skipped.
190      * 
191      * @throws IOException
192      *             If the stream is already closed or another IOException
193      *             occurs.
194      */
195 
196     public long skip(long count) throws IOException {
197         return in.skip(count);
198     }
199 }