1.1 --- a/emul/src/main/java/java/io/DataInput.java Wed Jan 23 20:16:48 2013 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,635 +0,0 @@
1.4 -/*
1.5 - * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
1.6 - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 - *
1.8 - * This code is free software; you can redistribute it and/or modify it
1.9 - * under the terms of the GNU General Public License version 2 only, as
1.10 - * published by the Free Software Foundation. Oracle designates this
1.11 - * particular file as subject to the "Classpath" exception as provided
1.12 - * by Oracle in the LICENSE file that accompanied this code.
1.13 - *
1.14 - * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 - * version 2 for more details (a copy is included in the LICENSE file that
1.18 - * accompanied this code).
1.19 - *
1.20 - * You should have received a copy of the GNU General Public License version
1.21 - * 2 along with this work; if not, write to the Free Software Foundation,
1.22 - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 - *
1.24 - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 - * or visit www.oracle.com if you need additional information or have any
1.26 - * questions.
1.27 - */
1.28 -
1.29 -package java.io;
1.30 -
1.31 -/**
1.32 - * The <code>DataInput</code> interface provides
1.33 - * for reading bytes from a binary stream and
1.34 - * reconstructing from them data in any of
1.35 - * the Java primitive types. There is also
1.36 - * a
1.37 - * facility for reconstructing a <code>String</code>
1.38 - * from data in
1.39 - * <a href="#modified-utf-8">modified UTF-8</a>
1.40 - * format.
1.41 - * <p>
1.42 - * It is generally true of all the reading
1.43 - * routines in this interface that if end of
1.44 - * file is reached before the desired number
1.45 - * of bytes has been read, an <code>EOFException</code>
1.46 - * (which is a kind of <code>IOException</code>)
1.47 - * is thrown. If any byte cannot be read for
1.48 - * any reason other than end of file, an <code>IOException</code>
1.49 - * other than <code>EOFException</code> is
1.50 - * thrown. In particular, an <code>IOException</code>
1.51 - * may be thrown if the input stream has been
1.52 - * closed.
1.53 - *
1.54 - * <h4><a name="modified-utf-8">Modified UTF-8</a></h4>
1.55 - * <p>
1.56 - * Implementations of the DataInput and DataOutput interfaces represent
1.57 - * Unicode strings in a format that is a slight modification of UTF-8.
1.58 - * (For information regarding the standard UTF-8 format, see section
1.59 - * <i>3.9 Unicode Encoding Forms</i> of <i>The Unicode Standard, Version
1.60 - * 4.0</i>).
1.61 - * Note that in the following tables, the most significant bit appears in the
1.62 - * far left-hand column.
1.63 - * <p>
1.64 - * All characters in the range <code>'\u0001'</code> to
1.65 - * <code>'\u007F'</code> are represented by a single byte:
1.66 - *
1.67 - * <blockquote>
1.68 - * <table border="1" cellspacing="0" cellpadding="8" width="50%"
1.69 - * summary="Bit values and bytes">
1.70 - * <tr>
1.71 - * <td></td>
1.72 - * <th id="bit">Bit Values</th>
1.73 - * </tr>
1.74 - * <tr>
1.75 - * <th id="byte1">Byte 1</th>
1.76 - * <td>
1.77 - * <table border="1" cellspacing="0" width="100%">
1.78 - * <tr>
1.79 - * <td width="12%"><center>0</center>
1.80 - * <td colspan="7"><center>bits 6-0</center>
1.81 - * </tr>
1.82 - * </table>
1.83 - * </td>
1.84 - * </tr>
1.85 - * </table>
1.86 - * </blockquote>
1.87 - *
1.88 - * <p>
1.89 - * The null character <code>'\u0000'</code> and characters in the
1.90 - * range <code>'\u0080'</code> to <code>'\u07FF'</code> are
1.91 - * represented by a pair of bytes:
1.92 - *
1.93 - * <blockquote>
1.94 - * <table border="1" cellspacing="0" cellpadding="8" width="50%"
1.95 - * summary="Bit values and bytes">
1.96 - * <tr>
1.97 - * <td></td>
1.98 - * <th id="bit">Bit Values</th>
1.99 - * </tr>
1.100 - * <tr>
1.101 - * <th id="byte1">Byte 1</th>
1.102 - * <td>
1.103 - * <table border="1" cellspacing="0" width="100%">
1.104 - * <tr>
1.105 - * <td width="12%"><center>1</center>
1.106 - * <td width="13%"><center>1</center>
1.107 - * <td width="12%"><center>0</center>
1.108 - * <td colspan="5"><center>bits 10-6</center>
1.109 - * </tr>
1.110 - * </table>
1.111 - * </td>
1.112 - * </tr>
1.113 - * <tr>
1.114 - * <th id="byte2">Byte 2</th>
1.115 - * <td>
1.116 - * <table border="1" cellspacing="0" width="100%">
1.117 - * <tr>
1.118 - * <td width="12%"><center>1</center>
1.119 - * <td width="13%"><center>0</center>
1.120 - * <td colspan="6"><center>bits 5-0</center>
1.121 - * </tr>
1.122 - * </table>
1.123 - * </td>
1.124 - * </tr>
1.125 - * </table>
1.126 - * </blockquote>
1.127 - *
1.128 - * <br>
1.129 - * <code>char</code> values in the range <code>'\u0800'</code> to
1.130 - * <code>'\uFFFF'</code> are represented by three bytes:
1.131 - *
1.132 - * <blockquote>
1.133 - * <table border="1" cellspacing="0" cellpadding="8" width="50%"
1.134 - * summary="Bit values and bytes">
1.135 - * <tr>
1.136 - * <td></td>
1.137 - * <th id="bit">Bit Values</th>
1.138 - * </tr>
1.139 - * <tr>
1.140 - * <th id="byte1">Byte 1</th>
1.141 - * <td>
1.142 - * <table border="1" cellspacing="0" width="100%">
1.143 - * <tr>
1.144 - * <td width="12%"><center>1</center>
1.145 - * <td width="13%"><center>1</center>
1.146 - * <td width="12%"><center>1</center>
1.147 - * <td width="13%"><center>0</center>
1.148 - * <td colspan="4"><center>bits 15-12</center>
1.149 - * </tr>
1.150 - * </table>
1.151 - * </td>
1.152 - * </tr>
1.153 - * <tr>
1.154 - * <th id="byte2">Byte 2</th>
1.155 - * <td>
1.156 - * <table border="1" cellspacing="0" width="100%">
1.157 - * <tr>
1.158 - * <td width="12%"><center>1</center>
1.159 - * <td width="13%"><center>0</center>
1.160 - * <td colspan="6"><center>bits 11-6</center>
1.161 - * </tr>
1.162 - * </table>
1.163 - * </td>
1.164 - * </tr>
1.165 - * <tr>
1.166 - * <th id="byte3">Byte 3</th>
1.167 - * <td>
1.168 - * <table border="1" cellspacing="0" width="100%">
1.169 - * <tr>
1.170 - * <td width="12%"><center>1</center>
1.171 - * <td width="13%"><center>0</center>
1.172 - * <td colspan="6"><center>bits 5-0</center>
1.173 - * </tr>
1.174 - * </table>
1.175 - * </td>
1.176 - * </tr>
1.177 - * </table>
1.178 - * </blockquote>
1.179 - *
1.180 - * <p>
1.181 - * The differences between this format and the
1.182 - * standard UTF-8 format are the following:
1.183 - * <ul>
1.184 - * <li>The null byte <code>'\u0000'</code> is encoded in 2-byte format
1.185 - * rather than 1-byte, so that the encoded strings never have
1.186 - * embedded nulls.
1.187 - * <li>Only the 1-byte, 2-byte, and 3-byte formats are used.
1.188 - * <li><a href="../lang/Character.html#unicode">Supplementary characters</a>
1.189 - * are represented in the form of surrogate pairs.
1.190 - * </ul>
1.191 - * @author Frank Yellin
1.192 - * @see java.io.DataInputStream
1.193 - * @see java.io.DataOutput
1.194 - * @since JDK1.0
1.195 - */
1.196 -public
1.197 -interface DataInput {
1.198 - /**
1.199 - * Reads some bytes from an input
1.200 - * stream and stores them into the buffer
1.201 - * array <code>b</code>. The number of bytes
1.202 - * read is equal
1.203 - * to the length of <code>b</code>.
1.204 - * <p>
1.205 - * This method blocks until one of the
1.206 - * following conditions occurs:<p>
1.207 - * <ul>
1.208 - * <li><code>b.length</code>
1.209 - * bytes of input data are available, in which
1.210 - * case a normal return is made.
1.211 - *
1.212 - * <li>End of
1.213 - * file is detected, in which case an <code>EOFException</code>
1.214 - * is thrown.
1.215 - *
1.216 - * <li>An I/O error occurs, in
1.217 - * which case an <code>IOException</code> other
1.218 - * than <code>EOFException</code> is thrown.
1.219 - * </ul>
1.220 - * <p>
1.221 - * If <code>b</code> is <code>null</code>,
1.222 - * a <code>NullPointerException</code> is thrown.
1.223 - * If <code>b.length</code> is zero, then
1.224 - * no bytes are read. Otherwise, the first
1.225 - * byte read is stored into element <code>b[0]</code>,
1.226 - * the next one into <code>b[1]</code>, and
1.227 - * so on.
1.228 - * If an exception is thrown from
1.229 - * this method, then it may be that some but
1.230 - * not all bytes of <code>b</code> have been
1.231 - * updated with data from the input stream.
1.232 - *
1.233 - * @param b the buffer into which the data is read.
1.234 - * @exception EOFException if this stream reaches the end before reading
1.235 - * all the bytes.
1.236 - * @exception IOException if an I/O error occurs.
1.237 - */
1.238 - void readFully(byte b[]) throws IOException;
1.239 -
1.240 - /**
1.241 - *
1.242 - * Reads <code>len</code>
1.243 - * bytes from
1.244 - * an input stream.
1.245 - * <p>
1.246 - * This method
1.247 - * blocks until one of the following conditions
1.248 - * occurs:<p>
1.249 - * <ul>
1.250 - * <li><code>len</code> bytes
1.251 - * of input data are available, in which case
1.252 - * a normal return is made.
1.253 - *
1.254 - * <li>End of file
1.255 - * is detected, in which case an <code>EOFException</code>
1.256 - * is thrown.
1.257 - *
1.258 - * <li>An I/O error occurs, in
1.259 - * which case an <code>IOException</code> other
1.260 - * than <code>EOFException</code> is thrown.
1.261 - * </ul>
1.262 - * <p>
1.263 - * If <code>b</code> is <code>null</code>,
1.264 - * a <code>NullPointerException</code> is thrown.
1.265 - * If <code>off</code> is negative, or <code>len</code>
1.266 - * is negative, or <code>off+len</code> is
1.267 - * greater than the length of the array <code>b</code>,
1.268 - * then an <code>IndexOutOfBoundsException</code>
1.269 - * is thrown.
1.270 - * If <code>len</code> is zero,
1.271 - * then no bytes are read. Otherwise, the first
1.272 - * byte read is stored into element <code>b[off]</code>,
1.273 - * the next one into <code>b[off+1]</code>,
1.274 - * and so on. The number of bytes read is,
1.275 - * at most, equal to <code>len</code>.
1.276 - *
1.277 - * @param b the buffer into which the data is read.
1.278 - * @param off an int specifying the offset into the data.
1.279 - * @param len an int specifying the number of bytes to read.
1.280 - * @exception EOFException if this stream reaches the end before reading
1.281 - * all the bytes.
1.282 - * @exception IOException if an I/O error occurs.
1.283 - */
1.284 - void readFully(byte b[], int off, int len) throws IOException;
1.285 -
1.286 - /**
1.287 - * Makes an attempt to skip over
1.288 - * <code>n</code> bytes
1.289 - * of data from the input
1.290 - * stream, discarding the skipped bytes. However,
1.291 - * it may skip
1.292 - * over some smaller number of
1.293 - * bytes, possibly zero. This may result from
1.294 - * any of a
1.295 - * number of conditions; reaching
1.296 - * end of file before <code>n</code> bytes
1.297 - * have been skipped is
1.298 - * only one possibility.
1.299 - * This method never throws an <code>EOFException</code>.
1.300 - * The actual
1.301 - * number of bytes skipped is returned.
1.302 - *
1.303 - * @param n the number of bytes to be skipped.
1.304 - * @return the number of bytes actually skipped.
1.305 - * @exception IOException if an I/O error occurs.
1.306 - */
1.307 - int skipBytes(int n) throws IOException;
1.308 -
1.309 - /**
1.310 - * Reads one input byte and returns
1.311 - * <code>true</code> if that byte is nonzero,
1.312 - * <code>false</code> if that byte is zero.
1.313 - * This method is suitable for reading
1.314 - * the byte written by the <code>writeBoolean</code>
1.315 - * method of interface <code>DataOutput</code>.
1.316 - *
1.317 - * @return the <code>boolean</code> value read.
1.318 - * @exception EOFException if this stream reaches the end before reading
1.319 - * all the bytes.
1.320 - * @exception IOException if an I/O error occurs.
1.321 - */
1.322 - boolean readBoolean() throws IOException;
1.323 -
1.324 - /**
1.325 - * Reads and returns one input byte.
1.326 - * The byte is treated as a signed value in
1.327 - * the range <code>-128</code> through <code>127</code>,
1.328 - * inclusive.
1.329 - * This method is suitable for
1.330 - * reading the byte written by the <code>writeByte</code>
1.331 - * method of interface <code>DataOutput</code>.
1.332 - *
1.333 - * @return the 8-bit value read.
1.334 - * @exception EOFException if this stream reaches the end before reading
1.335 - * all the bytes.
1.336 - * @exception IOException if an I/O error occurs.
1.337 - */
1.338 - byte readByte() throws IOException;
1.339 -
1.340 - /**
1.341 - * Reads one input byte, zero-extends
1.342 - * it to type <code>int</code>, and returns
1.343 - * the result, which is therefore in the range
1.344 - * <code>0</code>
1.345 - * through <code>255</code>.
1.346 - * This method is suitable for reading
1.347 - * the byte written by the <code>writeByte</code>
1.348 - * method of interface <code>DataOutput</code>
1.349 - * if the argument to <code>writeByte</code>
1.350 - * was intended to be a value in the range
1.351 - * <code>0</code> through <code>255</code>.
1.352 - *
1.353 - * @return the unsigned 8-bit value read.
1.354 - * @exception EOFException if this stream reaches the end before reading
1.355 - * all the bytes.
1.356 - * @exception IOException if an I/O error occurs.
1.357 - */
1.358 - int readUnsignedByte() throws IOException;
1.359 -
1.360 - /**
1.361 - * Reads two input bytes and returns
1.362 - * a <code>short</code> value. Let <code>a</code>
1.363 - * be the first byte read and <code>b</code>
1.364 - * be the second byte. The value
1.365 - * returned
1.366 - * is:
1.367 - * <p><pre><code>(short)((a << 8) | (b & 0xff))
1.368 - * </code></pre>
1.369 - * This method
1.370 - * is suitable for reading the bytes written
1.371 - * by the <code>writeShort</code> method of
1.372 - * interface <code>DataOutput</code>.
1.373 - *
1.374 - * @return the 16-bit value read.
1.375 - * @exception EOFException if this stream reaches the end before reading
1.376 - * all the bytes.
1.377 - * @exception IOException if an I/O error occurs.
1.378 - */
1.379 - short readShort() throws IOException;
1.380 -
1.381 - /**
1.382 - * Reads two input bytes and returns
1.383 - * an <code>int</code> value in the range <code>0</code>
1.384 - * through <code>65535</code>. Let <code>a</code>
1.385 - * be the first byte read and
1.386 - * <code>b</code>
1.387 - * be the second byte. The value returned is:
1.388 - * <p><pre><code>(((a & 0xff) << 8) | (b & 0xff))
1.389 - * </code></pre>
1.390 - * This method is suitable for reading the bytes
1.391 - * written by the <code>writeShort</code> method
1.392 - * of interface <code>DataOutput</code> if
1.393 - * the argument to <code>writeShort</code>
1.394 - * was intended to be a value in the range
1.395 - * <code>0</code> through <code>65535</code>.
1.396 - *
1.397 - * @return the unsigned 16-bit value read.
1.398 - * @exception EOFException if this stream reaches the end before reading
1.399 - * all the bytes.
1.400 - * @exception IOException if an I/O error occurs.
1.401 - */
1.402 - int readUnsignedShort() throws IOException;
1.403 -
1.404 - /**
1.405 - * Reads two input bytes and returns a <code>char</code> value.
1.406 - * Let <code>a</code>
1.407 - * be the first byte read and <code>b</code>
1.408 - * be the second byte. The value
1.409 - * returned is:
1.410 - * <p><pre><code>(char)((a << 8) | (b & 0xff))
1.411 - * </code></pre>
1.412 - * This method
1.413 - * is suitable for reading bytes written by
1.414 - * the <code>writeChar</code> method of interface
1.415 - * <code>DataOutput</code>.
1.416 - *
1.417 - * @return the <code>char</code> value read.
1.418 - * @exception EOFException if this stream reaches the end before reading
1.419 - * all the bytes.
1.420 - * @exception IOException if an I/O error occurs.
1.421 - */
1.422 - char readChar() throws IOException;
1.423 -
1.424 - /**
1.425 - * Reads four input bytes and returns an
1.426 - * <code>int</code> value. Let <code>a-d</code>
1.427 - * be the first through fourth bytes read. The value returned is:
1.428 - * <p><pre>
1.429 - * <code>
1.430 - * (((a & 0xff) << 24) | ((b & 0xff) << 16) |
1.431 - *  ((c & 0xff) << 8) | (d & 0xff))
1.432 - * </code></pre>
1.433 - * This method is suitable
1.434 - * for reading bytes written by the <code>writeInt</code>
1.435 - * method of interface <code>DataOutput</code>.
1.436 - *
1.437 - * @return the <code>int</code> value read.
1.438 - * @exception EOFException if this stream reaches the end before reading
1.439 - * all the bytes.
1.440 - * @exception IOException if an I/O error occurs.
1.441 - */
1.442 - int readInt() throws IOException;
1.443 -
1.444 - /**
1.445 - * Reads eight input bytes and returns
1.446 - * a <code>long</code> value. Let <code>a-h</code>
1.447 - * be the first through eighth bytes read.
1.448 - * The value returned is:
1.449 - * <p><pre> <code>
1.450 - * (((long)(a & 0xff) << 56) |
1.451 - * ((long)(b & 0xff) << 48) |
1.452 - * ((long)(c & 0xff) << 40) |
1.453 - * ((long)(d & 0xff) << 32) |
1.454 - * ((long)(e & 0xff) << 24) |
1.455 - * ((long)(f & 0xff) << 16) |
1.456 - * ((long)(g & 0xff) << 8) |
1.457 - * ((long)(h & 0xff)))
1.458 - * </code></pre>
1.459 - * <p>
1.460 - * This method is suitable
1.461 - * for reading bytes written by the <code>writeLong</code>
1.462 - * method of interface <code>DataOutput</code>.
1.463 - *
1.464 - * @return the <code>long</code> value read.
1.465 - * @exception EOFException if this stream reaches the end before reading
1.466 - * all the bytes.
1.467 - * @exception IOException if an I/O error occurs.
1.468 - */
1.469 - long readLong() throws IOException;
1.470 -
1.471 - /**
1.472 - * Reads four input bytes and returns
1.473 - * a <code>float</code> value. It does this
1.474 - * by first constructing an <code>int</code>
1.475 - * value in exactly the manner
1.476 - * of the <code>readInt</code>
1.477 - * method, then converting this <code>int</code>
1.478 - * value to a <code>float</code> in
1.479 - * exactly the manner of the method <code>Float.intBitsToFloat</code>.
1.480 - * This method is suitable for reading
1.481 - * bytes written by the <code>writeFloat</code>
1.482 - * method of interface <code>DataOutput</code>.
1.483 - *
1.484 - * @return the <code>float</code> value read.
1.485 - * @exception EOFException if this stream reaches the end before reading
1.486 - * all the bytes.
1.487 - * @exception IOException if an I/O error occurs.
1.488 - */
1.489 - float readFloat() throws IOException;
1.490 -
1.491 - /**
1.492 - * Reads eight input bytes and returns
1.493 - * a <code>double</code> value. It does this
1.494 - * by first constructing a <code>long</code>
1.495 - * value in exactly the manner
1.496 - * of the <code>readlong</code>
1.497 - * method, then converting this <code>long</code>
1.498 - * value to a <code>double</code> in exactly
1.499 - * the manner of the method <code>Double.longBitsToDouble</code>.
1.500 - * This method is suitable for reading
1.501 - * bytes written by the <code>writeDouble</code>
1.502 - * method of interface <code>DataOutput</code>.
1.503 - *
1.504 - * @return the <code>double</code> value read.
1.505 - * @exception EOFException if this stream reaches the end before reading
1.506 - * all the bytes.
1.507 - * @exception IOException if an I/O error occurs.
1.508 - */
1.509 - double readDouble() throws IOException;
1.510 -
1.511 - /**
1.512 - * Reads the next line of text from the input stream.
1.513 - * It reads successive bytes, converting
1.514 - * each byte separately into a character,
1.515 - * until it encounters a line terminator or
1.516 - * end of
1.517 - * file; the characters read are then
1.518 - * returned as a <code>String</code>. Note
1.519 - * that because this
1.520 - * method processes bytes,
1.521 - * it does not support input of the full Unicode
1.522 - * character set.
1.523 - * <p>
1.524 - * If end of file is encountered
1.525 - * before even one byte can be read, then <code>null</code>
1.526 - * is returned. Otherwise, each byte that is
1.527 - * read is converted to type <code>char</code>
1.528 - * by zero-extension. If the character <code>'\n'</code>
1.529 - * is encountered, it is discarded and reading
1.530 - * ceases. If the character <code>'\r'</code>
1.531 - * is encountered, it is discarded and, if
1.532 - * the following byte converts  to the
1.533 - * character <code>'\n'</code>, then that is
1.534 - * discarded also; reading then ceases. If
1.535 - * end of file is encountered before either
1.536 - * of the characters <code>'\n'</code> and
1.537 - * <code>'\r'</code> is encountered, reading
1.538 - * ceases. Once reading has ceased, a <code>String</code>
1.539 - * is returned that contains all the characters
1.540 - * read and not discarded, taken in order.
1.541 - * Note that every character in this string
1.542 - * will have a value less than <code>\u0100</code>,
1.543 - * that is, <code>(char)256</code>.
1.544 - *
1.545 - * @return the next line of text from the input stream,
1.546 - * or <CODE>null</CODE> if the end of file is
1.547 - * encountered before a byte can be read.
1.548 - * @exception IOException if an I/O error occurs.
1.549 - */
1.550 - String readLine() throws IOException;
1.551 -
1.552 - /**
1.553 - * Reads in a string that has been encoded using a
1.554 - * <a href="#modified-utf-8">modified UTF-8</a>
1.555 - * format.
1.556 - * The general contract of <code>readUTF</code>
1.557 - * is that it reads a representation of a Unicode
1.558 - * character string encoded in modified
1.559 - * UTF-8 format; this string of characters
1.560 - * is then returned as a <code>String</code>.
1.561 - * <p>
1.562 - * First, two bytes are read and used to
1.563 - * construct an unsigned 16-bit integer in
1.564 - * exactly the manner of the <code>readUnsignedShort</code>
1.565 - * method . This integer value is called the
1.566 - * <i>UTF length</i> and specifies the number
1.567 - * of additional bytes to be read. These bytes
1.568 - * are then converted to characters by considering
1.569 - * them in groups. The length of each group
1.570 - * is computed from the value of the first
1.571 - * byte of the group. The byte following a
1.572 - * group, if any, is the first byte of the
1.573 - * next group.
1.574 - * <p>
1.575 - * If the first byte of a group
1.576 - * matches the bit pattern <code>0xxxxxxx</code>
1.577 - * (where <code>x</code> means "may be <code>0</code>
1.578 - * or <code>1</code>"), then the group consists
1.579 - * of just that byte. The byte is zero-extended
1.580 - * to form a character.
1.581 - * <p>
1.582 - * If the first byte
1.583 - * of a group matches the bit pattern <code>110xxxxx</code>,
1.584 - * then the group consists of that byte <code>a</code>
1.585 - * and a second byte <code>b</code>. If there
1.586 - * is no byte <code>b</code> (because byte
1.587 - * <code>a</code> was the last of the bytes
1.588 - * to be read), or if byte <code>b</code> does
1.589 - * not match the bit pattern <code>10xxxxxx</code>,
1.590 - * then a <code>UTFDataFormatException</code>
1.591 - * is thrown. Otherwise, the group is converted
1.592 - * to the character:<p>
1.593 - * <pre><code>(char)(((a& 0x1F) << 6) | (b & 0x3F))
1.594 - * </code></pre>
1.595 - * If the first byte of a group
1.596 - * matches the bit pattern <code>1110xxxx</code>,
1.597 - * then the group consists of that byte <code>a</code>
1.598 - * and two more bytes <code>b</code> and <code>c</code>.
1.599 - * If there is no byte <code>c</code> (because
1.600 - * byte <code>a</code> was one of the last
1.601 - * two of the bytes to be read), or either
1.602 - * byte <code>b</code> or byte <code>c</code>
1.603 - * does not match the bit pattern <code>10xxxxxx</code>,
1.604 - * then a <code>UTFDataFormatException</code>
1.605 - * is thrown. Otherwise, the group is converted
1.606 - * to the character:<p>
1.607 - * <pre><code>
1.608 - * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
1.609 - * </code></pre>
1.610 - * If the first byte of a group matches the
1.611 - * pattern <code>1111xxxx</code> or the pattern
1.612 - * <code>10xxxxxx</code>, then a <code>UTFDataFormatException</code>
1.613 - * is thrown.
1.614 - * <p>
1.615 - * If end of file is encountered
1.616 - * at any time during this entire process,
1.617 - * then an <code>EOFException</code> is thrown.
1.618 - * <p>
1.619 - * After every group has been converted to
1.620 - * a character by this process, the characters
1.621 - * are gathered, in the same order in which
1.622 - * their corresponding groups were read from
1.623 - * the input stream, to form a <code>String</code>,
1.624 - * which is returned.
1.625 - * <p>
1.626 - * The <code>writeUTF</code>
1.627 - * method of interface <code>DataOutput</code>
1.628 - * may be used to write data that is suitable
1.629 - * for reading by this method.
1.630 - * @return a Unicode string.
1.631 - * @exception EOFException if this stream reaches the end
1.632 - * before reading all the bytes.
1.633 - * @exception IOException if an I/O error occurs.
1.634 - * @exception UTFDataFormatException if the bytes do not represent a
1.635 - * valid modified UTF-8 encoding of a string.
1.636 - */
1.637 - String readUTF() throws IOException;
1.638 -}