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 */ 30public class FilterInputStream extends InputStream { 31 32 /** 33 * The source input stream that is filtered. 34 */ 35 protected volatile InputStream in; 36 37 /** 38 * Constructs a new {@code FilterInputStream} with the specified input 39 * stream as source. 40 * 41 * <p><strong>Warning:</strong> passing a null source creates an invalid 42 * {@code FilterInputStream}, that fails on every method that is not 43 * overridden. Subclasses should check for null in their constructors. 44 * 45 * @param in the input stream to filter reads on. 46 */ 47 protected FilterInputStream(InputStream in) { 48 this.in = in; 49 } 50 51 @Override 52 public int available() throws IOException { 53 return in.available(); 54 } 55 56 /** 57 * Closes this stream. This implementation closes the filtered stream. 58 * 59 * @throws IOException 60 * if an error occurs while closing this stream. 61 */ 62 @Override 63 public void close() throws IOException { 64 in.close(); 65 } 66 67 /** 68 * Sets a mark position in this stream. The parameter {@code readlimit} 69 * indicates how many bytes can be read before the mark is invalidated. 70 * Sending {@code reset()} will reposition this stream back to the marked 71 * position, provided that {@code readlimit} has not been surpassed. 72 * <p> 73 * This implementation sets a mark in the filtered stream. 74 * 75 * @param readlimit 76 * the number of bytes that can be read from this stream before 77 * the mark is invalidated. 78 * @see #markSupported() 79 * @see #reset() 80 */ 81 @Override 82 public synchronized void mark(int readlimit) { 83 in.mark(readlimit); 84 } 85 86 /** 87 * Indicates whether this stream supports {@code mark()} and {@code reset()}. 88 * This implementation returns whether or not the filtered stream supports 89 * marking. 90 * 91 * @return {@code true} if {@code mark()} and {@code reset()} are supported, 92 * {@code false} otherwise. 93 * @see #mark(int) 94 * @see #reset() 95 * @see #skip(long) 96 */ 97 @Override 98 public boolean markSupported() { 99 return in.markSupported(); 100 } 101 102 /** 103 * Reads a single byte from the filtered stream and returns it as an integer 104 * in the range from 0 to 255. Returns -1 if the end of this stream has been 105 * reached. 106 * 107 * @return the byte read or -1 if the end of the filtered stream has been 108 * reached. 109 * @throws IOException 110 * if the stream is closed or another IOException occurs. 111 */ 112 @Override 113 public int read() throws IOException { 114 return in.read(); 115 } 116 117 /** 118 * Reads at most {@code count} bytes from this stream and stores them in the 119 * byte array {@code buffer} starting at {@code offset}. Returns the number 120 * of bytes actually read or -1 if no bytes have been read and the end of 121 * this stream has been reached. This implementation reads bytes from the 122 * filtered stream. 123 * 124 * @param buffer 125 * the byte array in which to store the bytes read. 126 * @param offset 127 * the initial position in {@code buffer} to store the bytes 128 * read from this stream. 129 * @param count 130 * the maximum number of bytes to store in {@code buffer}. 131 * @return the number of bytes actually read or -1 if the end of the 132 * filtered stream has been reached while reading. 133 * @throws IOException 134 * if this stream is closed or another I/O error occurs. 135 */ 136 @Override 137 public int read(byte[] buffer, int offset, int count) throws IOException { 138 return in.read(buffer, offset, count); 139 } 140 141 /** 142 * Resets this stream to the last marked location. This implementation 143 * resets the target stream. 144 * 145 * @throws IOException 146 * if this stream is already closed, no mark has been set or the 147 * mark is no longer valid because more than {@code readlimit} 148 * bytes have been read since setting the mark. 149 * @see #mark(int) 150 * @see #markSupported() 151 */ 152 @Override 153 public synchronized void reset() throws IOException { 154 in.reset(); 155 } 156 157 /** 158 * Skips {@code byteCount} bytes in this stream. Subsequent 159 * calls to {@code read} will not return these bytes unless {@code reset} is 160 * used. This implementation skips {@code byteCount} bytes in the 161 * filtered stream. 162 * 163 * @return the number of bytes actually skipped. 164 * @throws IOException 165 * if this stream is closed or another IOException occurs. 166 * @see #mark(int) 167 * @see #reset() 168 */ 169 @Override 170 public long skip(long byteCount) throws IOException { 171 return in.skip(byteCount); 172 } 173} 174