libjava/java/io/DataInputStream.java

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