GNU Classpath (0.20) | |
Frames | No Frames |
1: /* Reader.java -- base class of classes that read input as a stream of chars 2: Copyright (C) 1998, 1999, 2000, 2003 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: /* Written using "Java Class Libraries", 2nd edition, plus online 41: * API docs for JDK 1.2 beta from http://www.javasoft.com. 42: * Status: Believed complete and correct. 43: */ 44: 45: /** 46: * This abstract class forms the base of the hierarchy of classes that read 47: * input as a stream of characters. It provides a common set of methods for 48: * reading characters from streams. Subclasses implement and extend these 49: * methods to read characters from a particular input source such as a file 50: * or network connection. 51: * 52: * @author Per Bothner (bothner@cygnus.com) 53: * @date April 21, 1998. 54: * @author Aaron M. Renn (arenn@urbanophile.com) 55: */ 56: public abstract class Reader 57: { 58: /** 59: * This is the <code>Object</code> used for synchronizing critical code 60: * sections. Subclasses should use this variable instead of a 61: * synchronized method or an explicit synchronization on <code>this</code> 62: */ 63: protected Object lock; 64: 65: /** 66: * Unitializes a <code>Reader</code> that will use the object 67: * itself for synchronization of critical code sections. 68: */ 69: protected Reader() 70: { 71: this.lock = this; 72: } 73: 74: /** 75: * Initializes a <code>Reader</code> that will use the specified 76: * <code>Object</code> for synchronization of critical code sections. 77: * 78: * @param lock The <code>Object</code> to use for synchronization 79: */ 80: protected Reader(Object lock) 81: { 82: this.lock = lock; 83: } 84: 85: /** 86: * Read chars from a stream and stores them into a caller 87: * supplied buffer. It starts storing the data at index <code>offset</code> 88: * into the buffer and attempts to read <code>len</code> chars. This method 89: * can return before reading the number of chars requested. The actual 90: * number of chars read is returned as an int. A -1 is returned to indicate 91: * the end of the stream. 92: * <p> 93: * This method will block until some data can be read. 94: * <p> 95: * This method operates by calling the single char <code>read()</code> method 96: * in a loop until the desired number of chars are read. The read loop 97: * stops short if the end of the stream is encountered or if an IOException 98: * is encountered on any read operation except the first. If the first 99: * attempt to read a chars fails, the IOException is allowed to propagate 100: * upward. And subsequent IOException is caught and treated identically 101: * to an end of stream condition. Subclasses can (and should if possible) 102: * override this method to provide a more efficient implementation. 103: * 104: * @param buf The array into which the chars read should be stored 105: * @param offset The offset into the array to start storing chars 106: * @param count The requested number of chars to read 107: * 108: * @return The actual number of chars read, or -1 if end of stream. 109: * 110: * @exception IOException If an error occurs. 111: */ 112: public abstract int read(char buf[], int offset, int count) 113: throws IOException; 114: 115: /** 116: * Reads chars from a stream and stores them into a caller 117: * supplied buffer. This method attempts to completely fill the buffer, 118: * but can return before doing so. The actual number of chars read is 119: * returned as an int. A -1 is returned to indicate the end of the stream. 120: * <p> 121: * This method will block until some data can be read. 122: * <p> 123: * This method operates by calling an overloaded read method like so: 124: * <code>read(buf, 0, buf.length)</code> 125: * 126: * @param buf The buffer into which the chars read will be stored. 127: * 128: * @return The number of chars read or -1 if end of stream. 129: * 130: * @exception IOException If an error occurs. 131: */ 132: public int read(char buf[]) throws IOException 133: { 134: return read(buf, 0, buf.length); 135: } 136: 137: /** 138: * Reads an char from the input stream and returns it 139: * as an int in the range of 0-65535. This method also will return -1 if 140: * the end of the stream has been reached. 141: * <p> 142: * This method will block until the char can be read. 143: * 144: * @return The char read or -1 if end of stream 145: * 146: * @exception IOException If an error occurs 147: */ 148: public int read() throws IOException 149: { 150: char[] buf = new char[1]; 151: int count = read(buf, 0, 1); 152: return count > 0 ? buf[0] : -1; 153: } 154: 155: /** 156: * Closes the stream. Any futher attempts to read from the 157: * stream may generate an <code>IOException</code>. 158: * 159: * @exception IOException If an error occurs 160: */ 161: public abstract void close() throws IOException; 162: 163: /** 164: * Returns a boolean that indicates whether the mark/reset 165: * methods are supported in this class. Those methods can be used to 166: * remember a specific point in the stream and reset the stream to that 167: * point. 168: * <p> 169: * This method always returns <code>false</code> in this class, but 170: * subclasses can override this method to return <code>true</code> if they 171: * support mark/reset functionality. 172: * 173: * @return <code>true</code> if mark/reset functionality is supported, 174: * <code>false</code> otherwise 175: * 176: */ 177: public boolean markSupported() 178: { 179: return false; 180: } 181: 182: /** 183: * Marks a position in the input to which the stream can be 184: * "reset" by calling the <code>reset()</code> method. The parameter 185: * <code>readlimit</code> is the number of chars that can be read from the 186: * stream after setting the mark before the mark becomes invalid. For 187: * example, if <code>mark()</code> is called with a read limit of 10, then 188: * when 11 chars of data are read from the stream before the 189: * <code>reset()</code> method is called, then the mark is invalid and the 190: * stream object instance is not required to remember the mark. 191: * 192: * @param readLimit The number of chars that can be read before the mark 193: * becomes invalid 194: * 195: * @exception IOException If an error occurs such as mark not being 196: * supported for this class 197: */ 198: public void mark(int readLimit) throws IOException 199: { 200: throw new IOException("mark not supported"); 201: } 202: 203: /** 204: * Resets a stream to the point where the <code>mark()</code> 205: * method was called. Any chars that were read after the mark point was 206: * set will be re-read during subsequent reads. 207: * <p> 208: * This method always throws an IOException in this class, but subclasses 209: * can override this method if they provide mark/reset functionality. 210: * 211: * @exception IOException Always thrown for this class 212: */ 213: public void reset() throws IOException 214: { 215: throw new IOException("reset not supported"); 216: } 217: 218: /** 219: * Determines whether or not this stream is ready to be 220: * read. If it returns <code>false</code> the stream may block if a 221: * read is attempted, but it is not guaranteed to do so. 222: * <p> 223: * This method always returns <code>false</code> in this class 224: * 225: * @return <code>true</code> if the stream is ready to be read, 226: * <code>false</code> otherwise. 227: * 228: * @exception IOException If an error occurs 229: */ 230: public boolean ready() throws IOException 231: { 232: return false; 233: } 234: 235: /** 236: * Skips the specified number of chars in the stream. It 237: * returns the actual number of chars skipped, which may be less than the 238: * requested amount. 239: * <p> 240: * This method reads and discards chars into a 256 char array until the 241: * specified number of chars were skipped or until either the end of stream 242: * is reached or a read attempt returns a short count. Subclasses can 243: * override this method to provide a more efficient implementation where 244: * one exists. 245: * 246: * @param count The requested number of chars to skip 247: * 248: * @return The actual number of chars skipped. 249: * 250: * @exception IOException If an error occurs 251: */ 252: public long skip(long count) throws IOException 253: { 254: if (count <= 0) 255: return 0; 256: int bsize = count > 1024 ? 1024 : (int) count; 257: char[] buffer = new char[bsize]; 258: long todo = count; 259: synchronized (lock) 260: { 261: while (todo > 0) 262: { 263: int skipped = read(buffer, 0, bsize > todo ? (int) todo : bsize); 264: if (skipped <= 0) 265: break; 266: todo -= skipped; 267: } 268: } 269: return count - todo; 270: } 271: }
GNU Classpath (0.20) |