Source for java.io.DataInput

   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 &amp; 0x1F) &lt;&lt; 6) + (byte2 &amp; 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 &amp; 0x0F) &lt;&lt; 12) + ((byte2 &amp; 0x3F) + (byte3 &amp; 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>\&lt;llll&gt;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