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
20import java.util.Arrays;
21import 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 */
54public 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&nbsp;&mdash; 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 byteCount} bytes in this stream. The number of actual
213     * bytes skipped may be anywhere between 0 and {@code byteCount}. If
214     * {@code byteCount} is negative, this method does nothing and returns 0, but
215     * some subclasses may throw.
216     *
217     * <p>Note the "at most" in the description of this method: this method may
218     * choose to skip fewer bytes than requested. Callers should <i>always</i>
219     * check the return value.
220     *
221     * <p>This default implementation reads bytes into a temporary buffer. Concrete
222     * subclasses should provide their own implementation.
223     *
224     * @return the number of bytes actually skipped.
225     * @throws IOException if this stream is closed or another IOException
226     *             occurs.
227     */
228    public long skip(long byteCount) throws IOException {
229        return Streams.skipByReading(this, byteCount);
230    }
231}
232