001 /* BufferedReader.java
002 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
003 Free Software Foundation, Inc.
004
005 This file is part of GNU Classpath.
006
007 GNU Classpath is free software; you can redistribute it and/or modify
008 it under the terms of the GNU General Public License as published by
009 the Free Software Foundation; either version 2, or (at your option)
010 any later version.
011
012 GNU Classpath is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of
014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 General Public License for more details.
016
017 You should have received a copy of the GNU General Public License
018 along with GNU Classpath; see the file COPYING. If not, write to the
019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020 02110-1301 USA.
021
022 Linking this library statically or dynamically with other modules is
023 making a combined work based on this library. Thus, the terms and
024 conditions of the GNU General Public License cover the whole
025 combination.
026
027 As a special exception, the copyright holders of this library give you
028 permission to link this library with independent modules to produce an
029 executable, regardless of the license terms of these independent
030 modules, and to copy and distribute the resulting executable under
031 terms of your choice, provided that you also meet, for each linked
032 independent module, the terms and conditions of the license of that
033 module. An independent module is a module which is not derived from
034 or based on this library. If you modify this library, you may extend
035 this exception to your version of the library, but you are not
036 obligated to do so. If you do not wish to do so, delete this
037 exception statement from your version. */
038
039
040 package java.io;
041
042 /* Written using "Java Class Libraries", 2nd edition, plus online
043 * API docs for JDK 1.2 beta from http://www.javasoft.com.
044 * Status: Believed complete and correct.
045 */
046
047 /**
048 * This subclass of <code>FilterReader</code> buffers input from an
049 * underlying implementation to provide a possibly more efficient read
050 * mechanism. It maintains the buffer and buffer state in instance
051 * variables that are available to subclasses. The default buffer size
052 * of 8192 chars can be overridden by the creator of the stream.
053 * <p>
054 * This class also implements mark/reset functionality. It is capable
055 * of remembering any number of input chars, to the limits of
056 * system memory or the size of <code>Integer.MAX_VALUE</code>
057 *
058 * @author Per Bothner (bothner@cygnus.com)
059 * @author Aaron M. Renn (arenn@urbanophile.com)
060 */
061 public class BufferedReader extends Reader
062 {
063 Reader in;
064 char[] buffer;
065 /* Index of current read position. Must be >= 0 and <= limit. */
066 /* There is a special case where pos may be equal to limit+1; this
067 * is used as an indicator that a readLine was done with a '\r' was
068 * the very last char in the buffer. Since we don't want to read-ahead
069 * and potentially block, we set pos this way to indicate the situation
070 * and deal with it later. Doing it this way rather than having a
071 * separate boolean field to indicate the condition has the advantage
072 * that it is self-clearing on things like mark/reset.
073 */
074 int pos;
075 /* Limit of valid data in buffer. Must be >= pos and <= buffer.length. */
076 /* This can be < pos in the one special case described above. */
077 int limit;
078
079 /* The value -1 means there is no mark, or the mark has been invalidated.
080 Otherwise, markPos is the index in the buffer of the marked position.
081 Must be >= 0 and <= pos.
082 Note we do not explicitly store the read-limit.
083 The implicit read-limit is (buffer.length - markPos), which is
084 guaranteed to be >= the read-limit requested in the call to mark. */
085 int markPos = -1;
086
087 // The JCL book specifies the default buffer size as 8K characters.
088 // This is package-private because it is used by LineNumberReader.
089 static final int DEFAULT_BUFFER_SIZE = 8192;
090
091 /**
092 * The line buffer for <code>readLine</code>.
093 */
094 private StringBuffer sbuf = null;
095
096 /**
097 * Create a new <code>BufferedReader</code> that will read from the
098 * specified subordinate stream with a default buffer size of 8192 chars.
099 *
100 * @param in The subordinate stream to read from
101 */
102 public BufferedReader(Reader in)
103 {
104 this(in, DEFAULT_BUFFER_SIZE);
105 }
106
107 /**
108 * Create a new <code>BufferedReader</code> that will read from the
109 * specified subordinate stream with a buffer size that is specified by the
110 * caller.
111 *
112 * @param in The subordinate stream to read from
113 * @param size The buffer size to use
114 *
115 * @exception IllegalArgumentException if size <= 0
116 */
117 public BufferedReader(Reader in, int size)
118 {
119 super(in.lock);
120 if (size <= 0)
121 throw new IllegalArgumentException("Illegal buffer size: " + size);
122 this.in = in;
123 buffer = new char[size];
124 }
125
126 /**
127 * This method closes the underlying stream and frees any associated
128 * resources.
129 *
130 * @exception IOException If an error occurs
131 */
132 public void close() throws IOException
133 {
134 synchronized (lock)
135 {
136 if (in != null)
137 in.close();
138 in = null;
139 buffer = null;
140 }
141 }
142
143 /**
144 * Returns <code>true</code> to indicate that this class supports mark/reset
145 * functionality.
146 *
147 * @return <code>true</code>
148 */
149 public boolean markSupported()
150 {
151 return true;
152 }
153
154 /**
155 * Mark a position in the input to which the stream can be
156 * "reset" by calling the <code>reset()</code> method. The parameter
157 * <code>readLimit</code> is the number of chars that can be read from the
158 * stream after setting the mark before the mark becomes invalid. For
159 * example, if <code>mark()</code> is called with a read limit of 10, then
160 * when 11 chars of data are read from the stream before the
161 * <code>reset()</code> method is called, then the mark is invalid and the
162 * stream object instance is not required to remember the mark.
163 * <p>
164 * Note that the number of chars that can be remembered by this method
165 * can be greater than the size of the internal read buffer. It is also
166 * not dependent on the subordinate stream supporting mark/reset
167 * functionality.
168 *
169 * @param readLimit The number of chars that can be read before the mark
170 * becomes invalid
171 *
172 * @exception IOException If an error occurs
173 * @exception IllegalArgumentException if readLimit is negative.
174 */
175 public void mark(int readLimit) throws IOException
176 {
177 if (readLimit < 0)
178 throw new IllegalArgumentException("Read-ahead limit is negative");
179
180 synchronized (lock)
181 {
182 checkStatus();
183 // In this method we need to be aware of the special case where
184 // pos + 1 == limit. This indicates that a '\r' was the last char
185 // in the buffer during a readLine. We'll want to maintain that
186 // condition after we shift things around and if a larger buffer is
187 // needed to track readLimit, we'll have to make it one element
188 // larger to ensure we don't invalidate the mark too early, if the
189 // char following the '\r' is NOT a '\n'. This is ok because, per
190 // the spec, we are not required to invalidate when passing readLimit.
191 //
192 // Note that if 'pos > limit', then doing 'limit -= pos' will cause
193 // limit to be negative. This is the only way limit will be < 0.
194
195 if (pos + readLimit > limit)
196 {
197 char[] old_buffer = buffer;
198 int extraBuffSpace = 0;
199 if (pos > limit)
200 extraBuffSpace = 1;
201 if (readLimit + extraBuffSpace > limit)
202 buffer = new char[readLimit + extraBuffSpace];
203 limit -= pos;
204 if (limit >= 0)
205 {
206 System.arraycopy(old_buffer, pos, buffer, 0, limit);
207 pos = 0;
208 }
209 }
210
211 if (limit < 0)
212 {
213 // Maintain the relationship of 'pos > limit'.
214 pos = 1;
215 limit = markPos = 0;
216 }
217 else
218 markPos = pos;
219 // Now pos + readLimit <= buffer.length. thus if we need to read
220 // beyond buffer.length, then we are allowed to invalidate markPos.
221 }
222 }
223
224 /**
225 * Reset the stream to the point where the <code>mark()</code> method
226 * was called. Any chars that were read after the mark point was set will
227 * be re-read during subsequent reads.
228 * <p>
229 * This method will throw an IOException if the number of chars read from
230 * the stream since the call to <code>mark()</code> exceeds the mark limit
231 * passed when establishing the mark.
232 *
233 * @exception IOException If an error occurs;
234 */
235 public void reset() throws IOException
236 {
237 synchronized (lock)
238 {
239 checkStatus();
240 if (markPos < 0)
241 throw new IOException("mark never set or invalidated");
242
243 // Need to handle the extremely unlikely case where a readLine was
244 // done with a '\r' as the last char in the buffer; which was then
245 // immediately followed by a mark and a reset with NO intervening
246 // read of any sort. In that case, setting pos to markPos would
247 // lose that info and a subsequent read would thus not skip a '\n'
248 // (if one exists). The value of limit in this rare case is zero.
249 // We can assume that if limit is zero for other reasons, then
250 // pos is already set to zero and doesn't need to be readjusted.
251 if (limit > 0)
252 pos = markPos;
253 }
254 }
255
256 /**
257 * This method determines whether or not a stream is ready to be read. If
258 * this method returns <code>false</code> then this stream could (but is
259 * not guaranteed to) block on the next read attempt.
260 *
261 * @return <code>true</code> if this stream is ready to be read,
262 * <code>false</code> otherwise
263 *
264 * @exception IOException If an error occurs
265 */
266 public boolean ready() throws IOException
267 {
268 synchronized (lock)
269 {
270 checkStatus();
271 return pos < limit || in.ready();
272 }
273 }
274
275 /**
276 * This method read chars from a stream and stores them into a caller
277 * supplied buffer. It starts storing the data at index
278 * <code>offset</code> into
279 * the buffer and attempts to read <code>len</code> chars. This method can
280 * return before reading the number of chars requested. The actual number
281 * of chars read is returned as an int. A -1 is returned to indicate the
282 * end of the stream.
283 * <p>
284 * This method will block until some data can be read.
285 *
286 * @param buf The array into which the chars read should be stored
287 * @param offset The offset into the array to start storing chars
288 * @param count The requested number of chars to read
289 *
290 * @return The actual number of chars read, or -1 if end of stream.
291 *
292 * @exception IOException If an error occurs.
293 * @exception IndexOutOfBoundsException If offset and count are not
294 * valid regarding buf.
295 */
296 public int read(char[] buf, int offset, int count) throws IOException
297 {
298 if (offset < 0 || offset + count > buf.length || count < 0)
299 throw new IndexOutOfBoundsException();
300
301 synchronized (lock)
302 {
303 checkStatus();
304 // Once again, we need to handle the special case of a readLine
305 // that has a '\r' at the end of the buffer. In this case, we'll
306 // need to skip a '\n' if it is the next char to be read.
307 // This special case is indicated by 'pos > limit'.
308 boolean retAtEndOfBuffer = false;
309
310 int avail = limit - pos;
311 if (count > avail)
312 {
313 if (avail > 0)
314 count = avail;
315 else // pos >= limit
316 {
317 if (limit == buffer.length)
318 markPos = -1; // read too far - invalidate the mark.
319 if (pos > limit)
320 {
321 // Set a boolean and make pos == limit to simplify things.
322 retAtEndOfBuffer = true;
323 --pos;
324 }
325 if (markPos < 0)
326 {
327 // Optimization: can read directly into buf.
328 if (count >= buffer.length && !retAtEndOfBuffer)
329 return in.read(buf, offset, count);
330 pos = limit = 0;
331 }
332 avail = in.read(buffer, limit, buffer.length - limit);
333 if (retAtEndOfBuffer && avail > 0 && buffer[limit] == '\n')
334 {
335 --avail;
336 limit++;
337 }
338 if (avail < count)
339 {
340 if (avail <= 0)
341 return avail;
342 count = avail;
343 }
344 limit += avail;
345 }
346 }
347 System.arraycopy(buffer, pos, buf, offset, count);
348 pos += count;
349 return count;
350 }
351 }
352
353 /* Read more data into the buffer. Update pos and limit appropriately.
354 Assumes pos==limit initially. May invalidate the mark if read too much.
355 Return number of chars read (never 0), or -1 on eof. */
356 private int fill() throws IOException
357 {
358 checkStatus();
359 // Handle the special case of a readLine that has a '\r' at the end of
360 // the buffer. In this case, we'll need to skip a '\n' if it is the
361 // next char to be read. This special case is indicated by 'pos > limit'.
362 boolean retAtEndOfBuffer = false;
363 if (pos > limit)
364 {
365 retAtEndOfBuffer = true;
366 --pos;
367 }
368
369 if (markPos >= 0 && limit == buffer.length)
370 markPos = -1;
371 if (markPos < 0)
372 pos = limit = 0;
373 int count = in.read(buffer, limit, buffer.length - limit);
374 if (count > 0)
375 limit += count;
376
377 if (retAtEndOfBuffer && buffer[pos] == '\n')
378 {
379 --count;
380 // If the mark was set to the location of the \n, then we
381 // must change it to fully pretend that the \n does not
382 // exist.
383 if (markPos == pos)
384 ++markPos;
385 ++pos;
386 }
387
388 return count;
389 }
390
391 public int read() throws IOException
392 {
393 synchronized (lock)
394 {
395 checkStatus();
396 if (pos >= limit && fill () <= 0)
397 return -1;
398 return buffer[pos++];
399 }
400 }
401
402 /* Return the end of the line starting at this.pos and ending at limit.
403 * The index returns is *before* any line terminators, or limit
404 * if no line terminators were found.
405 */
406 private int lineEnd(int limit)
407 {
408 int i = pos;
409 for (; i < limit; i++)
410 {
411 char ch = buffer[i];
412 if (ch == '\n' || ch == '\r')
413 break;
414 }
415 return i;
416 }
417
418 /**
419 * This method reads a single line of text from the input stream, returning
420 * it as a <code>String</code>. A line is terminated by "\n", a "\r", or
421 * an "\r\n" sequence. The system dependent line separator is not used.
422 * The line termination characters are not returned in the resulting
423 * <code>String</code>.
424 *
425 * @return The line of text read, or <code>null</code> if end of stream.
426 *
427 * @exception IOException If an error occurs
428 */
429 public String readLine() throws IOException
430 {
431 checkStatus();
432 // Handle the special case where a previous readLine (with no intervening
433 // reads/skips) had a '\r' at the end of the buffer.
434 // In this case, we'll need to skip a '\n' if it's the next char to be read.
435 // This special case is indicated by 'pos > limit'.
436 if (pos > limit)
437 {
438 int ch = read();
439 if (ch < 0)
440 return null;
441 if (ch != '\n')
442 --pos;
443 }
444 int i = lineEnd(limit);
445 if (i < limit)
446 {
447 String str = String.valueOf(buffer, pos, i - pos);
448 pos = i + 1;
449 // If the last char in the buffer is a '\r', we must remember
450 // to check if the next char to be read after the buffer is refilled
451 // is a '\n'. If so, skip it. To indicate this condition, we set pos
452 // to be limit + 1, which normally is never possible.
453 if (buffer[i] == '\r')
454 if (pos == limit || buffer[pos] == '\n')
455 pos++;
456 return str;
457 }
458 if (sbuf == null)
459 sbuf = new StringBuffer(200);
460 else
461 sbuf.setLength(0);
462 sbuf.append(buffer, pos, i - pos);
463 pos = i;
464 // We only want to return null when no characters were read before
465 // EOF. So we must keep track of this separately. Otherwise we
466 // would treat an empty `sbuf' as an EOF condition, which is wrong
467 // when there is just a newline.
468 boolean eof = false;
469 for (;;)
470 {
471 // readLine should block. So we must not return until a -1 is reached.
472 if (pos >= limit)
473 {
474 // here count == 0 isn't sufficient to give a failure.
475 int count = fill();
476 if (count < 0)
477 {
478 eof = true;
479 break;
480 }
481 continue;
482 }
483 int ch = buffer[pos++];
484 if (ch == '\n' || ch == '\r')
485 {
486 // Check here if a '\r' was the last char in the buffer; if so,
487 // mark it as in the comment above to indicate future reads
488 // should skip a newline that is the next char read after
489 // refilling the buffer.
490 if (ch == '\r')
491 if (pos == limit || buffer[pos] == '\n')
492 pos++;
493 break;
494 }
495 i = lineEnd(limit);
496 sbuf.append(buffer, pos - 1, i - (pos - 1));
497 pos = i;
498 }
499 return (sbuf.length() == 0 && eof) ? null : sbuf.toString();
500 }
501
502 /**
503 * This method skips the specified number of chars in the stream. It
504 * returns the actual number of chars skipped, which may be less than the
505 * requested amount.
506 * <p>
507 * This method first discards chars in the buffer, then calls the
508 * <code>skip</code> method on the underlying stream to skip the
509 * remaining chars.
510 *
511 * @param count The requested number of chars to skip
512 *
513 * @return The actual number of chars skipped.
514 *
515 * @exception IOException If an error occurs.
516 * @exception IllegalArgumentException If count is negative.
517 */
518 public long skip(long count) throws IOException
519 {
520 synchronized (lock)
521 {
522 checkStatus();
523 if (count < 0)
524 throw new IllegalArgumentException("skip value is negative");
525 if (count == 0)
526 return 0;
527 // Yet again, we need to handle the special case of a readLine
528 // that has a '\r' at the end of the buffer. In this case, we need
529 // to ignore a '\n' if it is the next char to be read.
530 // This special case is indicated by 'pos > limit' (i.e. avail < 0).
531 // To simplify things, if we're dealing with the special case for
532 // readLine, just read the next char (since the fill method will
533 // skip the '\n' for us). By doing this, we'll have to back up pos.
534 // That's easier than trying to keep track of whether we've skipped
535 // one element or not.
536 if (pos > limit)
537 {
538 if (read() < 0)
539 return 0;
540 else
541 --pos;
542 }
543
544 int avail = limit - pos;
545
546 if (count < avail)
547 {
548 pos += count;
549 return count;
550 }
551
552 pos = limit;
553 long todo = count - avail;
554 if (todo > buffer.length)
555 {
556 markPos = -1;
557 todo -= in.skip(todo);
558 }
559 else
560 {
561 while (todo > 0)
562 {
563 avail = fill();
564 if (avail <= 0)
565 break;
566 if (avail > todo)
567 avail = (int) todo;
568 pos += avail;
569 todo -= avail;
570 }
571 }
572 return count - todo;
573 }
574 }
575
576 private void checkStatus() throws IOException
577 {
578 if (in == null)
579 throw new IOException("Stream closed");
580 }
581 }