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