1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/mini/src/main/java/java/io/DataInput.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,635 @@
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 +}