1: /* Reader.java -- base class of classes that read input as a stream of chars 2: Copyright (C) 1998, 1999, 2000, 2003, 2004, 2005 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.io; 39: 40: import java.nio.CharBuffer; 41: 42: /* Written using "Java Class Libraries", 2nd edition, plus online 43: * API docs for JDK 1.2 beta from http://www.javasoft.com. 44: * Status: Believed complete and correct. 45: */ 46: 47: /** 48: * This abstract class forms the base of the hierarchy of classes that read 49: * input as a stream of characters. It provides a common set of methods for 50: * reading characters from streams. Subclasses implement and extend these 51: * methods to read characters from a particular input source such as a file 52: * or network connection. 53: * 54: * @author Per Bothner (bothner@cygnus.com) 55: * @date April 21, 1998. 56: * @author Aaron M. Renn (arenn@urbanophile.com) 57: */ 58: public abstract class Reader implements Closeable, Readable 59: { 60: /** 61: * This is the <code>Object</code> used for synchronizing critical code 62: * sections. Subclasses should use this variable instead of a 63: * synchronized method or an explicit synchronization on <code>this</code> 64: */ 65: protected Object lock; 66: 67: /** 68: * Unitializes a <code>Reader</code> that will use the object 69: * itself for synchronization of critical code sections. 70: */ 71: protected Reader() 72: { 73: this.lock = this; 74: } 75: 76: /** 77: * Initializes a <code>Reader</code> that will use the specified 78: * <code>Object</code> for synchronization of critical code sections. 79: * 80: * @param lock The <code>Object</code> to use for synchronization 81: */ 82: protected Reader(Object lock) 83: { 84: this.lock = lock; 85: } 86: 87: /** 88: * Read chars from a stream and stores them into a caller 89: * supplied buffer. It starts storing the data at index <code>offset</code> 90: * into the buffer and attempts to read <code>len</code> chars. This method 91: * can return before reading the number of chars requested. The actual 92: * number of chars read is returned as an int. A -1 is returned to indicate 93: * the end of the stream. 94: * <p> 95: * This method will block until some data can be read. 96: * <p> 97: * This method operates by calling the single char <code>read()</code> method 98: * in a loop until the desired number of chars are read. The read loop 99: * stops short if the end of the stream is encountered or if an IOException 100: * is encountered on any read operation except the first. If the first 101: * attempt to read a chars fails, the IOException is allowed to propagate 102: * upward. And subsequent IOException is caught and treated identically 103: * to an end of stream condition. Subclasses can (and should if possible) 104: * override this method to provide a more efficient implementation. 105: * 106: * @param buf The array into which the chars read should be stored 107: * @param offset The offset into the array to start storing chars 108: * @param count The requested number of chars to read 109: * 110: * @return The actual number of chars read, or -1 if end of stream. 111: * 112: * @exception IOException If an error occurs. 113: */ 114: public abstract int read(char buf[], int offset, int count) 115: throws IOException; 116: 117: /** 118: * Reads chars from a stream and stores them into a caller 119: * supplied buffer. This method attempts to completely fill the buffer, 120: * but can return before doing so. The actual number of chars read is 121: * returned as an int. A -1 is returned to indicate the end of the stream. 122: * <p> 123: * This method will block until some data can be read. 124: * <p> 125: * This method operates by calling an overloaded read method like so: 126: * <code>read(buf, 0, buf.length)</code> 127: * 128: * @param buf The buffer into which the chars read will be stored. 129: * 130: * @return The number of chars read or -1 if end of stream. 131: * 132: * @exception IOException If an error occurs. 133: */ 134: public int read(char buf[]) throws IOException 135: { 136: return read(buf, 0, buf.length); 137: } 138: 139: /** 140: * Reads an char from the input stream and returns it 141: * as an int in the range of 0-65535. This method also will return -1 if 142: * the end of the stream has been reached. 143: * <p> 144: * This method will block until the char can be read. 145: * 146: * @return The char read or -1 if end of stream 147: * 148: * @exception IOException If an error occurs 149: */ 150: public int read() throws IOException 151: { 152: char[] buf = new char[1]; 153: int count = read(buf, 0, 1); 154: return count > 0 ? buf[0] : -1; 155: } 156: 157: /** @since 1.5 */ 158: public int read(CharBuffer buffer) throws IOException 159: { 160: // We want to call put(), so we don't manipulate the CharBuffer 161: // directly. 162: int rem = buffer.remaining(); 163: char[] buf = new char[rem]; 164: int result = read(buf, 0, rem); 165: if (result != -1) 166: buffer.put(buf, 0, result); 167: return result; 168: } 169: 170: /** 171: * Closes the stream. Any futher attempts to read from the 172: * stream may generate an <code>IOException</code>. 173: * 174: * @exception IOException If an error occurs 175: */ 176: public abstract void close() throws IOException; 177: 178: /** 179: * Returns a boolean that indicates whether the mark/reset 180: * methods are supported in this class. Those methods can be used to 181: * remember a specific point in the stream and reset the stream to that 182: * point. 183: * <p> 184: * This method always returns <code>false</code> in this class, but 185: * subclasses can override this method to return <code>true</code> if they 186: * support mark/reset functionality. 187: * 188: * @return <code>true</code> if mark/reset functionality is supported, 189: * <code>false</code> otherwise 190: * 191: */ 192: public boolean markSupported() 193: { 194: return false; 195: } 196: 197: /** 198: * Marks a position in the input to which the stream can be 199: * "reset" by calling the <code>reset()</code> method. The parameter 200: * <code>readlimit</code> is the number of chars that can be read from the 201: * stream after setting the mark before the mark becomes invalid. For 202: * example, if <code>mark()</code> is called with a read limit of 10, then 203: * when 11 chars of data are read from the stream before the 204: * <code>reset()</code> method is called, then the mark is invalid and the 205: * stream object instance is not required to remember the mark. 206: * 207: * @param readLimit The number of chars that can be read before the mark 208: * becomes invalid 209: * 210: * @exception IOException If an error occurs such as mark not being 211: * supported for this class 212: */ 213: public void mark(int readLimit) throws IOException 214: { 215: throw new IOException("mark not supported"); 216: } 217: 218: /** 219: * Resets a stream to the point where the <code>mark()</code> 220: * method was called. Any chars that were read after the mark point was 221: * set will be re-read during subsequent reads. 222: * <p> 223: * This method always throws an IOException in this class, but subclasses 224: * can override this method if they provide mark/reset functionality. 225: * 226: * @exception IOException Always thrown for this class 227: */ 228: public void reset() throws IOException 229: { 230: throw new IOException("reset not supported"); 231: } 232: 233: /** 234: * Determines whether or not this stream is ready to be 235: * read. If it returns <code>false</code> the stream may block if a 236: * read is attempted, but it is not guaranteed to do so. 237: * <p> 238: * This method always returns <code>false</code> in this class 239: * 240: * @return <code>true</code> if the stream is ready to be read, 241: * <code>false</code> otherwise. 242: * 243: * @exception IOException If an error occurs 244: */ 245: public boolean ready() throws IOException 246: { 247: return false; 248: } 249: 250: /** 251: * Skips the specified number of chars in the stream. It 252: * returns the actual number of chars skipped, which may be less than the 253: * requested amount. 254: * <p> 255: * This method reads and discards chars into a 256 char array until the 256: * specified number of chars were skipped or until either the end of stream 257: * is reached or a read attempt returns a short count. Subclasses can 258: * override this method to provide a more efficient implementation where 259: * one exists. 260: * 261: * @param count The requested number of chars to skip 262: * 263: * @return The actual number of chars skipped. 264: * 265: * @exception IOException If an error occurs 266: */ 267: public long skip(long count) throws IOException 268: { 269: if (count <= 0) 270: return 0; 271: int bsize = count > 1024 ? 1024 : (int) count; 272: char[] buffer = new char[bsize]; 273: long todo = count; 274: synchronized (lock) 275: { 276: while (todo > 0) 277: { 278: int skipped = read(buffer, 0, bsize > todo ? (int) todo : bsize); 279: if (skipped <= 0) 280: break; 281: todo -= skipped; 282: } 283: } 284: return count - todo; 285: } 286: }