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 @Override public int read(byte[] buffer, int byteOffset, int byteCount) throws IOException { 118 return in.read(buffer, byteOffset, byteCount); 119 } 120 121 /** 122 * Resets this stream to the last marked location. This implementation 123 * resets the target stream. 124 * 125 * @throws IOException 126 * if this stream is already closed, no mark has been set or the 127 * mark is no longer valid because more than {@code readlimit} 128 * bytes have been read since setting the mark. 129 * @see #mark(int) 130 * @see #markSupported() 131 */ 132 @Override 133 public synchronized void reset() throws IOException { 134 in.reset(); 135 } 136 137 /** 138 * Skips {@code byteCount} bytes in this stream. Subsequent 139 * calls to {@code read} will not return these bytes unless {@code reset} is 140 * used. This implementation skips {@code byteCount} bytes in the 141 * filtered stream. 142 * 143 * @return the number of bytes actually skipped. 144 * @throws IOException 145 * if this stream is closed or another IOException occurs. 146 * @see #mark(int) 147 * @see #reset() 148 */ 149 @Override 150 public long skip(long byteCount) throws IOException { 151 return in.skip(byteCount); 152 } 153} 154