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 18package java.io; 19 20/** 21 * Wraps an existing {@link InputStream} and performs some transformation on 22 * the input data while it is being read. Transformations can be anything from a 23 * simple byte-wise filtering input data to an on-the-fly compression or 24 * decompression of the underlying stream. Input streams that wrap another input 25 * stream and provide some additional functionality on top of it usually inherit 26 * from this class. 27 * 28 * @see FilterOutputStream 29 * 30 * @since Android 1.0 31 */ 32public class FilterInputStream extends InputStream { 33 34 // BEGIN android-changed 35 // The underlying input stream address should not be cached in a register. 36 // This was changed to be more close to the RI. 37 /** 38 * The source input stream that is filtered. 39 * 40 * @since Android 1.0 41 */ 42 protected volatile InputStream in; 43 // END android-changed 44 45 /** 46 * Constructs a new {@code FilterInputStream} with the specified input 47 * stream as source. 48 * 49 * @param in 50 * the non-null InputStream to filter reads on. 51 * @since Android 1.0 52 */ 53 protected FilterInputStream(InputStream in) { 54 super(); 55 this.in = in; 56 } 57 58 /** 59 * Returns the number of bytes that are available before this stream will 60 * block. 61 * 62 * @return the number of bytes available before blocking. 63 * @throws IOException 64 * if an error occurs in this stream. 65 * @since Android 1.0 66 */ 67 @Override 68 public int available() throws IOException { 69 return in.available(); 70 } 71 72 /** 73 * Closes this stream. This implementation closes the filtered stream. 74 * 75 * @throws IOException 76 * if an error occurs while closing this stream. 77 * @since Android 1.0 78 */ 79 @Override 80 public void close() throws IOException { 81 in.close(); 82 } 83 84 /** 85 * Sets a mark position in this stream. The parameter {@code readlimit} 86 * indicates how many bytes can be read before the mark is invalidated. 87 * Sending {@code reset()} will reposition this stream back to the marked 88 * position, provided that {@code readlimit} has not been surpassed. 89 * <p> 90 * This implementation sets a mark in the filtered stream. 91 * </p> 92 * 93 * @param readlimit 94 * the number of bytes that can be read from this stream before 95 * the mark is invalidated. 96 * @see #markSupported() 97 * @see #reset() 98 * @since Android 1.0 99 */ 100 @Override 101 public synchronized void mark(int readlimit) { 102 in.mark(readlimit); 103 } 104 105 /** 106 * Indicates whether this stream supports {@code mark()} and {@code reset()}. 107 * This implementation returns whether or not the filtered stream supports 108 * marking. 109 * 110 * @return {@code true} if {@code mark()} and {@code reset()} are supported, 111 * {@code false} otherwise. 112 * @see #mark(int) 113 * @see #reset() 114 * @see #skip(long) 115 * @since Android 1.0 116 */ 117 @Override 118 public boolean markSupported() { 119 return in.markSupported(); 120 } 121 122 /** 123 * Reads a single byte from the filtered stream and returns it as an integer 124 * in the range from 0 to 255. Returns -1 if the end of this stream has been 125 * reached. 126 * 127 * @return the byte read or -1 if the end of the filtered stream has been 128 * reached. 129 * @throws IOException 130 * if the stream is closed or another IOException occurs. 131 * @since Android 1.0 132 */ 133 @Override 134 public int read() throws IOException { 135 return in.read(); 136 } 137 138 /** 139 * Reads bytes from this stream and stores them in the byte array 140 * {@code buffer}. Returns the number of bytes actually read or -1 if no 141 * bytes were read and the end of this stream was encountered. This 142 * implementation reads bytes from the filtered stream. 143 * 144 * @param buffer 145 * the byte array in which to store the read bytes. 146 * @return the number of bytes actually read or -1 if the end of the 147 * filtered stream has been reached while reading. 148 * @throws IOException 149 * if this stream is closed or another IOException occurs. 150 * @since Android 1.0 151 */ 152 @Override 153 public int read(byte[] buffer) throws IOException { 154 return read(buffer, 0, buffer.length); 155 } 156 157 /** 158 * Reads at most {@code count} bytes from this stream and stores them in the 159 * byte array {@code buffer} starting at {@code offset}. Returns the number 160 * of bytes actually read or -1 if no bytes have been read and the end of 161 * this stream has been reached. This implementation reads bytes from the 162 * filtered stream. 163 * 164 * @param buffer 165 * the byte array in which to store the bytes read. 166 * @param offset 167 * the initial position in {@code buffer} to store the bytes 168 * read from this stream. 169 * @param count 170 * the maximum number of bytes to store in {@code buffer}. 171 * @return the number of bytes actually read or -1 if the end of the 172 * filtered stream has been reached while reading. 173 * @throws IOException 174 * if this stream is closed or another I/O error occurs. 175 * @since Android 1.0 176 */ 177 @Override 178 public int read(byte[] buffer, int offset, int count) throws IOException { 179 return in.read(buffer, offset, count); 180 } 181 182 /** 183 * Resets this stream to the last marked location. This implementation 184 * resets the target stream. 185 * 186 * @throws IOException 187 * if this stream is already closed, no mark has been set or the 188 * mark is no longer valid because more than {@code readlimit} 189 * bytes have been read since setting the mark. 190 * @see #mark(int) 191 * @see #markSupported() 192 * @since Android 1.0 193 */ 194 @Override 195 public synchronized void reset() throws IOException { 196 in.reset(); 197 } 198 199 /** 200 * Skips {@code count} number of bytes in this stream. Subsequent 201 * {@code read()}'s will not return these bytes unless {@code reset()} is 202 * used. This implementation skips {@code count} number of bytes in the 203 * filtered stream. 204 * 205 * @param count 206 * the number of bytes to skip. 207 * @return the number of bytes actually skipped. 208 * @throws IOException 209 * if this stream is closed or another IOException occurs. 210 * @see #mark(int) 211 * @see #reset() 212 * @since Android 1.0 213 */ 214 @Override 215 public long skip(long count) throws IOException { 216 return in.skip(count); 217 } 218} 219 220