BufferedReader.java revision a1603838fe9e865575c87982e32c6343740e464c
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; 21 22/** 23 * Wraps an existing {@link Reader} and <em>buffers</em> the input. Expensive 24 * interaction with the underlying reader is minimized, since most (smaller) 25 * requests can be satisfied by accessing the buffer alone. The drawback is that 26 * some extra space is required to hold the buffer and that copying takes place 27 * when filling that buffer, but this is usually outweighed by the performance 28 * benefits. 29 * 30 * <p/>A typical application pattern for the class looks like this:<p/> 31 * 32 * <pre> 33 * BufferedReader buf = new BufferedReader(new FileReader("file.java")); 34 * </pre> 35 * 36 * @see BufferedWriter 37 * @since 1.1 38 */ 39public class BufferedReader extends Reader { 40 41 private Reader in; 42 43 /** 44 * The characters that can be read and refilled in bulk. We maintain three 45 * indices into this buffer:<pre> 46 * { X X X X X X X X X X X X - - } 47 * ^ ^ ^ 48 * | | | 49 * mark pos end</pre> 50 * Pos points to the next readable character. End is one greater than the 51 * last readable character. When {@code pos == end}, the buffer is empty and 52 * must be {@link #fillBuf() filled} before characters can be read. 53 * 54 * <p>Mark is the value pos will be set to on calls to {@link #reset}. Its 55 * value is in the range {@code [0...pos]}. If the mark is {@code -1}, the 56 * buffer cannot be reset. 57 * 58 * <p>MarkLimit limits the distance between the mark and the pos. When this 59 * limit is exceeded, {@link #reset} is permitted (but not required) to 60 * throw an exception. For shorter distances, {@link #reset} shall not throw 61 * (unless the reader is closed). 62 */ 63 private char[] buf; 64 65 private int pos; 66 67 private int end; 68 69 private int mark = -1; 70 71 private int markLimit = -1; 72 73 /** 74 * Constructs a new {@code BufferedReader}, providing {@code in} with a buffer 75 * of 8192 characters. 76 * 77 * @param in the {@code Reader} the buffer reads from. 78 */ 79 public BufferedReader(Reader in) { 80 this(in, 8192); 81 } 82 83 /** 84 * Constructs a new {@code BufferedReader}, providing {@code in} with {@code size} characters 85 * of buffer. 86 * 87 * @param in the {@code InputStream} the buffer reads from. 88 * @param size the size of buffer in characters. 89 * @throws IllegalArgumentException if {@code size <= 0}. 90 */ 91 public BufferedReader(Reader in, int size) { 92 super(in); 93 if (size <= 0) { 94 throw new IllegalArgumentException("size <= 0"); 95 } 96 this.in = in; 97 buf = new char[size]; 98 } 99 100 /** 101 * Closes this reader. This implementation closes the buffered source reader 102 * and releases the buffer. Nothing is done if this reader has already been 103 * closed. 104 * 105 * @throws IOException 106 * if an error occurs while closing this reader. 107 */ 108 @Override 109 public void close() throws IOException { 110 synchronized (lock) { 111 if (!isClosed()) { 112 in.close(); 113 buf = null; 114 } 115 } 116 } 117 118 /** 119 * Populates the buffer with data. It is an error to call this method when 120 * the buffer still contains data; ie. if {@code pos < end}. 121 * 122 * @return the number of bytes read into the buffer, or -1 if the end of the 123 * source stream has been reached. 124 */ 125 private int fillBuf() throws IOException { 126 // assert(pos == end); 127 128 if (mark == -1 || (pos - mark >= markLimit)) { 129 /* mark isn't set or has exceeded its limit. use the whole buffer */ 130 int result = in.read(buf, 0, buf.length); 131 if (result > 0) { 132 mark = -1; 133 pos = 0; 134 end = result; 135 } 136 return result; 137 } 138 139 if (mark == 0 && markLimit > buf.length) { 140 /* the only way to make room when mark=0 is by growing the buffer */ 141 int newLength = buf.length * 2; 142 if (newLength > markLimit) { 143 newLength = markLimit; 144 } 145 char[] newbuf = new char[newLength]; 146 System.arraycopy(buf, 0, newbuf, 0, buf.length); 147 buf = newbuf; 148 } else if (mark > 0) { 149 /* make room by shifting the buffered data to left mark positions */ 150 System.arraycopy(buf, mark, buf, 0, buf.length - mark); 151 pos -= mark; 152 end -= mark; 153 mark = 0; 154 } 155 156 /* Set the new position and mark position */ 157 int count = in.read(buf, pos, buf.length - pos); 158 if (count != -1) { 159 end += count; 160 } 161 return count; 162 } 163 164 /** 165 * Indicates whether or not this reader is closed. 166 * 167 * @return {@code true} if this reader is closed, {@code false} 168 * otherwise. 169 */ 170 private boolean isClosed() { 171 return buf == null; 172 } 173 174 /** 175 * Sets a mark position in this reader. The parameter {@code markLimit} 176 * indicates how many characters can be read before the mark is invalidated. 177 * Calling {@code reset()} will reposition the reader back to the marked 178 * position if {@code markLimit} has not been surpassed. 179 * 180 * @param markLimit 181 * the number of characters that can be read before the mark is 182 * invalidated. 183 * @throws IllegalArgumentException 184 * if {@code markLimit < 0}. 185 * @throws IOException 186 * if an error occurs while setting a mark in this reader. 187 * @see #markSupported() 188 * @see #reset() 189 */ 190 @Override 191 public void mark(int markLimit) throws IOException { 192 if (markLimit < 0) { 193 throw new IllegalArgumentException(); 194 } 195 synchronized (lock) { 196 checkNotClosed(); 197 this.markLimit = markLimit; 198 mark = pos; 199 } 200 } 201 202 private void checkNotClosed() throws IOException { 203 if (isClosed()) { 204 throw new IOException("BufferedReader is closed"); 205 } 206 } 207 208 /** 209 * Indicates whether this reader supports the {@code mark()} and 210 * {@code reset()} methods. This implementation returns {@code true}. 211 * 212 * @return {@code true} for {@code BufferedReader}. 213 * @see #mark(int) 214 * @see #reset() 215 */ 216 @Override 217 public boolean markSupported() { 218 return true; 219 } 220 221 /** 222 * Reads a single character from this reader and returns it with the two 223 * higher-order bytes set to 0. If possible, BufferedReader returns a 224 * character from the buffer. If there are no characters available in the 225 * buffer, it fills the buffer and then returns a character. It returns -1 226 * if there are no more characters in the source reader. 227 * 228 * @return the character read or -1 if the end of the source reader has been 229 * reached. 230 * @throws IOException 231 * if this reader is closed or some other I/O error occurs. 232 */ 233 @Override 234 public int read() throws IOException { 235 synchronized (lock) { 236 checkNotClosed(); 237 /* Are there buffered characters available? */ 238 if (pos < end || fillBuf() != -1) { 239 return buf[pos++]; 240 } 241 return -1; 242 } 243 } 244 245 /** 246 * Reads at most {@code length} characters from this reader and stores them 247 * at {@code offset} in the character array {@code buffer}. Returns the 248 * number of characters actually read or -1 if the end of the source reader 249 * has been reached. If all the buffered characters have been used, a mark 250 * has not been set and the requested number of characters is larger than 251 * this readers buffer size, BufferedReader bypasses the buffer and simply 252 * places the results directly into {@code buffer}. 253 * 254 * @param buffer 255 * the character array to store the characters read. 256 * @param offset 257 * the initial position in {@code buffer} to store the bytes read 258 * from this reader. 259 * @param length 260 * the maximum number of characters to read, must be 261 * non-negative. 262 * @return number of characters read or -1 if the end of the source reader 263 * has been reached. 264 * @throws IndexOutOfBoundsException 265 * if {@code offset < 0} or {@code length < 0}, or if 266 * {@code offset + length} is greater than the size of 267 * {@code buffer}. 268 * @throws IOException 269 * if this reader is closed or some other I/O error occurs. 270 */ 271 @Override 272 public int read(char[] buffer, int offset, int length) throws IOException { 273 synchronized (lock) { 274 checkNotClosed(); 275 Arrays.checkOffsetAndCount(buffer.length, offset, length); 276 int outstanding = length; 277 while (outstanding > 0) { 278 279 /* 280 * If there are bytes in the buffer, grab those first. 281 */ 282 int available = end - pos; 283 if (available > 0) { 284 int count = available >= outstanding ? outstanding : available; 285 System.arraycopy(buf, pos, buffer, offset, count); 286 pos += count; 287 offset += count; 288 outstanding -= count; 289 } 290 291 /* 292 * Before attempting to read from the underlying stream, make 293 * sure we really, really want to. We won't bother if we're 294 * done, or if we've already got some bytes and reading from the 295 * underlying stream would block. 296 */ 297 if (outstanding == 0 || (outstanding < length && !in.ready())) { 298 break; 299 } 300 301 // assert(pos == end); 302 303 /* 304 * If we're unmarked and the requested size is greater than our 305 * buffer, read the bytes directly into the caller's buffer. We 306 * don't read into smaller buffers because that could result in 307 * a many reads. 308 */ 309 if ((mark == -1 || (pos - mark >= markLimit)) 310 && outstanding >= buf.length) { 311 int count = in.read(buffer, offset, outstanding); 312 if (count > 0) { 313 offset += count; 314 outstanding -= count; 315 mark = -1; 316 } 317 318 break; // assume the source stream gave us all that it could 319 } 320 321 if (fillBuf() == -1) { 322 break; // source is exhausted 323 } 324 } 325 326 int count = length - outstanding; 327 return (count > 0 || count == length) ? count : -1; 328 } 329 } 330 331 /** 332 * Peeks at the next input character, refilling the buffer if necessary. If 333 * this character is a newline character ("\n"), it is discarded. 334 */ 335 final void chompNewline() throws IOException { 336 if ((pos != end || fillBuf() != -1) 337 && buf[pos] == '\n') { 338 pos++; 339 } 340 } 341 342 /** 343 * Returns the next line of text available from this reader. A line is 344 * represented by zero or more characters followed by {@code '\n'}, 345 * {@code '\r'}, {@code "\r\n"} or the end of the reader. The string does 346 * not include the newline sequence. 347 * 348 * @return the contents of the line or {@code null} if no characters were 349 * read before the end of the reader has been reached. 350 * @throws IOException 351 * if this reader is closed or some other I/O error occurs. 352 */ 353 public String readLine() throws IOException { 354 synchronized (lock) { 355 checkNotClosed(); 356 /* has the underlying stream been exhausted? */ 357 if (pos == end && fillBuf() == -1) { 358 return null; 359 } 360 for (int charPos = pos; charPos < end; charPos++) { 361 char ch = buf[charPos]; 362 // BEGIN android-note 363 // a switch statement may be more efficient 364 // END android-note 365 if (ch > '\r') { 366 continue; 367 } 368 if (ch == '\n') { 369 String res = new String(buf, pos, charPos - pos); 370 pos = charPos + 1; 371 return res; 372 } else if (ch == '\r') { 373 String res = new String(buf, pos, charPos - pos); 374 pos = charPos + 1; 375 if (((pos < end) || (fillBuf() != -1)) 376 && (buf[pos] == '\n')) { 377 pos++; 378 } 379 return res; 380 } 381 } 382 383 char eol = '\0'; 384 StringBuilder result = new StringBuilder(80); 385 /* Typical Line Length */ 386 387 result.append(buf, pos, end - pos); 388 while (true) { 389 pos = end; 390 391 /* Are there buffered characters available? */ 392 if (eol == '\n') { 393 return result.toString(); 394 } 395 // attempt to fill buffer 396 if (fillBuf() == -1) { 397 // characters or null. 398 return result.length() > 0 || eol != '\0' 399 ? result.toString() 400 : null; 401 } 402 for (int charPos = pos; charPos < end; charPos++) { 403 char c = buf[charPos]; 404 if (eol == '\0') { 405 if ((c == '\n' || c == '\r')) { 406 eol = c; 407 } 408 } else if (eol == '\r' && c == '\n') { 409 if (charPos > pos) { 410 result.append(buf, pos, charPos - pos - 1); 411 } 412 pos = charPos + 1; 413 return result.toString(); 414 } else { 415 if (charPos > pos) { 416 result.append(buf, pos, charPos - pos - 1); 417 } 418 pos = charPos; 419 return result.toString(); 420 } 421 } 422 if (eol == '\0') { 423 result.append(buf, pos, end - pos); 424 } else { 425 result.append(buf, pos, end - pos - 1); 426 } 427 } 428 } 429 430 } 431 432 /** 433 * Indicates whether this reader is ready to be read without blocking. 434 * 435 * @return {@code true} if this reader will not block when {@code read} is 436 * called, {@code false} if unknown or blocking will occur. 437 * @throws IOException 438 * if this reader is closed or some other I/O error occurs. 439 * @see #read() 440 * @see #read(char[], int, int) 441 * @see #readLine() 442 */ 443 @Override 444 public boolean ready() throws IOException { 445 synchronized (lock) { 446 checkNotClosed(); 447 return ((end - pos) > 0) || in.ready(); 448 } 449 } 450 451 /** 452 * Resets this reader's position to the last {@code mark()} location. 453 * Invocations of {@code read()} and {@code skip()} will occur from this new 454 * location. 455 * 456 * @throws IOException 457 * if this reader is closed or no mark has been set. 458 * @see #mark(int) 459 * @see #markSupported() 460 */ 461 @Override 462 public void reset() throws IOException { 463 synchronized (lock) { 464 checkNotClosed(); 465 if (mark == -1) { 466 throw new IOException("Invalid mark"); 467 } 468 pos = mark; 469 } 470 } 471 472 /** 473 * Skips {@code byteCount} bytes in this stream. Subsequent calls to 474 * {@code read} will not return these bytes unless {@code reset} is 475 * used. 476 * Skipping characters may invalidate a mark if {@code markLimit} 477 * is surpassed. 478 * 479 * @param byteCount 480 * the maximum number of characters to skip. 481 * @return the number of characters actually skipped. 482 * @throws IllegalArgumentException 483 * if {@code byteCount < 0}. 484 * @throws IOException 485 * if this reader is closed or some other I/O error occurs. 486 * @see #mark(int) 487 * @see #markSupported() 488 * @see #reset() 489 */ 490 @Override 491 public long skip(long byteCount) throws IOException { 492 if (byteCount < 0) { 493 throw new IllegalArgumentException("byteCount < 0: " + byteCount); 494 } 495 synchronized (lock) { 496 checkNotClosed(); 497 if (byteCount < 1) { 498 return 0; 499 } 500 if (end - pos >= byteCount) { 501 pos += byteCount; 502 return byteCount; 503 } 504 505 long read = end - pos; 506 pos = end; 507 while (read < byteCount) { 508 if (fillBuf() == -1) { 509 return read; 510 } 511 if (end - pos >= byteCount - read) { 512 pos += byteCount - read; 513 return byteCount; 514 } 515 // Couldn't get all the characters, skip what we read 516 read += (end - pos); 517 pos = end; 518 } 519 return byteCount; 520 } 521 } 522} 523