1 /*
2 * Copyright (c) 1994, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.io;
27
28 /**
29 * A <code>PushbackInputStream</code> adds
30 * functionality to another input stream, namely
31 * the ability to "push back" or "unread" bytes,
32 * by storing pushed-back bytes in an internal buffer.
33 * This is useful in situations where
34 * it is convenient for a fragment of code
35 * to read an indefinite number of data bytes
36 * that are delimited by a particular byte
37 * value; after reading the terminating byte,
38 * the code fragment can "unread" it, so that
39 * the next read operation on the input stream
40 * will reread the byte that was pushed back.
41 * For example, bytes representing the characters
42 * constituting an identifier might be terminated
43 * by a byte representing an operator character;
44 * a method whose job is to read just an identifier
45 * can read until it sees the operator and
46 * then push the operator back to be re-read.
47 *
48 * @author David Connelly
49 * @author Jonathan Payne
50 * @since 1.0
51 */
52 public
53 class PushbackInputStream extends FilterInputStream {
54 /**
55 * The pushback buffer.
56 * @since 1.1
57 */
58 protected byte[] buf;
59
60 /**
61 * The position within the pushback buffer from which the next byte will
62 * be read. When the buffer is empty, <code>pos</code> is equal to
63 * <code>buf.length</code>; when the buffer is full, <code>pos</code> is
64 * equal to zero.
65 *
66 * @since 1.1
67 */
68 protected int pos;
69
70 /**
71 * Check to make sure that this stream has not been closed
72 */
73 private void ensureOpen() throws IOException {
74 if (in == null)
75 throw new IOException("Stream closed");
76 }
77
78 /**
79 * Creates a <code>PushbackInputStream</code>
80 * with a pushback buffer of the specified <code>size</code>,
81 * and saves its argument, the input stream
82 * <code>in</code>, for later use. Initially,
83 * the pushback buffer is empty.
84 *
85 * @param in the input stream from which bytes will be read.
86 * @param size the size of the pushback buffer.
87 * @exception IllegalArgumentException if {@code size <= 0}
88 * @since 1.1
89 */
90 public PushbackInputStream(InputStream in, int size) {
91 super(in);
92 if (size <= 0) {
93 throw new IllegalArgumentException("size <= 0");
94 }
95 this.buf = new byte[size];
96 this.pos = size;
97 }
98
99 /**
100 * Creates a <code>PushbackInputStream</code>
101 * with a 1-byte pushback buffer, and saves its argument, the input stream
102 * <code>in</code>, for later use. Initially,
103 * the pushback buffer is empty.
104 *
105 * @param in the input stream from which bytes will be read.
106 */
107 public PushbackInputStream(InputStream in) {
108 this(in, 1);
109 }
110
111 /**
112 * Reads the next byte of data from this input stream. The value
113 * byte is returned as an <code>int</code> in the range
114 * <code>0</code> to <code>255</code>. If no byte is available
115 * because the end of the stream has been reached, the value
116 * <code>-1</code> is returned. This method blocks until input data
117 * is available, the end of the stream is detected, or an exception
118 * is thrown.
119 *
120 * <p> This method returns the most recently pushed-back byte, if there is
121 * one, and otherwise calls the <code>read</code> method of its underlying
122 * input stream and returns whatever value that method returns.
123 *
124 * @return the next byte of data, or <code>-1</code> if the end of the
125 * stream has been reached.
126 * @exception IOException if this input stream has been closed by
127 * invoking its {@link #close()} method,
128 * or an I/O error occurs.
129 * @see java.io.InputStream#read()
130 */
131 public int read() throws IOException {
132 ensureOpen();
133 if (pos < buf.length) {
134 return buf[pos++] & 0xff;
135 }
136 return super.read();
137 }
138
139 /**
140 * Reads up to <code>len</code> bytes of data from this input stream into
141 * an array of bytes. This method first reads any pushed-back bytes; after
142 * that, if fewer than <code>len</code> bytes have been read then it
143 * reads from the underlying input stream. If <code>len</code> is not zero, the method
144 * blocks until at least 1 byte of input is available; otherwise, no
145 * bytes are read and <code>0</code> is returned.
146 *
147 * @param b the buffer into which the data is read.
148 * @param off the start offset in the destination array <code>b</code>
149 * @param len the maximum number of bytes read.
150 * @return the total number of bytes read into the buffer, or
151 * <code>-1</code> if there is no more data because the end of
152 * the stream has been reached.
153 * @exception NullPointerException If <code>b</code> is <code>null</code>.
154 * @exception IndexOutOfBoundsException If <code>off</code> is negative,
155 * <code>len</code> is negative, or <code>len</code> is greater than
156 * <code>b.length - off</code>
157 * @exception IOException if this input stream has been closed by
158 * invoking its {@link #close()} method,
159 * or an I/O error occurs.
160 * @see java.io.InputStream#read(byte[], int, int)
161 */
162 public int read(byte[] b, int off, int len) throws IOException {
163 ensureOpen();
164 if (b == null) {
165 throw new NullPointerException();
166 } else if (off < 0 || len < 0 || len > b.length - off) {
167 throw new IndexOutOfBoundsException();
168 } else if (len == 0) {
169 return 0;
170 }
171
172 int avail = buf.length - pos;
173 if (avail > 0) {
174 if (len < avail) {
175 avail = len;
176 }
177 System.arraycopy(buf, pos, b, off, avail);
178 pos += avail;
179 off += avail;
180 len -= avail;
181 }
182 if (len > 0) {
183 len = super.read(b, off, len);
184 if (len == -1) {
185 return avail == 0 ? -1 : avail;
186 }
187 return avail + len;
188 }
189 return avail;
190 }
191
192 /**
193 * Pushes back a byte by copying it to the front of the pushback buffer.
194 * After this method returns, the next byte to be read will have the value
195 * <code>(byte)b</code>.
196 *
197 * @param b the <code>int</code> value whose low-order
198 * byte is to be pushed back.
199 * @exception IOException If there is not enough room in the pushback
200 * buffer for the byte, or this input stream has been closed by
201 * invoking its {@link #close()} method.
202 */
203 public void unread(int b) throws IOException {
204 ensureOpen();
205 if (pos == 0) {
206 throw new IOException("Push back buffer is full");
207 }
208 buf[--pos] = (byte)b;
209 }
210
211 /**
212 * Pushes back a portion of an array of bytes by copying it to the front
213 * of the pushback buffer. After this method returns, the next byte to be
214 * read will have the value <code>b[off]</code>, the byte after that will
215 * have the value <code>b[off+1]</code>, and so forth.
216 *
217 * @param b the byte array to push back.
218 * @param off the start offset of the data.
219 * @param len the number of bytes to push back.
220 * @exception IOException If there is not enough room in the pushback
221 * buffer for the specified number of bytes,
222 * or this input stream has been closed by
223 * invoking its {@link #close()} method.
224 * @since 1.1
225 */
226 public void unread(byte[] b, int off, int len) throws IOException {
227 ensureOpen();
228 if (len > pos) {
229 throw new IOException("Push back buffer is full");
230 }
231 pos -= len;
232 System.arraycopy(b, off, buf, pos, len);
233 }
234
235 /**
236 * Pushes back an array of bytes by copying it to the front of the
237 * pushback buffer. After this method returns, the next byte to be read
238 * will have the value <code>b[0]</code>, the byte after that will have the
239 * value <code>b[1]</code>, and so forth.
240 *
241 * @param b the byte array to push back
242 * @exception IOException If there is not enough room in the pushback
243 * buffer for the specified number of bytes,
244 * or this input stream has been closed by
245 * invoking its {@link #close()} method.
246 * @since 1.1
247 */
248 public void unread(byte[] b) throws IOException {
249 unread(b, 0, b.length);
250 }
251
252 /**
253 * Returns an estimate of the number of bytes that can be read (or
254 * skipped over) from this input stream without blocking by the next
255 * invocation of a method for this input stream. The next invocation might be
256 * the same thread or another thread. A single read or skip of this
257 * many bytes will not block, but may read or skip fewer bytes.
258 *
259 * <p> The method returns the sum of the number of bytes that have been
260 * pushed back and the value returned by {@link
261 * java.io.FilterInputStream#available available}.
262 *
263 * @return the number of bytes that can be read (or skipped over) from
264 * the input stream without blocking.
265 * @exception IOException if this input stream has been closed by
266 * invoking its {@link #close()} method,
267 * or an I/O error occurs.
268 * @see java.io.FilterInputStream#in
269 * @see java.io.InputStream#available()
270 */
271 public int available() throws IOException {
272 ensureOpen();
273 int n = buf.length - pos;
274 int avail = super.available();
275 return n > (Integer.MAX_VALUE - avail)
276 ? Integer.MAX_VALUE
277 : n + avail;
278 }
279
280 /**
281 * Skips over and discards <code>n</code> bytes of data from this
282 * input stream. The <code>skip</code> method may, for a variety of
283 * reasons, end up skipping over some smaller number of bytes,
284 * possibly zero. If <code>n</code> is negative, no bytes are skipped.
285 *
286 * <p> The <code>skip</code> method of <code>PushbackInputStream</code>
287 * first skips over the bytes in the pushback buffer, if any. It then
288 * calls the <code>skip</code> method of the underlying input stream if
289 * more bytes need to be skipped. The actual number of bytes skipped
290 * is returned.
291 *
292 * @param n {@inheritDoc}
293 * @return {@inheritDoc}
294 * @throws IOException if the stream has been closed by
295 * invoking its {@link #close()} method,
296 * {@code in.skip(n)} throws an IOException,
297 * or an I/O error occurs.
298 * @see java.io.FilterInputStream#in
299 * @see java.io.InputStream#skip(long n)
300 * @since 1.2
301 */
302 public long skip(long n) throws IOException {
303 ensureOpen();
304 if (n <= 0) {
305 return 0;
306 }
307
308 long pskip = buf.length - pos;
309 if (pskip > 0) {
310 if (n < pskip) {
311 pskip = n;
312 }
313 pos += pskip;
314 n -= pskip;
315 }
316 if (n > 0) {
317 pskip += super.skip(n);
318 }
319 return pskip;
320 }
321
322 /**
323 * Tests if this input stream supports the <code>mark</code> and
324 * <code>reset</code> methods, which it does not.
325 *
326 * @return <code>false</code>, since this class does not support the
327 * <code>mark</code> and <code>reset</code> methods.
328 * @see java.io.InputStream#mark(int)
329 * @see java.io.InputStream#reset()
330 */
331 public boolean markSupported() {
332 return false;
333 }
334
335 /**
336 * Marks the current position in this input stream.
337 *
338 * <p> The <code>mark</code> method of <code>PushbackInputStream</code>
339 * does nothing.
340 *
341 * @param readlimit the maximum limit of bytes that can be read before
342 * the mark position becomes invalid.
343 * @see java.io.InputStream#reset()
344 */
345 public synchronized void mark(int readlimit) {
346 }
347
348 /**
349 * Repositions this stream to the position at the time the
350 * <code>mark</code> method was last called on this input stream.
351 *
352 * <p> The method <code>reset</code> for class
353 * <code>PushbackInputStream</code> does nothing except throw an
354 * <code>IOException</code>.
355 *
356 * @exception IOException if this method is invoked.
357 * @see java.io.InputStream#mark(int)
358 * @see java.io.IOException
359 */
360 public synchronized void reset() throws IOException {
361 throw new IOException("mark/reset not supported");
362 }
363
364 /**
365 * Closes this input stream and releases any system resources
366 * associated with the stream.
367 * Once the stream has been closed, further read(), unread(),
368 * available(), reset(), or skip() invocations will throw an IOException.
369 * Closing a previously closed stream has no effect.
370 *
371 * @exception IOException if an I/O error occurs.
372 */
373 public synchronized void close() throws IOException {
374 if (in == null)
375 return;
376 in.close();
377 in = null;
378 buf = null;
379 }
380 }
381
