libjava/java/io/DataInputStream.java

   1 /* DataInputStream.java -- FilteredInputStream that implements DataInput
   2    Copyright (C) 1998, 1999, 2000, 2001  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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 As a special exception, if you link this library with other files to
  22 produce an executable, this library does not by itself cause the
  23 resulting executable to be covered by the GNU General Public License.
  24 This exception does not however invalidate any other reasons why the
  25 executable file might be covered by the GNU General Public License. */
  26
  27 package java.io;
  28
  29 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  30  * "The Java Language Specification", ISBN 0-201-63451-1
  31  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
  32  * Status:  Believed complete and correct.
  33  */
  34
  35 /**
  36  * This subclass of <code>FilteredInputStream</code> implements the
  37  * <code>DataInput</code> interface that provides method for reading primitive
  38  * Java data types from a stream.
  39  *
  40  * @see DataInput
  41  *
  42  * @version 0.0
  43  *
  44  * @author Warren Levy <warrenl@cygnus.com>
  45  * @author Aaron M. Renn (arenn@urbanophile.com)
  46  * @date October 20, 1998.
  47  */
  48 public class DataInputStream extends FilterInputStream implements DataInput
  49 {
  50   // readLine() hack to ensure that an '\r' not followed by an '\n' is
  51   // handled correctly. If set, readLine() will ignore the first char it sees
  52   // if that char is a '\n'
  53   boolean ignoreInitialNewline = false;
  54
  55   /**
  56    * This constructor initializes a new <code>DataInputStream</code>
  57    * to read from the specified subordinate stream.
  58    *
  59    * @param in The subordinate <code>InputStream</code> to read from
  60    */
  61   public DataInputStream(InputStream in)
  62   {
  63     super(in);
  64   }
  65
  66   /**
  67    * This method reads bytes from the underlying stream into the specified
  68    * byte array buffer.  It will attempt to fill the buffer completely, but
  69    * may return a short count if there is insufficient data remaining to be
  70    * read to fill the buffer.
  71    *
  72    * @param b The buffer into which bytes will be read.
  73    *
  74    * @return The actual number of bytes read, or -1 if end of stream reached
  75    * before reading any bytes.
  76    *
  77    * @exception IOException If an error occurs.
  78    */
  79   public final int read(byte[] b) throws IOException
  80   {
  81     return in.read(b, 0, b.length);
  82   }
  83
  84   /**
  85    * This method reads bytes from the underlying stream into the specified
  86    * byte array buffer.  It will attempt to read <code>len</code> bytes and
  87    * will start storing them at position <code>off</code> into the buffer.
  88    * This method can return a short count if there is insufficient data
  89    * remaining to be read to complete the desired read length.
  90    *
  91    * @param b The buffer into which bytes will be read.
  92    * @param off The offset into the buffer to start storing bytes.
  93    * @param len The requested number of bytes to read.
  94    *
  95    * @return The actual number of bytes read, or -1 if end of stream reached
  96    * before reading any bytes.
  97    *
  98    * @exception IOException If an error occurs.
  99    */
 100   public final int read(byte[] b, int off, int len) throws IOException
 101   {
 102     return in.read(b, off, len);
 103   }
 104
 105   /**
 106    * This method reads a Java boolean value from an input stream.  It does
 107    * so by reading a single byte of data.  If that byte is zero, then the
 108    * value returned is <code>false</code>.  If the byte is non-zero, then
 109    * the value returned is <code>true</code>.
 110    * <p>
 111    * This method can read a <code>boolean</code> written by an object
 112    * implementing the <code>writeBoolean()</code> method in the
 113    * <code>DataOutput</code> interface.
 114    *
 115    * @return The <code>boolean</code> value read
 116    *
 117    * @exception EOFException If end of file is reached before reading
 118    * the boolean
 119    * @exception IOException If any other error occurs
 120    */
 121   public final boolean readBoolean() throws IOException
 122   {
 123     int b = in.read();
 124     if (b < 0)
 125       throw new EOFException();
 126     return (b != 0);
 127   }
 128
 129   /**
 130    * This method reads a Java byte value from an input stream.  The value
 131    * is in the range of -128 to 127.
 132    * <p>
 133    * This method can read a <code>byte</code> written by an object
 134    * implementing the <code>writeByte()</code> method in the
 135    * <code>DataOutput</code> interface.
 136    *
 137    * @return The <code>byte</code> value read
 138    *
 139    * @exception EOFException If end of file is reached before reading the byte
 140    * @exception IOException If any other error occurs
 141    *
 142    * @see DataOutput
 143    */
 144   public final byte readByte() throws IOException
 145   {
 146     int i = in.read();
 147     if (i < 0)
 148       throw new EOFException();
 149
 150     return (byte) i;
 151   }
 152
 153   /**
 154    * This method reads a Java <code>char</code> value from an input stream.
 155    * It operates by reading two bytes from the stream and converting them to
 156    * a single 16-bit Java <code>char</code>.  The two bytes are stored most
 157    * significant byte first (i.e., "big endian") regardless of the native
 158    * host byte ordering.
 159    * <p>
 160    * As an example, if <code>byte1</code> and <code>byte2</code>
 161    * represent the first and second byte read from the stream
 162    * respectively, they will be transformed to a <code>char</code> in
 163    * the following manner:
 164    * <p>
 165    * <code>(char)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>
 166    * <p>
 167    * This method can read a <code>char</code> written by an object
 168    * implementing the <code>writeChar()</code> method in the
 169    * <code>DataOutput</code> interface.
 170    *
 171    * @return The <code>char</code> value read
 172    *
 173    * @exception EOFException If end of file is reached before reading the char
 174    * @exception IOException If any other error occurs
 175    *
 176    * @see DataOutput
 177    */
 178   public final char readChar() throws IOException
 179   {
 180     int a = in.read();
 181     int b = in.read();
 182     if (b < 0)
 183       throw new EOFException();
 184     return (char) ((a << 8) | (b & 0xff));
 185   }
 186
 187   /**
 188    * This method reads a Java double value from an input stream.  It operates
 189    * by first reading a <code>long</code> value from the stream by calling the
 190    * <code>readLong()</code> method in this interface, then converts
 191    * that <code>long</code> to a <code>double</code> using the
 192    * <code>longBitsToDouble</code> method in the class
 193    * <code>java.lang.Double</code>
 194    * <p>
 195    * This method can read a <code>double</code> written by an object
 196    * implementing the <code>writeDouble()</code> method in the
 197    * <code>DataOutput</code> interface.
 198    *
 199    * @return The <code>double</code> value read
 200    *
 201    * @exception EOFException If end of file is reached before reading
 202    * the double
 203    * @exception IOException If any other error occurs
 204    *
 205    * @see java.lang.Double
 206    * @see DataOutput
 207    */
 208   public final double readDouble() throws IOException
 209   {
 210     return Double.longBitsToDouble(readLong());
 211   }
 212
 213   /**
 214    * This method reads a Java float value from an input stream.  It
 215    * operates by first reading an <code>int</code> value from the
 216    * stream by calling the <code>readInt()</code> method in this
 217    * interface, then converts that <code>int</code> to a
 218    * <code>float</code> using the <code>intBitsToFloat</code> method
 219    * in the class <code>java.lang.Float</code>
 220    * <p>
 221    * This method can read a <code>float</code> written by an object
 222    * implementing the * <code>writeFloat()</code> method in the
 223    * <code>DataOutput</code> interface.
 224    *
 225    * @return The <code>float</code> value read
 226    *
 227    * @exception EOFException If end of file is reached before reading the float
 228    * @exception IOException If any other error occurs
 229    *
 230    * @see java.lang.Float
 231    * @see DataOutput */
 232   public final float readFloat() throws IOException
 233   {
 234     return Float.intBitsToFloat(readInt());
 235   }
 236
 237   /**
 238    * This method reads raw bytes into the passed array until the array is
 239    * full.  Note that this method blocks until the data is available and
 240    * throws an exception if there is not enough data left in the stream to
 241    * fill the buffer
 242    *
 243    * @param b The buffer into which to read the data
 244    *
 245    * @exception EOFException If end of file is reached before filling
 246    * the buffer
 247    * @exception IOException If any other error occurs */
 248   public final void readFully(byte[] b) throws IOException
 249   {
 250     readFully(b, 0, b.length);
 251   }
 252
 253   /**
 254    * This method reads raw bytes into the passed array
 255    * <code>buf</code> starting <code>offset</code> bytes into the
 256    * buffer.  The number of bytes read will be exactly
 257    * <code>len</code> Note that this method blocks until the data is
 258    * available and * throws an exception if there is not enough data
 259    * left in the stream to read <code>len</code> bytes.
 260    *
 261    * @param buf The buffer into which to read the data
 262    * @param offset The offset into the buffer to start storing data
 263    * @param len The number of bytes to read into the buffer
 264    *
 265    * @exception EOFException If end of file is reached before filling
 266    * the buffer
 267    * @exception IOException If any other error occurs
 268    */
 269   public final void readFully(byte[] b, int off, int len) throws IOException
 270   {
 271     while (len > 0)
 272       {
 273         // in.read will block until some data is available.
 274         int numread = in.read(b, off, len);
 275         if (numread < 0)
 276           throw new EOFException();
 277         len -= numread;
 278         off += numread;
 279       }
 280   }
 281
 282   /**
 283    * This method reads a Java <code>int</code> value from an input
 284    * stream It operates by reading four bytes from the stream and
 285    * converting them to a single Java <code>int</code> The bytes are
 286    * stored most significant byte first (i.e., "big endian")
 287    * regardless of the native host byte ordering.
 288    * <p>
 289    * As an example, if <code>byte1</code> through <code>byte4</code>
 290    * represent the first four bytes read from the stream, they will be
 291    * transformed to an <code>int</code> in the following manner:
 292    * <p>
 293    * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +
 294    * ((byte3 & 0xFF) << 8) + (byte4 & 0xFF)))</code>
 295    * <p>
 296    * The value returned is in the range of 0 to 65535.
 297    * <p>
 298    * This method can read an <code>int</code> written by an object
 299    * implementing the <code>writeInt()</code> method in the
 300    * <code>DataOutput</code> interface.
 301    *
 302    * @return The <code>int</code> value read
 303    *
 304    * @exception EOFException If end of file is reached before reading the int
 305    * @exception IOException If any other error occurs
 306    *
 307    * @see DataOutput
 308    */
 309   public final int readInt() throws IOException
 310   {
 311     int a = in.read();
 312     int b = in.read();
 313     int c = in.read();
 314     int d = in.read();
 315     if (d < 0)
 316       throw new EOFException();
 317
 318     return (((a & 0xff) << 24) | ((b & 0xff) << 16) |
 319             ((c & 0xff) << 8) | (d & 0xff));
 320   }
 321
 322   /**
 323    * This method reads the next line of text data from an input
 324    * stream.  It operates by reading bytes and converting those bytes
 325    * to <code>char</code> values by treating the byte read as the low
 326    * eight bits of the <code>char</code> and using 0 as the high eight
 327    * bits.  Because of this, it does not support the full 16-bit
 328    * Unicode character set.
 329    * <p>
 330    * The reading of bytes ends when either the end of file or a line
 331    * terminator is encountered.  The bytes read are then returned as a
 332    * <code>String</code> A line terminator is a byte sequence
 333    * consisting of either <code>\r</code>, <code>\n</code> or
 334    * <code>\r\n</code>.  These termination charaters are discarded and
 335    * are not returned as part of the string.
 336    * <p>
 337    * This method can read data that was written by an object implementing the
 338    * <code>writeLine()</code> method in <code>DataOutput</code>.
 339    *
 340    * @return The line read as a <code>String</code>
 341    *
 342    * @exception IOException If an error occurs
 343    *
 344    * @see DataOutput
 345    *
 346    * @deprecated
 347    */
 348   public final String readLine() throws IOException
 349   {
 350     StringBuffer strb = new StringBuffer();
 351
 352     readloop: while (true)
 353       {
 354         int c = 0;
 355         char ch = ' ';
 356         boolean getnext = true;
 357         while (getnext)
 358           {
 359             getnext = false;
 360             c = in.read();
 361             if (c < 0)  // got an EOF
 362               return strb.length() > 0 ? strb.toString() : null;
 363             ch = (char) c;
 364             if ((ch &= 0xFF) == '\n')
 365               // hack to correctly handle '\r\n' sequences
 366               if (ignoreInitialNewline)
 367                 {
 368                   ignoreInitialNewline = false;
 369                   getnext = true;
 370                 }
 371               else
 372                 break readloop;
 373           }
 374
 375         if (ch == '\r')
 376           {
 377             // FIXME: The following code tries to adjust the stream back one
 378             // character if the next char read is '\n'.  As a last resort,
 379             // it tries to mark the position before reading but the bottom
 380             // line is that it is possible that this method will not properly
 381             // deal with a '\r' '\n' combination thus not fulfilling the
 382             // DataInput contract for readLine.  It's not a particularly
 383             // safe approach threadwise since it is unsynchronized and
 384             // since it might mark an input stream behind the users back.
 385             // Along the same vein it could try the same thing for
 386             // ByteArrayInputStream and PushbackInputStream, but that is
 387             // probably overkill since this is deprecated & BufferedInputStream
 388             // is the most likely type of input stream.
 389             //
 390             // The alternative is to somehow push back the next byte if it
 391             // isn't a '\n' or to have the reading methods of this class
 392             // keep track of whether the last byte read was '\r' by readLine
 393             // and then skip the very next byte if it is '\n'.  Either way,
 394             // this would increase the complexity of the non-deprecated methods
 395             // and since it is undesirable to make non-deprecated methods
 396             // less efficient, the following seems like the most reasonable
 397             // approach.
 398             int next_c = 0;
 399             char next_ch = ' ';
 400             if (in instanceof BufferedInputStream)
 401               {
 402                 next_c = in.read();
 403                 next_ch = (char) (next_c & 0xFF);
 404                 if ((next_ch != '\n') && (next_c >= 0))
 405                   {
 406                     BufferedInputStream bin = (BufferedInputStream) in;
 407                     if (bin.pos > 0)
 408                       bin.pos--;
 409                   }
 410               }
 411             else if (markSupported())
 412               {
 413                 next_c = in.read();
 414                 next_ch = (char) (next_c & 0xFF);
 415                 if ((next_ch != '\n') && (next_c >= 0))
 416                   {
 417                     mark(1);
 418                     if ((in.read() & 0xFF) != '\n')
 419                       reset();
 420                   }
 421               }
 422             // In order to catch cases where 'in' isn't a BufferedInputStream
 423             // and doesn't support mark() (such as reading from a Socket), set
 424             // a flag that instructs readLine() to ignore the first character
 425             // it sees _if_ that character is a '\n'.
 426             else ignoreInitialNewline = true;
 427             break;
 428           }
 429         strb.append(ch);
 430       }
 431
 432     return strb.length() > 0 ? strb.toString() : "";
 433   }
 434
 435   /**
 436    * This method reads a Java long value from an input stream
 437    * It operates by reading eight bytes from the stream and converting them to
 438    * a single Java <code>long</code>  The bytes are stored most
 439    * significant byte first (i.e., "big endian") regardless of the native
 440    * host byte ordering.
 441    * <p>
 442    * As an example, if <code>byte1</code> through <code>byte8</code>
 443    * represent the first eight bytes read from the stream, they will
 444    * be transformed to an <code>long</code> in the following manner:
 445    * <p>
 446    * <code>(long)((((long)byte1 & 0xFF) << 56) + (((long)byte2 & 0xFF) << 48) +
 447    * (((long)byte3 & 0xFF) << 40) + (((long)byte4 & 0xFF) << 32) +
 448    * (((long)byte5 & 0xFF) << 24) + (((long)byte6 & 0xFF) << 16) +
 449    * (((long)byte7 & 0xFF) << 8) + ((long)byte9 & 0xFF)))</code>
 450    * <p>
 451    * The value returned is in the range of 0 to 65535.
 452    * <p>
 453    * This method can read an <code>long</code> written by an object
 454    * implementing the <code>writeLong()</code> method in the
 455    * <code>DataOutput</code> interface.
 456    *
 457    * @return The <code>long</code> value read
 458    *
 459    * @exception EOFException If end of file is reached before reading the long
 460    * @exception IOException If any other error occurs
 461    *
 462    * @see DataOutput
 463    */
 464   public final long readLong() throws IOException
 465   {
 466     int a = in.read();
 467     int b = in.read();
 468     int c = in.read();
 469     int d = in.read();
 470     int e = in.read();
 471     int f = in.read();
 472     int g = in.read();
 473     int h = in.read();
 474     if (h < 0)
 475       throw new EOFException();
 476
 477     return (((long)(a & 0xff) << 56) |
 478             ((long)(b & 0xff) << 48) |
 479             ((long)(c & 0xff) << 40) |
 480             ((long)(d & 0xff) << 32) |
 481             ((long)(e & 0xff) << 24) |
 482             ((long)(f & 0xff) << 16) |
 483             ((long)(g & 0xff) <<  8) |
 484             ((long)(h & 0xff)));
 485   }
 486
 487   /**
 488    * This method reads a signed 16-bit value into a Java in from the
 489    * stream.  It operates by reading two bytes from the stream and
 490    * converting them to a single 16-bit Java <code>short</code>.  The
 491    * two bytes are stored most significant byte first (i.e., "big
 492    * endian") regardless of the native host byte ordering.
 493    * <p>
 494    * As an example, if <code>byte1</code> and <code>byte2</code>
 495    * represent the first and second byte read from the stream
 496    * respectively, they will be transformed to a <code>short</code>. in
 497    * the following manner:
 498    * <p>
 499    * <code>(short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>
 500    * <p>
 501    * The value returned is in the range of -32768 to 32767.
 502    * <p>
 503    * This method can read a <code>short</code> written by an object
 504    * implementing the <code>writeShort()</code> method in the
 505    * <code>DataOutput</code> interface.
 506    *
 507    * @return The <code>short</code> value read
 508    *
 509    * @exception EOFException If end of file is reached before reading the value
 510    * @exception IOException If any other error occurs
 511    *
 512    * @see DataOutput
 513    */
 514   public final short readShort() throws IOException
 515   {
 516     int a = in.read();
 517     int b = in.read();
 518     if (b < 0)
 519       throw new EOFException();
 520     return (short) ((a << 8) | (b & 0xff));
 521   }
 522
 523   /**
 524    * This method reads 8 unsigned bits into a Java <code>int</code>
 525    * value from the stream. The value returned is in the range of 0 to
 526    * 255.
 527    * <p>
 528    * This method can read an unsigned byte written by an object
 529    * implementing the <code>writeUnsignedByte()</code> method in the
 530    * <code>DataOutput</code> interface.
 531    *
 532    * @return The unsigned bytes value read as a Java <code>int</code>.
 533    *
 534    * @exception EOFException If end of file is reached before reading the value
 535    * @exception IOException If any other error occurs
 536    *
 537    * @see DataOutput
 538    */
 539   public final int readUnsignedByte() throws IOException
 540   {
 541     int i = in.read();
 542     if (i < 0)
 543       throw new EOFException();
 544
 545     return (i & 0xFF);
 546   }
 547
 548   /**
 549    * This method reads 16 unsigned bits into a Java int value from the stream.
 550    * It operates by reading two bytes from the stream and converting them to
 551    * a single Java <code>int</code>  The two bytes are stored most
 552    * significant byte first (i.e., "big endian") regardless of the native
 553    * host byte ordering.
 554    * <p>
 555    * As an example, if <code>byte1</code> and <code>byte2</code>
 556    * represent the first and second byte read from the stream
 557    * respectively, they will be transformed to an <code>int</code> in
 558    * the following manner:
 559    * <p>
 560    * <code>(int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))</code>
 561    * <p>
 562    * The value returned is in the range of 0 to 65535.
 563    * <p>
 564    * This method can read an unsigned short written by an object
 565    * implementing the <code>writeUnsignedShort()</code> method in the
 566    * <code>DataOutput</code> interface.
 567    *
 568    * @return The unsigned short value read as a Java <code>int</code>
 569    *
 570    * @exception EOFException If end of file is reached before reading the value
 571    * @exception IOException If any other error occurs
 572    */
 573   public final int readUnsignedShort() throws IOException
 574   {
 575     int a = in.read();
 576     int b = in.read();
 577     if (b < 0)
 578       throw new EOFException();
 579     return (((a & 0xff) << 8) | (b & 0xff));
 580   }
 581
 582   /**
 583    * This method reads a <code>String</code> from an input stream that
 584    * is encoded in a modified UTF-8 format.  This format has a leading
 585    * two byte sequence that contains the remaining number of bytes to
 586    * read.  This two byte sequence is read using the
 587    * <code>readUnsignedShort()</code> method of this interface.
 588    * <p>
 589    * After the number of remaining bytes have been determined, these
 590    * bytes are read an transformed into <code>char</code> values.
 591    * These <code>char</code> values are encoded in the stream using
 592    * either a one, two, or three byte format.  The particular format
 593    * in use can be determined by examining the first byte read.
 594    * <p>
 595    * If the first byte has a high order bit of 0, then that character
 596    * consists on only one byte.  This character value consists of
 597    * seven bits that are at positions 0 through 6 of the byte.  As an
 598    * example, if <code>byte1</code> is the byte read from the stream,
 599    * it would be converted to a <code>char</code> like so:
 600    * <p>
 601    * <code>(char)byte1</code>
 602    * <p>
 603    * If the first byte has 110 as its high order bits, then the
 604    * character consists of two bytes.  The bits that make up the character
 605    * value are in positions 0 through 4 of the first byte and bit positions
 606    * 0 through 5 of the second byte.  (The second byte should have
 607    * 10 as its high order bits).  These values are in most significant
 608    * byte first (i.e., "big endian") order.
 609    * <p>
 610    * As an example, if <code>byte1</code> and <code>byte2</code> are
 611    * the first two bytes read respectively, and the high order bits of
 612    * them match the patterns which indicate a two byte character
 613    * encoding, then they would be converted to a Java
 614    * <code>char</code> like so:
 615    * <p>
 616    * <code>(char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F))</code>
 617    * <p>
 618    * If the first byte has a 1110 as its high order bits, then the
 619    * character consists of three bytes.  The bits that make up the character
 620    * value are in positions 0 through 3 of the first byte and bit positions
 621    * 0 through 5 of the other two bytes.  (The second and third bytes should
 622    * have 10 as their high order bits).  These values are in most
 623    * significant byte first (i.e., "big endian") order.
 624    * <p>
 625    * As an example, if <code>byte1</code> <code>byte2</code> and
 626    * <code>byte3</code> are the three bytes read, and the high order
 627    * bits of them match the patterns which indicate a three byte
 628    * character encoding, then they would be converted to a Java
 629    * <code>char</code> like so:
 630    * <p>
 631    * <code>(char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) | (byte3 & 0x3F))</code>
 632    * <p>
 633    * Note that all characters are encoded in the method that requires
 634    * the fewest number of bytes with the exception of the character
 635    * with the value of <code>&#92;u0000</code> which is encoded as two
 636    * bytes.  This is a modification of the UTF standard used to
 637    * prevent C language style <code>NUL</code> values from appearing
 638    * in the byte stream.
 639    * <p>
 640    * This method can read data that was written by an object implementing the
 641    * <code>writeUTF()</code> method in <code>DataOutput</code>
 642    *
 643    * @returns The <code>String</code> read
 644    *
 645    * @exception EOFException If end of file is reached before reading
 646    * the String
 647    * @exception UTFDataFormatException If the data is not in UTF-8 format
 648    * @exception IOException If any other error occurs
 649    *
 650    * @see DataOutput
 651    */
 652   public final String readUTF() throws IOException
 653   {
 654     return readUTF(this);
 655   }
 656
 657   /**
 658    * This method reads a String encoded in UTF-8 format from the
 659    * specified <code>DataInput</code> source.
 660    *
 661    * @param in The <code>DataInput</code> source to read from
 662    *
 663    * @return The String read from the source
 664    *
 665    * @exception IOException If an error occurs
 666    */
 667   public final static String readUTF(DataInput in) throws IOException
 668   {
 669     final int UTFlen = in.readUnsignedShort();
 670     byte[] buf = new byte[UTFlen];
 671     StringBuffer strbuf = new StringBuffer();
 672
 673     // This blocks until the entire string is available rather than
 674     // doing partial processing on the bytes that are available and then
 675     // blocking.  An advantage of the latter is that Exceptions
 676     // could be thrown earlier.  The former is a bit cleaner.
 677     in.readFully(buf, 0, UTFlen);
 678     for (int i = 0; i < UTFlen; )
 679       {
 680         if ((buf[i] & 0x80) == 0)               // bit pattern 0xxxxxxx
 681           strbuf.append((char) (buf[i++] & 0xFF));
 682         else if ((buf[i] & 0xE0) == 0xC0)       // bit pattern 110xxxxx
 683           {
 684             if (i + 1 >= UTFlen || (buf[i+1] & 0xC0) != 0x80)
 685               throw new UTFDataFormatException();
 686
 687             strbuf.append((char) (((buf[i++] & 0x1F) << 6) |
 688                                   (buf[i++] & 0x3F)));
 689           }
 690         else if ((buf[i] & 0xF0) == 0xE0)       // bit pattern 1110xxxx
 691           {
 692             if (i + 2 >= UTFlen ||
 693                 (buf[i+1] & 0xC0) != 0x80 || (buf[i+2] & 0xC0) != 0x80)
 694               throw new UTFDataFormatException();
 695
 696             strbuf.append((char) (((buf[i++] & 0x0F) << 12) |
 697                                   ((buf[i++] & 0x3F) << 6) |
 698                                   (buf[i++] & 0x3F)));
 699           }
 700         else // must be ((buf[i] & 0xF0) == 0xF0 || (buf[i] & 0xC0) == 0x80)
 701           throw new UTFDataFormatException();   // bit patterns 1111xxxx or
 702                                                 //              10xxxxxx
 703       }
 704
 705     return strbuf.toString();
 706   }
 707
 708   /**
 709    * This method attempts to skip and discard the specified number of bytes
 710    * in the input stream.  It may actually skip fewer bytes than requested.
 711    * This method will not skip any bytes if passed a negative number of bytes
 712    * to skip.
 713    *
 714    * @param n The requested number of bytes to skip.
 715    * @return The requested number of bytes to skip.
 716    * @exception IOException If an error occurs.
 717    * @specnote The JDK docs claim that this returns the number of bytes
 718    *  actually skipped. The JCL claims that this method can throw an
 719    *  EOFException. Neither of these appear to be true in the JDK 1.3's
 720    *  implementation. This tries to implement the actual JDK behaviour.
 721    */
 722   public final int skipBytes(int n) throws IOException
 723   {
 724     if (n <= 0)
 725       return 0;
 726     try
 727       {
 728         return (int) in.skip(n);
 729       }
 730     catch (EOFException x)
 731       {
 732         // do nothing.
 733       }
 734     return n;
 735   }
 736 }