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 java.io; 19 20 import java.util.Arrays; 21 import libcore.io.Streams; 22 23 /** 24 * A readable source of bytes. 25 * 26 * <p>Most clients will use input streams that read data from the file system 27 * ({@link FileInputStream}), the network ({@link java.net.Socket#getInputStream()}/{@link 28 * java.net.HttpURLConnection#getInputStream()}), or from an in-memory byte 29 * array ({@link ByteArrayInputStream}). 30 * 31 * <p>Use {@link InputStreamReader} to adapt a byte stream like this one into a 32 * character stream. 33 * 34 * <p>Most clients should wrap their input stream with {@link 35 * BufferedInputStream}. Callers that do only bulk reads may omit buffering. 36 * 37 * <p>Some implementations support marking a position in the input stream and 38 * resetting back to this position later. Implementations that don't return 39 * false from {@link #markSupported()} and throw an {@link IOException} when 40 * {@link #reset()} is called. 41 * 42 * <h3>Subclassing InputStream</h3> 43 * Subclasses that decorate another input stream should consider subclassing 44 * {@link FilterInputStream}, which delegates all calls to the source input 45 * stream. 46 * 47 * <p>All input stream subclasses should override <strong>both</strong> {@link 48 * #read() read()} and {@link #read(byte[],int,int) read(byte[],int,int)}. The 49 * three argument overload is necessary for bulk access to the data. This is 50 * much more efficient than byte-by-byte access. 51 * 52 * @see OutputStream 53 */ 54 public abstract class InputStream extends Object implements Closeable { 55 56 /** 57 * This constructor does nothing. It is provided for signature 58 * compatibility. 59 */ 60 public InputStream() { 61 /* empty */ 62 } 63 64 /** 65 * Returns an estimated number of bytes that can be read or skipped without blocking for more 66 * input. 67 * 68 * <p>Note that this method provides such a weak guarantee that it is not very useful in 69 * practice. 70 * 71 * <p>Firstly, the guarantee is "without blocking for more input" rather than "without 72 * blocking": a read may still block waiting for I/O to complete — the guarantee is 73 * merely that it won't have to wait indefinitely for data to be written. The result of this 74 * method should not be used as a license to do I/O on a thread that shouldn't be blocked. 75 * 76 * <p>Secondly, the result is a 77 * conservative estimate and may be significantly smaller than the actual number of bytes 78 * available. In particular, an implementation that always returns 0 would be correct. 79 * In general, callers should only use this method if they'd be satisfied with 80 * treating the result as a boolean yes or no answer to the question "is there definitely 81 * data ready?". 82 * 83 * <p>Thirdly, the fact that a given number of bytes is "available" does not guarantee that a 84 * read or skip will actually read or skip that many bytes: they may read or skip fewer. 85 * 86 * <p>It is particularly important to realize that you <i>must not</i> use this method to 87 * size a container and assume that you can read the entirety of the stream without needing 88 * to resize the container. Such callers should probably write everything they read to a 89 * {@link ByteArrayOutputStream} and convert that to a byte array. Alternatively, if you're 90 * reading from a file, {@link File#length} returns the current length of the file (though 91 * assuming the file's length can't change may be incorrect, reading a file is inherently 92 * racy). 93 * 94 * <p>The default implementation of this method in {@code InputStream} always returns 0. 95 * Subclasses should override this method if they are able to indicate the number of bytes 96 * available. 97 * 98 * @return the estimated number of bytes available 99 * @throws IOException if this stream is closed or an error occurs 100 */ 101 public int available() throws IOException { 102 return 0; 103 } 104 105 /** 106 * Closes this stream. Concrete implementations of this class should free 107 * any resources during close. This implementation does nothing. 108 * 109 * @throws IOException 110 * if an error occurs while closing this stream. 111 */ 112 public void close() throws IOException { 113 /* empty */ 114 } 115 116 /** 117 * Sets a mark position in this InputStream. The parameter {@code readlimit} 118 * indicates how many bytes can be read before the mark is invalidated. 119 * Sending {@code reset()} will reposition the stream back to the marked 120 * position provided {@code readLimit} has not been surpassed. 121 * <p> 122 * This default implementation does nothing and concrete subclasses must 123 * provide their own implementation. 124 * 125 * @param readlimit 126 * the number of bytes that can be read from this stream before 127 * the mark is invalidated. 128 * @see #markSupported() 129 * @see #reset() 130 */ 131 public void mark(int readlimit) { 132 /* empty */ 133 } 134 135 /** 136 * Indicates whether this stream supports the {@code mark()} and 137 * {@code reset()} methods. The default implementation returns {@code false}. 138 * 139 * @return always {@code false}. 140 * @see #mark(int) 141 * @see #reset() 142 */ 143 public boolean markSupported() { 144 return false; 145 } 146 147 /** 148 * Reads a single byte from this stream and returns it as an integer in the 149 * range from 0 to 255. Returns -1 if the end of the stream has been 150 * reached. Blocks until one byte has been read, the end of the source 151 * stream is detected or an exception is thrown. 152 * 153 * @throws IOException 154 * if the stream is closed or another IOException occurs. 155 */ 156 public abstract int read() throws IOException; 157 158 /** 159 * Equivalent to {@code read(buffer, 0, buffer.length)}. 160 */ 161 public int read(byte[] buffer) throws IOException { 162 return read(buffer, 0, buffer.length); 163 } 164 165 /** 166 * Reads up to {@code byteCount} bytes from this stream and stores them in 167 * the byte array {@code buffer} starting at {@code byteOffset}. 168 * Returns the number of bytes actually read or -1 if the end of the stream 169 * has been reached. 170 * 171 * @throws IndexOutOfBoundsException 172 * if {@code byteOffset < 0 || byteCount < 0 || byteOffset + byteCount > buffer.length}. 173 * @throws IOException 174 * if the stream is closed or another IOException occurs. 175 */ 176 public int read(byte[] buffer, int byteOffset, int byteCount) throws IOException { 177 Arrays.checkOffsetAndCount(buffer.length, byteOffset, byteCount); 178 for (int i = 0; i < byteCount; ++i) { 179 int c; 180 try { 181 if ((c = read()) == -1) { 182 return i == 0 ? -1 : i; 183 } 184 } catch (IOException e) { 185 if (i != 0) { 186 return i; 187 } 188 throw e; 189 } 190 buffer[byteOffset + i] = (byte) c; 191 } 192 return byteCount; 193 } 194 195 /** 196 * Resets this stream to the last marked location. Throws an 197 * {@code IOException} if the number of bytes read since the mark has been 198 * set is greater than the limit provided to {@code mark}, or if no mark 199 * has been set. 200 * <p> 201 * This implementation always throws an {@code IOException} and concrete 202 * subclasses should provide the proper implementation. 203 * 204 * @throws IOException 205 * if this stream is closed or another IOException occurs. 206 */ 207 public synchronized void reset() throws IOException { 208 throw new IOException(); 209 } 210 211 /** 212 * Skips at most {@code n} bytes in this stream. This method does nothing and returns 213 * 0 if {@code n} is negative, but some subclasses may throw. 214 * 215 * <p>Note the "at most" in the description of this method: this method may choose to skip 216 * fewer bytes than requested. Callers should <i>always</i> check the return value. 217 * 218 * <p>This default implementation reads bytes into a temporary 219 * buffer. Concrete subclasses should provide their own implementation. 220 * 221 * @param byteCount the number of bytes to skip. 222 * @return the number of bytes actually skipped. 223 * @throws IOException 224 * if this stream is closed or another IOException occurs. 225 */ 226 public long skip(long byteCount) throws IOException { 227 return Streams.skipByReading(this, byteCount); 228 } 229 } 230
