DataInput


1   /*
2    * @(#)DataInput.java   1.23 04/06/03
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.io;
9   
10  /**
11   * The <code>DataInput</code> interface provides
12   * for reading bytes from a binary stream and
13   * reconstructing from them data in any of
14   * the Java primitive types. There is also
15   * a
16   * facility for reconstructing a <code>String</code>
17   * from data in
18   * <a HREF="#modified-utf-8">modified UTF-8</a>
19   * format.
20   * <p>
21   * It is generally true of all the reading
22   * routines in this interface that if end of
23   * file is reached before the desired number
24   * of bytes has been read, an <code>EOFException</code>
25   * (which is a kind of <code>IOException</code>)
26   * is thrown. If any byte cannot be read for
27   * any reason other than end of file, an <code>IOException</code>
28   * other than <code>EOFException</code> is
29   * thrown. In particular, an <code>IOException</code>
30   * may be thrown if the input stream has been
31   * closed.
32   *
33   * <h4><a name="modified-utf-8">Modified UTF-8</a></h4>
34   * <p>
35   * Implementations of the DataInput and DataOutput interfaces represent
36   * Unicode strings in a format that is a slight modification of UTF-8.
37   * (For information regarding the standard UTF-8 format, see section
38   * <i>3.9 Unicode Encoding Forms</i> of <i>The Unicode Standard, Version
39   * 4.0</i>).
40   * Note that in the following tables, the most significant bit appears in the
41   * far left-hand column.
42   * <p>
43   * All characters in the range <code>'&#92;u0001'</code> to
44   * <code>'&#92;u007F'</code> are represented by a single byte:
45   *
46   * <blockquote>
47   *   <table border="1" cellspacing="0" cellpadding="8" width="50%"
48   *          summary="Bit values and bytes">
49   *     <tr>
50   *       <td></td>
51   *       <th id="bit">Bit Values</th>
52   *     </tr>
53   *     <tr>
54   *       <th id="byte1">Byte 1</th>
55   *       <td>
56   *         <table border="1" cellspacing="0" width="100%">
57   *           <tr>
58   *             <td width="12%"><center>0</center>
59   *             <td colspan="7"><center>bits 6-0</center>
60   *           </tr>
61   *         </table>
62   *       </td>
63   *     </tr>
64   *   </table>
65   * </blockquote>
66   *
67   * <p>
68   * The null character <code>'&#92;u0000'</code> and characters in the
69   * range <code>'&#92;u0080'</code> to <code>'&#92;u07FF'</code> are
70   * represented by a pair of bytes:
71   *
72   * <blockquote>
73   *   <table border="1" cellspacing="0" cellpadding="8" width="50%"
74   *          summary="Bit values and bytes">
75   *     <tr>
76   *       <td></td>
77   *       <th id="bit">Bit Values</th>
78   *     </tr>
79   *     <tr>
80   *       <th id="byte1">Byte 1</th>
81   *       <td>
82   *         <table border="1" cellspacing="0" width="100%">
83   *           <tr>
84   *             <td width="12%"><center>1</center>
85   *             <td width="13%"><center>1</center>
86   *             <td width="12%"><center>0</center>
87   *             <td colspan="5"><center>bits 10-6</center>
88   *           </tr>
89   *         </table>
90   *       </td>
91   *     </tr>
92   *     <tr>
93   *       <th id="byte2">Byte 2</th>
94   *       <td>
95   *         <table border="1" cellspacing="0" width="100%">
96   *           <tr>
97   *             <td width="12%"><center>1</center>
98   *             <td width="13%"><center>0</center>
99   *             <td colspan="6"><center>bits 5-0</center>
100  *           </tr>
101  *         </table>
102  *       </td>
103  *     </tr>
104  *   </table>
105  *  </blockquote>
106  *
107  * <br>
108  * <code>char</code> values in the range <code>'&#92;u0800'</code> to
109  * <code>'&#92;uFFFF'</code> are represented by three bytes:
110  *
111  * <blockquote>
112  *   <table border="1" cellspacing="0" cellpadding="8" width="50%"
113  *          summary="Bit values and bytes">
114  *     <tr>
115  *       <td></td>
116  *       <th id="bit">Bit Values</th>
117  *     </tr>
118  *     <tr>
119  *       <th id="byte1">Byte 1</th>
120  *       <td>
121  *         <table border="1" cellspacing="0" width="100%">
122  *           <tr>
123  *             <td width="12%"><center>1</center>
124  *             <td width="13%"><center>1</center>
125  *             <td width="12%"><center>1</center>
126  *             <td width="13%"><center>0</center>
127  *             <td colspan="4"><center>bits 15-12</center>
128  *           </tr>
129  *         </table>
130  *       </td>
131  *     </tr>
132  *     <tr>
133  *       <th id="byte2">Byte 2</th>
134  *       <td>
135  *         <table border="1" cellspacing="0" width="100%">
136  *           <tr>
137  *             <td width="12%"><center>1</center>
138  *             <td width="13%"><center>0</center>
139  *             <td colspan="6"><center>bits 11-6</center>
140  *           </tr>
141  *         </table>
142  *       </td>
143  *     </tr>
144  *     <tr>
145  *       <th id="byte3">Byte 3</th>
146  *       <td>
147  *         <table border="1" cellspacing="0" width="100%">
148  *           <tr>
149  *             <td width="12%"><center>1</center>
150  *             <td width="13%"><center>0</center>
151  *             <td colspan="6"><center>bits 5-0</center>
152  *           </tr>
153  *         </table>
154  *       </td>
155  *     </tr>
156  *   </table>
157  *  </blockquote>
158  *
159  * <p>
160  * The differences between this format and the
161  * standard UTF-8 format are the following:
162  * <ul>
163  * <li>The null byte <code>'&#92;u0000'</code> is encoded in 2-byte format
164  *     rather than 1-byte, so that the encoded strings never have
165  *     embedded nulls.
166  * <li>Only the 1-byte, 2-byte, and 3-byte formats are used.
167  * <li><a HREF="../lang/Character.html#unicode">Supplementary characters</a>
168  *     are represented in the form of surrogate pairs.
169  * </ul>
170  * @author  Frank Yellin
171  * @version 1.23, 06/03/04
172  * @see     java.io.DataInputStream
173  * @see     java.io.DataOutput
174  * @since   JDK1.0
175  */
176 public
177 interface DataInput {
178     /**
179      * Reads some bytes from an input
180      * stream and stores them into the buffer
181      * array <code>b</code>. The number of bytes
182      * read is equal
183      * to the length of <code>b</code>.
184      * <p>
185      * This method blocks until one of the
186      * following conditions occurs:<p>
187      * <ul>
188      * <li><code>b.length</code>
189      * bytes of input data are available, in which
190      * case a normal return is made.
191      *
192      * <li>End of
193      * file is detected, in which case an <code>EOFException</code>
194      * is thrown.
195      *
196      * <li>An I/O error occurs, in
197      * which case an <code>IOException</code> other
198      * than <code>EOFException</code> is thrown.
199      * </ul>
200      * <p>
201      * If <code>b</code> is <code>null</code>,
202      * a <code>NullPointerException</code> is thrown.
203      * If <code>b.length</code> is zero, then
204      * no bytes are read. Otherwise, the first
205      * byte read is stored into element <code>b[0]</code>,
206      * the next one into <code>b[1]</code>, and
207      * so on.
208      * If an exception is thrown from
209      * this method, then it may be that some but
210      * not all bytes of <code>b</code> have been
211      * updated with data from the input stream.
212      *
213      * @param     b   the buffer into which the data is read.
214      * @exception  EOFException  if this stream reaches the end before reading
215      *               all the bytes.
216      * @exception  IOException   if an I/O error occurs.
217      */
218     void readFully(byte b[]) throws IOException  ;
219 
220     /**
221      *
222      * Reads <code>len</code>
223      * bytes from
224      * an input stream.
225      * <p>
226      * This method
227      * blocks until one of the following conditions
228      * occurs:<p>
229      * <ul>
230      * <li><code>len</code> bytes
231      * of input data are available, in which case
232      * a normal return is made.
233      *
234      * <li>End of file
235      * is detected, in which case an <code>EOFException</code>
236      * is thrown.
237      *
238      * <li>An I/O error occurs, in
239      * which case an <code>IOException</code> other
240      * than <code>EOFException</code> is thrown.
241      * </ul>
242      * <p>
243      * If <code>b</code> is <code>null</code>,
244      * a <code>NullPointerException</code> is thrown.
245      * If <code>off</code> is negative, or <code>len</code>
246      * is negative, or <code>off+len</code> is
247      * greater than the length of the array <code>b</code>,
248      * then an <code>IndexOutOfBoundsException</code>
249      * is thrown.
250      * If <code>len</code> is zero,
251      * then no bytes are read. Otherwise, the first
252      * byte read is stored into element <code>b[off]</code>,
253      * the next one into <code>b[off+1]</code>,
254      * and so on. The number of bytes read is,
255      * at most, equal to <code>len</code>.
256      *
257      * @param     b   the buffer into which the data is read.
258      * @param off  an int specifying the offset into the data.
259      * @param len  an int specifying the number of bytes to read.
260      * @exception  EOFException  if this stream reaches the end before reading
261      *               all the bytes.
262      * @exception  IOException   if an I/O error occurs.
263      */
264     void readFully(byte b[], int off, int len) throws IOException  ;
265 
266     /**
267      * Makes an attempt to skip over
268      * <code>n</code> bytes
269      * of data from the input
270      * stream, discarding the skipped bytes. However,
271      * it may skip
272      * over some smaller number of
273      * bytes, possibly zero. This may result from
274      * any of a
275      * number of conditions; reaching
276      * end of file before <code>n</code> bytes
277      * have been skipped is
278      * only one possibility.
279      * This method never throws an <code>EOFException</code>.
280      * The actual
281      * number of bytes skipped is returned.
282      *
283      * @param      n   the number of bytes to be skipped.
284      * @return     the number of bytes actually skipped.
285      * @exception  IOException   if an I/O error occurs.
286      */
287     int skipBytes(int n) throws IOException  ;
288 
289     /**
290      * Reads one input byte and returns
291      * <code>true</code> if that byte is nonzero,
292      * <code>false</code> if that byte is zero.
293      * This method is suitable for reading
294      * the byte written by the <code>writeBoolean</code>
295      * method of interface <code>DataOutput</code>.
296      *
297      * @return     the <code>boolean</code> value read.
298      * @exception  EOFException  if this stream reaches the end before reading
299      *               all the bytes.
300      * @exception  IOException   if an I/O error occurs.
301      */
302     boolean readBoolean() throws IOException  ;
303 
304     /**
305      * Reads and returns one input byte.
306      * The byte is treated as a signed value in
307      * the range <code>-128</code> through <code>127</code>,
308      * inclusive.
309      * This method is suitable for
310      * reading the byte written by the <code>writeByte</code>
311      * method of interface <code>DataOutput</code>.
312      *
313      * @return     the 8-bit value read.
314      * @exception  EOFException  if this stream reaches the end before reading
315      *               all the bytes.
316      * @exception  IOException   if an I/O error occurs.
317      */
318     byte readByte() throws IOException  ;
319 
320     /**
321      * Reads one input byte, zero-extends
322      * it to type <code>int</code>, and returns
323      * the result, which is therefore in the range
324      * <code>0</code>
325      * through <code>255</code>.
326      * This method is suitable for reading
327      * the byte written by the <code>writeByte</code>
328      * method of interface <code>DataOutput</code>
329      * if the argument to <code>writeByte</code>
330      * was intended to be a value in the range
331      * <code>0</code> through <code>255</code>.
332      *
333      * @return     the unsigned 8-bit value read.
334      * @exception  EOFException  if this stream reaches the end before reading
335      *               all the bytes.
336      * @exception  IOException   if an I/O error occurs.
337      */
338     int readUnsignedByte() throws IOException  ;
339 
340     /**
341      * Reads two input bytes and returns
342      * a <code>short</code> value. Let <code>a</code>
343      * be the first byte read and <code>b</code>
344      * be the second byte. The value
345      * returned
346      * is:
347      * <p><pre><code>(short)((a &lt;&lt; 8) | (b &amp; 0xff))
348      * </code></pre>
349      * This method
350      * is suitable for reading the bytes written
351      * by the <code>writeShort</code> method of
352      * interface <code>DataOutput</code>.
353      *
354      * @return     the 16-bit value read.
355      * @exception  EOFException  if this stream reaches the end before reading
356      *               all the bytes.
357      * @exception  IOException   if an I/O error occurs.
358      */
359     short readShort() throws IOException  ;
360 
361     /**
362      * Reads two input bytes and returns
363      * an <code>int</code> value in the range <code>0</code>
364      * through <code>65535</code>. Let <code>a</code>
365      * be the first byte read and
366      * <code>b</code>
367      * be the second byte. The value returned is:
368      * <p><pre><code>(((a &amp; 0xff) &lt;&lt; 8) | (b &amp; 0xff))
369      * </code></pre>
370      * This method is suitable for reading the bytes
371      * written by the <code>writeShort</code> method
372      * of interface <code>DataOutput</code>  if
373      * the argument to <code>writeShort</code>
374      * was intended to be a value in the range
375      * <code>0</code> through <code>65535</code>.
376      *
377      * @return     the unsigned 16-bit value read.
378      * @exception  EOFException  if this stream reaches the end before reading
379      *               all the bytes.
380      * @exception  IOException   if an I/O error occurs.
381      */
382     int readUnsignedShort() throws IOException  ;
383 
384     /**
385      * Reads an input <code>char</code> and returns the <code>char</code> value.
386      * A Unicode <code>char</code> is made up of two bytes.
387      * Let <code>a</code>
388      * be the first byte read and <code>b</code>
389      * be the second byte. The value
390      * returned is:
391      * <p><pre><code>(char)((a &lt;&lt; 8) | (b &amp; 0xff))
392      * </code></pre>
393      * This method
394      * is suitable for reading bytes written by
395      * the <code>writeChar</code> method of interface
396      * <code>DataOutput</code>.
397      *
398      * @return     the Unicode <code>char</code> read.
399      * @exception  EOFException  if this stream reaches the end before reading
400      *               all the bytes.
401      * @exception  IOException   if an I/O error occurs.
402      */
403     char readChar() throws IOException  ;
404 
405     /**
406      * Reads four input bytes and returns an
407      * <code>int</code> value. Let <code>a</code>
408      * be the first byte read, <code>b</code> be
409      * the second byte, <code>c</code> be the third
410      * byte,
411      * and <code>d</code> be the fourth
412      * byte. The value returned is:
413      * <p><pre>
414      * <code>
415      * (((a &amp; 0xff) &lt;&lt; 24) | ((b &amp; 0xff) &lt;&lt; 16) |
416      * &#32;((c &amp; 0xff) &lt;&lt; 8) | (d &amp; 0xff))
417      * </code></pre>
418      * This method is suitable
419      * for reading bytes written by the <code>writeInt</code>
420      * method of interface <code>DataOutput</code>.
421      *
422      * @return     the <code>int</code> value read.
423      * @exception  EOFException  if this stream reaches the end before reading
424      *               all the bytes.
425      * @exception  IOException   if an I/O error occurs.
426      */
427     int readInt() throws IOException  ;
428 
429     /**
430      * Reads eight input bytes and returns
431      * a <code>long</code> value. Let <code>a</code>
432      * be the first byte read, <code>b</code> be
433      * the second byte, <code>c</code> be the third
434      * byte, <code>d</code>
435      * be the fourth byte,
436      * <code>e</code> be the fifth byte, <code>f</code>
437      * be the sixth byte, <code>g</code> be the
438      * seventh byte,
439      * and <code>h</code> be the
440      * eighth byte. The value returned is:
441      * <p><pre> <code>
442      * (((long)(a &amp; 0xff) &lt;&lt; 56) |
443      *  ((long)(b &amp; 0xff) &lt;&lt; 48) |
444      *  ((long)(c &amp; 0xff) &lt;&lt; 40) |
445      *  ((long)(d &amp; 0xff) &lt;&lt; 32) |
446      *  ((long)(e &amp; 0xff) &lt;&lt; 24) |
447      *  ((long)(f &amp; 0xff) &lt;&lt; 16) |
448      *  ((long)(g &amp; 0xff) &lt;&lt;  8) |
449      *  ((long)(h &amp; 0xff)))
450      * </code></pre>
451      * <p>
452      * This method is suitable
453      * for reading bytes written by the <code>writeLong</code>
454      * method of interface <code>DataOutput</code>.
455      *
456      * @return     the <code>long</code> value read.
457      * @exception  EOFException  if this stream reaches the end before reading
458      *               all the bytes.
459      * @exception  IOException   if an I/O error occurs.
460      */
461     long readLong() throws IOException  ;
462 
463     /**
464      * Reads four input bytes and returns
465      * a <code>float</code> value. It does this
466      * by first constructing an <code>int</code>
467      * value in exactly the manner
468      * of the <code>readInt</code>
469      * method, then converting this <code>int</code>
470      * value to a <code>float</code> in
471      * exactly the manner of the method <code>Float.intBitsToFloat</code>.
472      * This method is suitable for reading
473      * bytes written by the <code>writeFloat</code>
474      * method of interface <code>DataOutput</code>.
475      *
476      * @return     the <code>float</code> value read.
477      * @exception  EOFException  if this stream reaches the end before reading
478      *               all the bytes.
479      * @exception  IOException   if an I/O error occurs.
480      */
481     float readFloat() throws IOException  ;
482 
483     /**
484      * Reads eight input bytes and returns
485      * a <code>double</code> value. It does this
486      * by first constructing a <code>long</code>
487      * value in exactly the manner
488      * of the <code>readlong</code>
489      * method, then converting this <code>long</code>
490      * value to a <code>double</code> in exactly
491      * the manner of the method <code>Double.longBitsToDouble</code>.
492      * This method is suitable for reading
493      * bytes written by the <code>writeDouble</code>
494      * method of interface <code>DataOutput</code>.
495      *
496      * @return     the <code>double</code> value read.
497      * @exception  EOFException  if this stream reaches the end before reading
498      *               all the bytes.
499      * @exception  IOException   if an I/O error occurs.
500      */
501     double readDouble() throws IOException  ;
502 
503     /**
504      * Reads the next line of text from the input stream.
505      * It reads successive bytes, converting
506      * each byte separately into a character,
507      * until it encounters a line terminator or
508      * end of
509      * file; the characters read are then
510      * returned as a <code>String</code>. Note
511      * that because this
512      * method processes bytes,
513      * it does not support input of the full Unicode
514      * character set.
515      * <p>
516      * If end of file is encountered
517      * before even one byte can be read, then <code>null</code>
518      * is returned. Otherwise, each byte that is
519      * read is converted to type <code>char</code>
520      * by zero-extension. If the character <code>'\n'</code>
521      * is encountered, it is discarded and reading
522      * ceases. If the character <code>'\r'</code>
523      * is encountered, it is discarded and, if
524      * the following byte converts &#32;to the
525      * character <code>'\n'</code>, then that is
526      * discarded also; reading then ceases. If
527      * end of file is encountered before either
528      * of the characters <code>'\n'</code> and
529      * <code>'\r'</code> is encountered, reading
530      * ceases. Once reading has ceased, a <code>String</code>
531      * is returned that contains all the characters
532      * read and not discarded, taken in order.
533      * Note that every character in this string
534      * will have a value less than <code>&#92;u0100</code>,
535      * that is, <code>(char)256</code>.
536      *
537      * @return the next line of text from the input stream,
538      *         or <CODE>null</CODE> if the end of file is
539      *         encountered before a byte can be read. 
540      * @exception  IOException  if an I/O error occurs.
541      */
542     String   readLine() throws IOException  ;
543 
544     /**
545      * Reads in a string that has been encoded using a
546      * <a HREF="#modified-utf-8">modified UTF-8</a>
547      * format.
548      * The general contract of <code>readUTF</code>
549      * is that it reads a representation of a Unicode
550      * character string encoded in modified
551      * UTF-8 format; this string of characters
552      * is then returned as a <code>String</code>.
553      * <p>
554      * First, two bytes are read and used to
555      * construct an unsigned 16-bit integer in
556      * exactly the manner of the <code>readUnsignedShort</code>
557      * method . This integer value is called the
558      * <i>UTF length</i> and specifies the number
559      * of additional bytes to be read. These bytes
560      * are then converted to characters by considering
561      * them in groups. The length of each group
562      * is computed from the value of the first
563      * byte of the group. The byte following a
564      * group, if any, is the first byte of the
565      * next group.
566      * <p>
567      * If the first byte of a group
568      * matches the bit pattern <code>0xxxxxxx</code>
569      * (where <code>x</code> means "may be <code>0</code>
570      * or <code>1</code>"), then the group consists
571      * of just that byte. The byte is zero-extended
572      * to form a character.
573      * <p>
574      * If the first byte
575      * of a group matches the bit pattern <code>110xxxxx</code>,
576      * then the group consists of that byte <code>a</code>
577      * and a second byte <code>b</code>. If there
578      * is no byte <code>b</code> (because byte
579      * <code>a</code> was the last of the bytes
580      * to be read), or if byte <code>b</code> does
581      * not match the bit pattern <code>10xxxxxx</code>,
582      * then a <code>UTFDataFormatException</code>
583      * is thrown. Otherwise, the group is converted
584      * to the character:<p>
585      * <pre><code>(char)(((a&amp; 0x1F) &lt;&lt; 6) | (b &amp; 0x3F))
586      * </code></pre>
587      * If the first byte of a group
588      * matches the bit pattern <code>1110xxxx</code>,
589      * then the group consists of that byte <code>a</code>
590      * and two more bytes <code>b</code> and <code>c</code>.
591      * If there is no byte <code>c</code> (because
592      * byte <code>a</code> was one of the last
593      * two of the bytes to be read), or either
594      * byte <code>b</code> or byte <code>c</code>
595      * does not match the bit pattern <code>10xxxxxx</code>,
596      * then a <code>UTFDataFormatException</code>
597      * is thrown. Otherwise, the group is converted
598      * to the character:<p>
599      * <pre><code>
600      * (char)(((a &amp; 0x0F) &lt;&lt; 12) | ((b &amp; 0x3F) &lt;&lt; 6) | (c &amp; 0x3F))
601      * </code></pre>
602      * If the first byte of a group matches the
603      * pattern <code>1111xxxx</code> or the pattern
604      * <code>10xxxxxx</code>, then a <code>UTFDataFormatException</code>
605      * is thrown.
606      * <p>
607      * If end of file is encountered
608      * at any time during this entire process,
609      * then an <code>EOFException</code> is thrown.
610      * <p>
611      * After every group has been converted to
612      * a character by this process, the characters
613      * are gathered, in the same order in which
614      * their corresponding groups were read from
615      * the input stream, to form a <code>String</code>,
616      * which is returned.
617      * <p>
618      * The <code>writeUTF</code>
619      * method of interface <code>DataOutput</code>
620      * may be used to write data that is suitable
621      * for reading by this method.
622      * @return     a Unicode string.
623      * @exception  EOFException            if this stream reaches the end
624      *               before reading all the bytes.
625      * @exception  IOException             if an I/O error occurs.
626      * @exception  UTFDataFormatException  if the bytes do not represent a
627      *               valid modified UTF-8 encoding of a string.
628      */
629     String   readUTF() throws IOException  ;
630 }
631
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags