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 org.apache.harmony.luni.internal.nls.Messages;
21
22 /**
23 * The base class for all input streams. An input stream is a means of reading
24 * data from a source in a byte-wise manner.
25 * <p>
26 * Some input streams also support marking a position in the input stream and
27 * returning to this position later. This abstract class does not provide a
28 * fully working implementation, so it needs to be subclassed, and at least the
29 * {@link #read()} method needs to be overridden. Overriding some of the
30 * non-abstract methods is also often advised, since it might result in higher
31 * efficiency.
32 * <p>
33 * Many specialized input streams for purposes like reading from a file already
34 * exist in this package.
35 *
36 * @see OutputStream
37 */
38 public abstract class InputStream extends Object implements Closeable {
39
40 private static byte[] skipBuf;
41
42 /**
43 * This constructor does nothing. It is provided for signature
44 * compatibility.
45 */
46 public InputStream() {
47 /* empty */
48 }
49
50 /**
51 * Returns the number of bytes that are available before this stream will
52 * block. This implementation always returns 0. Subclasses should override
53 * and indicate the correct number of bytes available.
54 *
55 * @return the number of bytes available before blocking.
56 * @throws IOException
57 * if an error occurs in this stream.
58 */
59 public int available() throws IOException {
60 return 0;
61 }
62
63 /**
64 * Closes this stream. Concrete implementations of this class should free
65 * any resources during close. This implementation does nothing.
66 *
67 * @throws IOException
68 * if an error occurs while closing this stream.
69 */
70 public void close() throws IOException {
71 /* empty */
72 }
73
74 /**
75 * Sets a mark position in this InputStream. The parameter {@code readlimit}
76 * indicates how many bytes can be read before the mark is invalidated.
77 * Sending {@code reset()} will reposition the stream back to the marked
78 * position provided {@code readLimit} has not been surpassed.
79 * <p>
80 * This default implementation does nothing and concrete subclasses must
81 * provide their own implementation.
82 *
83 * @param readlimit
84 * the number of bytes that can be read from this stream before
85 * the mark is invalidated.
86 * @see #markSupported()
87 * @see #reset()
88 */
89 public void mark(int readlimit) {
90 /* empty */
91 }
92
93 /**
94 * Indicates whether this stream supports the {@code mark()} and
95 * {@code reset()} methods. The default implementation returns {@code false}.
96 *
97 * @return always {@code false}.
98 * @see #mark(int)
99 * @see #reset()
100 */
101 public boolean markSupported() {
102 return false;
103 }
104
105 /**
106 * Reads a single byte from this stream and returns it as an integer in the
107 * range from 0 to 255. Returns -1 if the end of the stream has been
108 * reached. Blocks until one byte has been read, the end of the source
109 * stream is detected or an exception is thrown.
110 *
111 * @return the byte read or -1 if the end of stream has been reached.
112 * @throws IOException
113 * if the stream is closed or another IOException occurs.
114 */
115 public abstract int read() throws IOException;
116
117 /**
118 * Reads bytes from this stream and stores them in the byte array {@code b}.
119 *
120 * @param b
121 * the byte array in which to store the bytes read.
122 * @return the number of bytes actually read or -1 if the end of the stream
123 * has been reached.
124 * @throws IOException
125 * if this stream is closed or another IOException occurs.
126 */
127 public int read(byte b[]) throws IOException {
128 return read(b, 0, b.length);
129 }
130
131 /**
132 * Reads at most {@code length} bytes from this stream and stores them in
133 * the byte array {@code b} starting at {@code offset}.
134 *
135 * @param b
136 * the byte array in which to store the bytes read.
137 * @param offset
138 * the initial position in {@code buffer} to store the bytes read
139 * from this stream.
140 * @param length
141 * the maximum number of bytes to store in {@code b}.
142 * @return the number of bytes actually read or -1 if the end of the stream
143 * has been reached.
144 * @throws IndexOutOfBoundsException
145 * if {@code offset < 0} or {@code length < 0}, or if
146 * {@code offset + length} is greater than the length of
147 * {@code b}.
148 * @throws IOException
149 * if the stream is closed or another IOException occurs.
150 */
151 public int read(byte b[], int offset, int length) throws IOException {
152 // Force null check for b first!
153 if (offset > b.length || offset < 0) {
154 // luni.12=Offset out of bounds \: {0}
155 throw new ArrayIndexOutOfBoundsException(Messages.getString("luni.12", offset)); //$NON-NLS-1$
156 }
157 if (length < 0 || length > b.length - offset) {
158 // luni.18=Length out of bounds \: {0}
159 throw new ArrayIndexOutOfBoundsException(Messages.getString("luni.18", length)); //$NON-NLS-1$
160 }
161 for (int i = 0; i < length; i++) {
162 int c;
163 try {
164 if ((c = read()) == -1) {
165 return i == 0 ? -1 : i;
166 }
167 } catch (IOException e) {
168 if (i != 0) {
169 return i;
170 }
171 throw e;
172 }
173 b[offset + i] = (byte) c;
174 }
175 return length;
176 }
177
178 /**
179 * Resets this stream to the last marked location. Throws an
180 * {@code IOException} if the number of bytes read since the mark has been
181 * set is greater than the limit provided to {@code mark}, or if no mark
182 * has been set.
183 * <p>
184 * This implementation always throws an {@code IOException} and concrete
185 * subclasses should provide the proper implementation.
186 *
187 * @throws IOException
188 * if this stream is closed or another IOException occurs.
189 */
190 public synchronized void reset() throws IOException {
191 throw new IOException();
192 }
193
194 /**
195 * Skips at most {@code n} bytes in this stream. It does nothing and returns
196 * 0 if {@code n} is negative. Less than {@code n} characters are skipped if
197 * the end of this stream is reached before the operation completes.
198 * <p>
199 * This default implementation reads {@code n} bytes into a temporary
200 * buffer. Concrete subclasses should provide their own implementation.
201 *
202 * @param n
203 * the number of bytes to skip.
204 * @return the number of bytes actually skipped.
205 * @throws IOException
206 * if this stream is closed or another IOException occurs.
207 */
208 public long skip(long n) throws IOException {
209 if (n <= 0) {
210 return 0;
211 }
212 long skipped = 0;
213 int toRead = n < 4096 ? (int) n : 4096;
214 // We are unsynchronized, so take a local copy of the skipBuf at some
215 // point in time.
216 byte[] localBuf = skipBuf;
217 if (localBuf == null || localBuf.length < toRead) {
218 // May be lazily written back to the static. No matter if it
219 // overwrites somebody else's store.
220 skipBuf = localBuf = new byte[toRead];
221 }
222 while (skipped < n) {
223 int read = read(localBuf, 0, toRead);
224 if (read == -1) {
225 return skipped;
226 }
227 skipped += read;
228 if (read < toRead) {
229 return skipped;
230 }
231 if (n - skipped < toRead) {
232 toRead = (int) (n - skipped);
233 }
234 }
235 return skipped;
236 }
237 }
Save This Page