| Frames | No Frames |
1: /* DataInput.java -- Interface for reading data from a stream 2: Copyright (C) 1998, 1999, 2001, 2003, 2005 Free Software Foundation, Inc. 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: 39: package java.io; 40: 41: /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 42: * "The Java Language Specification", ISBN 0-201-63451-1 43: * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. 44: * Status: Believed complete and correct. */ 45: 46: /** 47: * This interface is implemented by classes that can data from streams 48: * into Java primitive types. 49: * 50: * @author Aaron M. Renn (arenn@urbanophile.com) 51: * @author Warren Levy (warrenl@cygnus.com) 52: */ 53: public interface DataInput 54: { 55: 56: /** 57: * This method reads a Java boolean value from an input stream. It does 58: * so by reading a single byte of data. If that byte is zero, then the 59: * value returned is <code>false</code>. If the byte is non-zero, then 60: * the value returned is <code>true</code>. 61: * <p> 62: * This method can read a <code>boolean</code> written by an object 63: * implementing the <code>writeBoolean()</code> method in the 64: * <code>DataOutput</code> interface. 65: * 66: * @return The <code>boolean</code> value read 67: * 68: * @exception EOFException If end of file is reached before 69: * reading the boolean 70: * @exception IOException If any other error occurs 71: * 72: * @see DataOutput#writeBoolean 73: */ 74: boolean readBoolean() throws EOFException, IOException; 75: 76: /** 77: * This method reads a Java byte value from an input stream. The value 78: * is in the range of -128 to 127. 79: * <p> 80: * This method can read a <code>byte</code> written by an object 81: * implementing the 82: * <code>writeByte()</code> method in the <code>DataOutput</code> interface. 83: * <p> 84: * @return The <code>byte</code> value read 85: * 86: * @exception EOFException If end of file is reached before reading the byte 87: * @exception IOException If any other error occurs 88: * 89: * @see DataOutput#writeByte 90: */ 91: byte readByte() throws EOFException, IOException; 92: 93: /** 94: * This method reads 8 unsigned bits into a Java <code>int</code> value from 95: * the stream. The value returned is in the range of 0 to 255. 96: * <p> 97: * This method can read an unsigned byte written by an object 98: * implementing the 99: * <code>writeByte()</code> method in the <code>DataOutput</code> 100: * interface. 101: * 102: * @return The unsigned bytes value read as a Java <code>int</code>. 103: * 104: * @exception EOFException If end of file is reached before reading the value 105: * @exception IOException If any other error occurs 106: * 107: * @see DataOutput#writeByte 108: */ 109: int readUnsignedByte() throws EOFException, IOException; 110: 111: /** 112: * This method reads a Java <code>char</code> value from an input stream. 113: * It operates by reading two bytes from the stream and converting them to 114: * a single 16-bit Java <code>char</code>. The two bytes are stored most 115: * significant byte first (i.e., "big endian") regardless of the native 116: * host byte ordering. 117: * <p> 118: * As an example, if <code>byte1</code> and <code>byte2</code> represent the 119: * first and second byte read from the stream respectively, they will be 120: * transformed to a <code>char</code> in the following manner: 121: * <p> 122: * <code>(char)((byte1 << 8) + byte2)</code> 123: * <p> 124: * This method can read a <code>char</code> written by an object implementing 125: * the 126: * <code>writeChar()</code> method in the <code>DataOutput</code> interface. 127: * 128: * @return The <code>char</code> value read 129: * 130: * @exception EOFException If end of file is reached before reading the char 131: * @exception IOException If any other error occurs 132: * 133: * @see DataOutput#writeChar 134: */ 135: char readChar() throws EOFException, IOException; 136: 137: /** 138: * This method reads a signed 16-bit value into a Java in from the stream. 139: * It operates by reading two bytes from the stream and converting them to 140: * a single 16-bit Java <code>short</code>. The two bytes are stored most 141: * significant byte first (i.e., "big endian") regardless of the native 142: * host byte ordering. 143: * <p> 144: * As an example, if <code>byte1</code> and <code>byte2</code> represent the 145: * first and second byte read from the stream respectively, they will be 146: * transformed to a <code>short</code> in the following manner: 147: * <p> 148: * <code>(short)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))</code> 149: * <p> 150: * The value returned is in the range of -32768 to 32767. 151: * <p> 152: * This method can read a <code>short</code> written by an object 153: * implementing 154: * the <code>writeShort()</code> method in the <code>DataOutput</code> 155: * interface. 156: * 157: * @return The <code>short</code> value read 158: * 159: * @exception EOFException If end of file is reached before reading the value 160: * @exception IOException If any other error occurs 161: * 162: * @see DataOutput#writeShort 163: */ 164: short readShort() throws EOFException, IOException; 165: 166: /** 167: * This method reads 16 unsigned bits into a Java int value from the stream. 168: * It operates by reading two bytes from the stream and converting them to 169: * a single Java <code>int</code>. The two bytes are stored most 170: * significant byte first (i.e., "big endian") regardless of the native 171: * host byte ordering. 172: * <p> 173: * As an example, if <code>byte1</code> and <code>byte2</code> represent the 174: * first and second byte read from the stream respectively, they will be 175: * transformed to an <code>int</code> in the following manner: 176: * <p> 177: * <code>(int)(((byte1 0xFF) << 8) + (byte2 & 0xFF))</code> 178: * <p> 179: * The value returned is in the range of 0 to 65535. 180: * <p> 181: * This method can read an unsigned short written by an object implementing 182: * the <code>writeShort()</code> method in the 183: * <code>DataOutput</code> 184: * interface. 185: * 186: * @return The unsigned short value read as a Java <code>int</code>. 187: * 188: * @exception EOFException If end of file is reached before reading 189: * the value 190: * @exception IOException If any other error occurs 191: * 192: * @see DataOutput#writeShort 193: */ 194: int readUnsignedShort() throws EOFException, IOException; 195: 196: /** 197: * This method reads a Java <code>int</code> value from an input stream 198: * It operates by reading four bytes from the stream and converting them to 199: * a single Java <code>int</code>. The bytes are stored most 200: * significant byte first (i.e., "big endian") regardless of the native 201: * host byte ordering. 202: * <p> 203: * As an example, if <code>byte1</code> through <code>byte4</code> represent 204: * the first four bytes read from the stream, they will be 205: * transformed to an <code>int</code> in the following manner: 206: * <p> 207: * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) + 208: * ((byte3 & 0xFF)<< 8) + (byte4 & 0xFF)))</code> 209: * <p> 210: * The value returned is in the range of -2147483648 to 2147483647. 211: * <p> 212: * This method can read an <code>int</code> written by an object 213: * implementing the <code>writeInt()</code> method in the 214: * <code>DataOutput</code> interface. 215: * 216: * @return The <code>int</code> value read 217: * 218: * @exception EOFException If end of file is reached before reading the int 219: * @exception IOException If any other error occurs 220: * 221: * @see DataOutput#writeInt 222: */ 223: int readInt() throws EOFException, IOException; 224: 225: /** 226: * This method reads a Java <code>long</code> value from an input stream 227: * It operates by reading eight bytes from the stream and converting them to 228: * a single Java <code>long</code>. The bytes are stored most 229: * significant byte first (i.e., "big endian") regardless of the native 230: * host byte ordering. 231: * <p> 232: * As an example, if <code>byte1</code> through <code>byte8</code> represent 233: * the first eight bytes read from the stream, they will be 234: * transformed to an <code>long</code> in the following manner: 235: * <p> 236: * <code>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) + 237: * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) + 238: * ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) + 239: * ((byte7 & 0xFF) << 8) + (byte8 & 0xFF))) 240: * </code> 241: * <p> 242: * The value returned is in the range of -9223372036854775808 to 243: * 9223372036854775807. 244: * <p> 245: * This method can read an <code>long</code> written by an object 246: * implementing the <code>writeLong()</code> method in the 247: * <code>DataOutput</code> interface. 248: * 249: * @return The <code>long</code> value read 250: * 251: * @exception EOFException If end of file is reached before reading the long 252: * @exception IOException If any other error occurs 253: * 254: * @see DataOutput#writeLong 255: */ 256: long readLong() throws EOFException, IOException; 257: 258: /** 259: * This method reads a Java float value from an input stream. It operates 260: * by first reading an <code>int</code> value from the stream by calling the 261: * <code>readInt()</code> method in this interface, then converts that 262: * <code>int</code> to a <code>float</code> using the 263: * <code>intBitsToFloat</code> method in the class 264: * <code>java.lang.Float</code>. 265: * <p> 266: * This method can read a <code>float</code> written by an object 267: * implementing 268: * the <code>writeFloat()</code> method in the <code>DataOutput</code> 269: * interface. 270: * 271: * @return The <code>float</code> value read 272: * 273: * @exception EOFException If end of file is reached before reading the 274: * float 275: * @exception IOException If any other error occurs 276: * 277: * @see DataOutput#writeFloat 278: * @see java.lang.Float#intBitsToFloat 279: */ 280: float readFloat() throws EOFException, IOException; 281: 282: /** 283: * This method reads a Java double value from an input stream. It operates 284: * by first reading a <code>long</code> value from the stream by calling the 285: * <code>readLong()</code> method in this interface, then converts that 286: * <code>long</code> to a <code>double</code> using the 287: * <code>longBitsToDouble</code> method in the class 288: * <code>java.lang.Double</code>. 289: * <p> 290: * This method can read a <code>double</code> written by an object 291: * implementing the <code>writeDouble()</code> method in the 292: * <code>DataOutput</code> interface. 293: * 294: * @return The <code>double</code> value read 295: * 296: * @exception EOFException If end of file is reached before reading the 297: * double 298: * @exception IOException If any other error occurs 299: * 300: * @see DataOutput#writeDouble 301: * @see java.lang.Double#longBitsToDouble 302: */ 303: double readDouble() throws EOFException, IOException; 304: 305: /** 306: * This method reads the next line of text data from an input stream. 307: * It operates by reading bytes and converting those bytes to 308: * <code>char</code> 309: * values by treating the byte read as the low eight bits of the 310: * <code>char</code> and using 0 as the high eight bits. Because of this, 311: * it does not support the full 16-bit Unicode character set. 312: * <P> 313: * The reading of bytes ends when either the end of file or a line terminator 314: * is encountered. The bytes read are then returned as a 315: * <code>String</code>. 316: * A line terminator is a byte sequence consisting of either 317: * <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination 318: * charaters are discarded and are not returned as part of the string. 319: * A line is also terminated by an end of file condition. 320: * <p> 321: * 322: * @return The line read as a <code>String</code> 323: * 324: * @exception IOException If an error occurs 325: */ 326: String readLine() throws IOException; 327: 328: /** 329: * This method reads a <code>String</code> from an input stream that is 330: * encoded in a modified UTF-8 format. This format has a leading two byte 331: * sequence that contains the remaining number of bytes to read. 332: * This two byte 333: * sequence is read using the <code>readUnsignedShort()</code> method of this 334: * interface. 335: * 336: * After the number of remaining bytes have been determined, these bytes 337: * are read an transformed into <code>char</code> values. These 338: * <code>char</code> values are encoded in the stream using either a one, 339: * two, or three byte format. 340: * The particular format in use can be determined by examining the first 341: * byte read. 342: * <p> 343: * If the first byte has a high order bit of 0, then 344: * that character consists on only one byte. This character value consists 345: * of seven bits that are at positions 0 through 6 of the byte. As an 346: * example, if <code>byte1</code> is the byte read from the stream, it would 347: * be converted to a <code>char</code> like so: 348: * <p> 349: * <code>(char)byte1</code> 350: * <p> 351: * If the first byte has 110 as its high order bits, then the 352: * character consists of two bytes. The bits that make up the character 353: * value are in positions 0 through 4 of the first byte and bit positions 354: * 0 through 5 of the second byte. (The second byte should have 355: * 10 as its high order bits). These values are in most significant 356: * byte first (i.e., "big endian") order. 357: * <p> 358: * As an example, if <code>byte1</code> and <code>byte2</code> are the first 359: * two bytes read respectively, and the high order bits of them match the 360: * patterns which indicate a two byte character encoding, then they would be 361: * converted to a Java <code>char</code> like so: 362: * <p> 363: * <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code> 364: * <p> 365: * If the first byte has a 1110 as its high order bits, then the 366: * character consists of three bytes. The bits that make up the character 367: * value are in positions 0 through 3 of the first byte and bit positions 368: * 0 through 5 of the other two bytes. (The second and third bytes should 369: * have 10 as their high order bits). These values are in most 370: * significant byte first (i.e., "big endian") order. 371: * <p> 372: * As an example, if <code>byte1</code>, <code>byte2</code>, and 373: * <code>byte3</code> are the three bytes read, and the high order bits of 374: * them match the patterns which indicate a three byte character encoding, 375: * then they would be converted to a Java <code>char</code> like so: 376: * 377: * <code> 378: * (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F)) 379: * </code> 380: * 381: * Note that all characters are encoded in the method that requires the 382: * fewest number of bytes with the exception of the character with the 383: * value of <code>\<llll>u0000</code> which is encoded as two bytes. 384: * This is a modification of the UTF standard used to prevent C language 385: * style <code>NUL</code> values from appearing in the byte stream. 386: * <p> 387: * This method can read data that was written by an object implementing the 388: * <code>writeUTF()</code> method in <code>DataOutput</code>. 389: * 390: * @return The <code>String</code> read 391: * 392: * @exception EOFException If end of file is reached before reading the 393: * String 394: * @exception UTFDataFormatException If the data is not in UTF-8 format 395: * @exception IOException If any other error occurs 396: * 397: * @see DataOutput#writeUTF 398: */ 399: String readUTF() throws EOFException, UTFDataFormatException, IOException; 400: 401: /** 402: * This method reads raw bytes into the passed array until the array is 403: * full. Note that this method blocks until the data is available and 404: * throws an exception if there is not enough data left in the stream to 405: * fill the buffer. Note also that zero length buffers are permitted. 406: * In this case, the method will return immediately without reading any 407: * bytes from the stream. 408: * 409: * @param buf The buffer into which to read the data 410: * 411: * @exception EOFException If end of file is reached before filling the 412: * buffer 413: * @exception IOException If any other error occurs 414: */ 415: void readFully(byte[] buf) throws EOFException, IOException; 416: 417: /** 418: * This method reads raw bytes into the passed array <code>buf</code> 419: * starting 420: * <code>offset</code> bytes into the buffer. The number of bytes read 421: * will be 422: * exactly <code>len</code>. Note that this method blocks until the data is 423: * available and throws an exception if there is not enough data left in 424: * the stream to read <code>len</code> bytes. Note also that zero length 425: * buffers are permitted. In this case, the method will return immediately 426: * without reading any bytes from the stream. 427: * 428: * @param buf The buffer into which to read the data 429: * @param offset The offset into the buffer to start storing data 430: * @param len The number of bytes to read into the buffer 431: * 432: * @exception EOFException If end of file is reached before filling the 433: * buffer 434: * @exception IOException If any other error occurs 435: */ 436: void readFully(byte[] buf, int offset, int len) 437: throws EOFException, IOException; 438: 439: /** 440: * This method skips and discards the specified number of bytes in an 441: * input stream. Note that this method may skip less than the requested 442: * number of bytes. The actual number of bytes skipped is returned. 443: * No bytes are skipped if a negative number is passed to this method. 444: * 445: * @param numBytes The number of bytes to skip 446: * 447: * @return The number of bytes actually skipped, which will always be 448: * <code>numBytes</code> 449: * 450: * @exception EOFException If end of file is reached before all bytes can be 451: * skipped 452: * @exception IOException If any other error occurs 453: */ 454: int skipBytes(int numBytes) throws EOFException, IOException; 455: 456: } // interface DataInput