KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > 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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc readLine() throws IOException JavaDoc;
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 JavaDoc readUTF() throws IOException JavaDoc;
630 }
631
Popular Tags