author | jjg |
Thu, 27 Apr 2017 09:47:40 -0700 | |
changeset 44848 | e946981dc37c |
parent 44844 | b2b4d98404ba |
child 45124 | 144479e89cdb |
permissions | -rw-r--r-- |
2 | 1 |
/* |
37591
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
2 |
* Copyright (c) 1995, 2016, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.io; |
|
27 |
||
28 |
/** |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
29 |
* The {@code DataInput} interface provides |
2 | 30 |
* for reading bytes from a binary stream and |
31 |
* reconstructing from them data in any of |
|
32 |
* the Java primitive types. There is also |
|
33 |
* a |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
34 |
* facility for reconstructing a {@code String} |
2 | 35 |
* from data in |
36 |
* <a href="#modified-utf-8">modified UTF-8</a> |
|
37 |
* format. |
|
38 |
* <p> |
|
39 |
* It is generally true of all the reading |
|
40 |
* routines in this interface that if end of |
|
41 |
* file is reached before the desired number |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
42 |
* of bytes has been read, an {@code EOFException} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
43 |
* (which is a kind of {@code IOException}) |
2 | 44 |
* is thrown. If any byte cannot be read for |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
45 |
* any reason other than end of file, an {@code IOException} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
46 |
* other than {@code EOFException} is |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
47 |
* thrown. In particular, an {@code IOException} |
2 | 48 |
* may be thrown if the input stream has been |
49 |
* closed. |
|
50 |
* |
|
44844
b2b4d98404ba
8179364: update "<a name=" in java.base module to use id attribute
jjg
parents:
37591
diff
changeset
|
51 |
* <h3><a id="modified-utf-8">Modified UTF-8</a></h3> |
2 | 52 |
* <p> |
53 |
* Implementations of the DataInput and DataOutput interfaces represent |
|
54 |
* Unicode strings in a format that is a slight modification of UTF-8. |
|
55 |
* (For information regarding the standard UTF-8 format, see section |
|
56 |
* <i>3.9 Unicode Encoding Forms</i> of <i>The Unicode Standard, Version |
|
57 |
* 4.0</i>). |
|
19029 | 58 |
* Note that in the following table, the most significant bit appears in the |
2 | 59 |
* far left-hand column. |
60 |
* |
|
61 |
* <blockquote> |
|
19029 | 62 |
* <table border="1" cellspacing="0" cellpadding="8" |
2 | 63 |
* summary="Bit values and bytes"> |
64 |
* <tr> |
|
19029 | 65 |
* <th colspan="9"><span style="font-weight:normal"> |
66 |
* All characters in the range {@code '\u005Cu0001'} to |
|
67 |
* {@code '\u005Cu007F'} are represented by a single byte:</span></th> |
|
68 |
* </tr> |
|
69 |
* <tr> |
|
2 | 70 |
* <td></td> |
19029 | 71 |
* <th colspan="8" id="bit_a">Bit Values</th> |
2 | 72 |
* </tr> |
73 |
* <tr> |
|
18786 | 74 |
* <th id="byte1_a">Byte 1</th> |
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
75 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
76 |
* <td colspan="7" style="text-align:center">bits 6-0 |
2 | 77 |
* </tr> |
19029 | 78 |
* <tr> |
79 |
* <th colspan="9"><span style="font-weight:normal"> |
|
80 |
* The null character {@code '\u005Cu0000'} and characters |
|
81 |
* in the range {@code '\u005Cu0080'} to {@code '\u005Cu07FF'} are |
|
82 |
* represented by a pair of bytes:</span></th> |
|
83 |
* </tr> |
|
2 | 84 |
* <tr> |
85 |
* <td></td> |
|
19029 | 86 |
* <th colspan="8" id="bit_b">Bit Values</th> |
2 | 87 |
* </tr> |
88 |
* <tr> |
|
18786 | 89 |
* <th id="byte1_b">Byte 1</th> |
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
90 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
91 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
92 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
93 |
* <td colspan="5" style="text-align:center">bits 10-6 |
2 | 94 |
* </tr> |
95 |
* <tr> |
|
18786 | 96 |
* <th id="byte2_a">Byte 2</th> |
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
97 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
98 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
99 |
* <td colspan="6" style="text-align:center">bits 5-0 |
2 | 100 |
* </tr> |
19029 | 101 |
* <tr> |
102 |
* <th colspan="9"><span style="font-weight:normal"> |
|
103 |
* {@code char} values in the range {@code '\u005Cu0800'} |
|
104 |
* to {@code '\u005CuFFFF'} are represented by three bytes:</span></th> |
|
105 |
* </tr> |
|
2 | 106 |
* <tr> |
107 |
* <td></td> |
|
19029 | 108 |
* <th colspan="8"id="bit_c">Bit Values</th> |
2 | 109 |
* </tr> |
110 |
* <tr> |
|
18786 | 111 |
* <th id="byte1_c">Byte 1</th> |
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
112 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
113 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
114 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
115 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
116 |
* <td colspan="4" style="text-align:center">bits 15-12 |
2 | 117 |
* </tr> |
118 |
* <tr> |
|
18786 | 119 |
* <th id="byte2_b">Byte 2</th> |
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
120 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
121 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
122 |
* <td colspan="6" style="text-align:center">bits 11-6 |
2 | 123 |
* </tr> |
124 |
* <tr> |
|
125 |
* <th id="byte3">Byte 3</th> |
|
44848
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
126 |
* <td style="text-align:center">1 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
127 |
* <td style="text-align:center">0 |
e946981dc37c
8179370: Replace use of <tt>, <center> and <font> tags in java.base
jjg
parents:
44844
diff
changeset
|
128 |
* <td colspan="6" style="text-align:center">bits 5-0 |
2 | 129 |
* </tr> |
130 |
* </table> |
|
19029 | 131 |
* </blockquote> |
2 | 132 |
* <p> |
133 |
* The differences between this format and the |
|
134 |
* standard UTF-8 format are the following: |
|
135 |
* <ul> |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
136 |
* <li>The null byte {@code '\u005Cu0000'} is encoded in 2-byte format |
2 | 137 |
* rather than 1-byte, so that the encoded strings never have |
138 |
* embedded nulls. |
|
139 |
* <li>Only the 1-byte, 2-byte, and 3-byte formats are used. |
|
140 |
* <li><a href="../lang/Character.html#unicode">Supplementary characters</a> |
|
141 |
* are represented in the form of surrogate pairs. |
|
142 |
* </ul> |
|
143 |
* @author Frank Yellin |
|
144 |
* @see java.io.DataInputStream |
|
145 |
* @see java.io.DataOutput |
|
24865
09b1d992ca72
8044740: Convert all JDK versions used in @since tag to 1.n[.n] in jdk repo
henryjen
parents:
21624
diff
changeset
|
146 |
* @since 1.0 |
2 | 147 |
*/ |
148 |
public |
|
149 |
interface DataInput { |
|
150 |
/** |
|
151 |
* Reads some bytes from an input |
|
152 |
* stream and stores them into the buffer |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
153 |
* array {@code b}. The number of bytes |
2 | 154 |
* read is equal |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
155 |
* to the length of {@code b}. |
2 | 156 |
* <p> |
157 |
* This method blocks until one of the |
|
21334 | 158 |
* following conditions occurs: |
2 | 159 |
* <ul> |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
160 |
* <li>{@code b.length} |
2 | 161 |
* bytes of input data are available, in which |
162 |
* case a normal return is made. |
|
163 |
* |
|
164 |
* <li>End of |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
165 |
* file is detected, in which case an {@code EOFException} |
2 | 166 |
* is thrown. |
167 |
* |
|
168 |
* <li>An I/O error occurs, in |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
169 |
* which case an {@code IOException} other |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
170 |
* than {@code EOFException} is thrown. |
2 | 171 |
* </ul> |
172 |
* <p> |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
173 |
* If {@code b} is {@code null}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
174 |
* a {@code NullPointerException} is thrown. |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
175 |
* If {@code b.length} is zero, then |
2 | 176 |
* no bytes are read. Otherwise, the first |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
177 |
* byte read is stored into element {@code b[0]}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
178 |
* the next one into {@code b[1]}, and |
2 | 179 |
* so on. |
180 |
* If an exception is thrown from |
|
181 |
* this method, then it may be that some but |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
182 |
* not all bytes of {@code b} have been |
2 | 183 |
* updated with data from the input stream. |
184 |
* |
|
37591
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
185 |
* @param b the buffer into which the data is read. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
186 |
* @throws NullPointerException if {@code b} is {@code null}. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
187 |
* @throws EOFException if this stream reaches the end before reading |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
188 |
* all the bytes. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
189 |
* @throws IOException if an I/O error occurs. |
2 | 190 |
*/ |
191 |
void readFully(byte b[]) throws IOException; |
|
192 |
||
193 |
/** |
|
194 |
* |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
195 |
* Reads {@code len} |
2 | 196 |
* bytes from |
197 |
* an input stream. |
|
198 |
* <p> |
|
199 |
* This method |
|
200 |
* blocks until one of the following conditions |
|
21334 | 201 |
* occurs: |
2 | 202 |
* <ul> |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
203 |
* <li>{@code len} bytes |
2 | 204 |
* of input data are available, in which case |
205 |
* a normal return is made. |
|
206 |
* |
|
207 |
* <li>End of file |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
208 |
* is detected, in which case an {@code EOFException} |
2 | 209 |
* is thrown. |
210 |
* |
|
211 |
* <li>An I/O error occurs, in |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
212 |
* which case an {@code IOException} other |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
213 |
* than {@code EOFException} is thrown. |
2 | 214 |
* </ul> |
215 |
* <p> |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
216 |
* If {@code b} is {@code null}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
217 |
* a {@code NullPointerException} is thrown. |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
218 |
* If {@code off} is negative, or {@code len} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
219 |
* is negative, or {@code off+len} is |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
220 |
* greater than the length of the array {@code b}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
221 |
* then an {@code IndexOutOfBoundsException} |
2 | 222 |
* is thrown. |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
223 |
* If {@code len} is zero, |
2 | 224 |
* then no bytes are read. Otherwise, the first |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
225 |
* byte read is stored into element {@code b[off]}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
226 |
* the next one into {@code b[off+1]}, |
2 | 227 |
* and so on. The number of bytes read is, |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
228 |
* at most, equal to {@code len}. |
2 | 229 |
* |
37591
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
230 |
* @param b the buffer into which the data is read. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
231 |
* @param off an int specifying the offset in the data array {@code b}. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
232 |
* @param len an int specifying the number of bytes to read. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
233 |
* @throws NullPointerException if {@code b} is {@code null}. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
234 |
* @throws IndexOutOfBoundsException if {@code off} is negative, |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
235 |
* {@code len} is negative, or {@code len} is greater than |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
236 |
* {@code b.length - off}. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
237 |
* @throws EOFException if this stream reaches the end before reading |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
238 |
* all the bytes. |
b71bda3ce058
8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
bpb
parents:
25859
diff
changeset
|
239 |
* @throws IOException if an I/O error occurs. |
2 | 240 |
*/ |
241 |
void readFully(byte b[], int off, int len) throws IOException; |
|
242 |
||
243 |
/** |
|
244 |
* Makes an attempt to skip over |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
245 |
* {@code n} bytes |
2 | 246 |
* of data from the input |
247 |
* stream, discarding the skipped bytes. However, |
|
248 |
* it may skip |
|
249 |
* over some smaller number of |
|
250 |
* bytes, possibly zero. This may result from |
|
251 |
* any of a |
|
252 |
* number of conditions; reaching |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
253 |
* end of file before {@code n} bytes |
2 | 254 |
* have been skipped is |
255 |
* only one possibility. |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
256 |
* This method never throws an {@code EOFException}. |
2 | 257 |
* The actual |
258 |
* number of bytes skipped is returned. |
|
259 |
* |
|
260 |
* @param n the number of bytes to be skipped. |
|
261 |
* @return the number of bytes actually skipped. |
|
262 |
* @exception IOException if an I/O error occurs. |
|
263 |
*/ |
|
264 |
int skipBytes(int n) throws IOException; |
|
265 |
||
266 |
/** |
|
267 |
* Reads one input byte and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
268 |
* {@code true} if that byte is nonzero, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
269 |
* {@code false} if that byte is zero. |
2 | 270 |
* This method is suitable for reading |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
271 |
* the byte written by the {@code writeBoolean} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
272 |
* method of interface {@code DataOutput}. |
2 | 273 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
274 |
* @return the {@code boolean} value read. |
2 | 275 |
* @exception EOFException if this stream reaches the end before reading |
276 |
* all the bytes. |
|
277 |
* @exception IOException if an I/O error occurs. |
|
278 |
*/ |
|
279 |
boolean readBoolean() throws IOException; |
|
280 |
||
281 |
/** |
|
282 |
* Reads and returns one input byte. |
|
283 |
* The byte is treated as a signed value in |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
284 |
* the range {@code -128} through {@code 127}, |
2 | 285 |
* inclusive. |
286 |
* This method is suitable for |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
287 |
* reading the byte written by the {@code writeByte} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
288 |
* method of interface {@code DataOutput}. |
2 | 289 |
* |
290 |
* @return the 8-bit value read. |
|
291 |
* @exception EOFException if this stream reaches the end before reading |
|
292 |
* all the bytes. |
|
293 |
* @exception IOException if an I/O error occurs. |
|
294 |
*/ |
|
295 |
byte readByte() throws IOException; |
|
296 |
||
297 |
/** |
|
298 |
* Reads one input byte, zero-extends |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
299 |
* it to type {@code int}, and returns |
2 | 300 |
* the result, which is therefore in the range |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
301 |
* {@code 0} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
302 |
* through {@code 255}. |
2 | 303 |
* This method is suitable for reading |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
304 |
* the byte written by the {@code writeByte} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
305 |
* method of interface {@code DataOutput} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
306 |
* if the argument to {@code writeByte} |
2 | 307 |
* was intended to be a value in the range |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
308 |
* {@code 0} through {@code 255}. |
2 | 309 |
* |
310 |
* @return the unsigned 8-bit value read. |
|
311 |
* @exception EOFException if this stream reaches the end before reading |
|
312 |
* all the bytes. |
|
313 |
* @exception IOException if an I/O error occurs. |
|
314 |
*/ |
|
315 |
int readUnsignedByte() throws IOException; |
|
316 |
||
317 |
/** |
|
318 |
* Reads two input bytes and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
319 |
* a {@code short} value. Let {@code a} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
320 |
* be the first byte read and {@code b} |
2 | 321 |
* be the second byte. The value |
322 |
* returned |
|
323 |
* is: |
|
21334 | 324 |
* <pre>{@code (short)((a << 8) | (b & 0xff)) |
325 |
* }</pre> |
|
2 | 326 |
* This method |
327 |
* is suitable for reading the bytes written |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
328 |
* by the {@code writeShort} method of |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
329 |
* interface {@code DataOutput}. |
2 | 330 |
* |
331 |
* @return the 16-bit value read. |
|
332 |
* @exception EOFException if this stream reaches the end before reading |
|
333 |
* all the bytes. |
|
334 |
* @exception IOException if an I/O error occurs. |
|
335 |
*/ |
|
336 |
short readShort() throws IOException; |
|
337 |
||
338 |
/** |
|
339 |
* Reads two input bytes and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
340 |
* an {@code int} value in the range {@code 0} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
341 |
* through {@code 65535}. Let {@code a} |
2 | 342 |
* be the first byte read and |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
343 |
* {@code b} |
2 | 344 |
* be the second byte. The value returned is: |
21334 | 345 |
* <pre>{@code (((a & 0xff) << 8) | (b & 0xff)) |
346 |
* }</pre> |
|
2 | 347 |
* This method is suitable for reading the bytes |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
348 |
* written by the {@code writeShort} method |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
349 |
* of interface {@code DataOutput} if |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
350 |
* the argument to {@code writeShort} |
2 | 351 |
* was intended to be a value in the range |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
352 |
* {@code 0} through {@code 65535}. |
2 | 353 |
* |
354 |
* @return the unsigned 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 |
int readUnsignedShort() throws IOException; |
|
360 |
||
361 |
/** |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
362 |
* Reads two input bytes and returns a {@code char} value. |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
363 |
* Let {@code a} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
364 |
* be the first byte read and {@code b} |
2 | 365 |
* be the second byte. The value |
366 |
* returned is: |
|
21334 | 367 |
* <pre>{@code (char)((a << 8) | (b & 0xff)) |
368 |
* }</pre> |
|
2 | 369 |
* This method |
370 |
* is suitable for reading bytes written by |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
371 |
* the {@code writeChar} method of interface |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
372 |
* {@code DataOutput}. |
2 | 373 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
374 |
* @return the {@code char} value read. |
2 | 375 |
* @exception EOFException if this stream reaches the end before reading |
376 |
* all the bytes. |
|
377 |
* @exception IOException if an I/O error occurs. |
|
378 |
*/ |
|
379 |
char readChar() throws IOException; |
|
380 |
||
381 |
/** |
|
382 |
* Reads four input bytes and returns an |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
383 |
* {@code int} value. Let {@code a-d} |
2 | 384 |
* be the first through fourth bytes read. The value returned is: |
21334 | 385 |
* <pre>{@code |
386 |
* (((a & 0xff) << 24) | ((b & 0xff) << 16) | |
|
387 |
* ((c & 0xff) << 8) | (d & 0xff)) |
|
388 |
* }</pre> |
|
2 | 389 |
* This method is suitable |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
390 |
* for reading bytes written by the {@code writeInt} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
391 |
* method of interface {@code DataOutput}. |
2 | 392 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
393 |
* @return the {@code int} value read. |
2 | 394 |
* @exception EOFException if this stream reaches the end before reading |
395 |
* all the bytes. |
|
396 |
* @exception IOException if an I/O error occurs. |
|
397 |
*/ |
|
398 |
int readInt() throws IOException; |
|
399 |
||
400 |
/** |
|
401 |
* Reads eight input bytes and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
402 |
* a {@code long} value. Let {@code a-h} |
2 | 403 |
* be the first through eighth bytes read. |
404 |
* The value returned is: |
|
21334 | 405 |
* <pre>{@code |
406 |
* (((long)(a & 0xff) << 56) | |
|
407 |
* ((long)(b & 0xff) << 48) | |
|
408 |
* ((long)(c & 0xff) << 40) | |
|
409 |
* ((long)(d & 0xff) << 32) | |
|
410 |
* ((long)(e & 0xff) << 24) | |
|
411 |
* ((long)(f & 0xff) << 16) | |
|
412 |
* ((long)(g & 0xff) << 8) | |
|
413 |
* ((long)(h & 0xff))) |
|
414 |
* }</pre> |
|
2 | 415 |
* <p> |
416 |
* This method is suitable |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
417 |
* for reading bytes written by the {@code writeLong} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
418 |
* method of interface {@code DataOutput}. |
2 | 419 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
420 |
* @return the {@code long} value read. |
2 | 421 |
* @exception EOFException if this stream reaches the end before reading |
422 |
* all the bytes. |
|
423 |
* @exception IOException if an I/O error occurs. |
|
424 |
*/ |
|
425 |
long readLong() throws IOException; |
|
426 |
||
427 |
/** |
|
428 |
* Reads four input bytes and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
429 |
* a {@code float} value. It does this |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
430 |
* by first constructing an {@code int} |
2 | 431 |
* value in exactly the manner |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
432 |
* of the {@code readInt} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
433 |
* method, then converting this {@code int} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
434 |
* value to a {@code float} in |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
435 |
* exactly the manner of the method {@code Float.intBitsToFloat}. |
2 | 436 |
* This method is suitable for reading |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
437 |
* bytes written by the {@code writeFloat} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
438 |
* method of interface {@code DataOutput}. |
2 | 439 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
440 |
* @return the {@code float} value read. |
2 | 441 |
* @exception EOFException if this stream reaches the end before reading |
442 |
* all the bytes. |
|
443 |
* @exception IOException if an I/O error occurs. |
|
444 |
*/ |
|
445 |
float readFloat() throws IOException; |
|
446 |
||
447 |
/** |
|
448 |
* Reads eight input bytes and returns |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
449 |
* a {@code double} value. It does this |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
450 |
* by first constructing a {@code long} |
2 | 451 |
* value in exactly the manner |
21624
2648e47a6654
8024458: DataInput.readDouble refers to "readlong" instead of "readLong"
rriggs
parents:
21334
diff
changeset
|
452 |
* of the {@code readLong} |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
453 |
* method, then converting this {@code long} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
454 |
* value to a {@code double} in exactly |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
455 |
* the manner of the method {@code Double.longBitsToDouble}. |
2 | 456 |
* This method is suitable for reading |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
457 |
* bytes written by the {@code writeDouble} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
458 |
* method of interface {@code DataOutput}. |
2 | 459 |
* |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
460 |
* @return the {@code double} value read. |
2 | 461 |
* @exception EOFException if this stream reaches the end before reading |
462 |
* all the bytes. |
|
463 |
* @exception IOException if an I/O error occurs. |
|
464 |
*/ |
|
465 |
double readDouble() throws IOException; |
|
466 |
||
467 |
/** |
|
468 |
* Reads the next line of text from the input stream. |
|
469 |
* It reads successive bytes, converting |
|
470 |
* each byte separately into a character, |
|
471 |
* until it encounters a line terminator or |
|
472 |
* end of |
|
473 |
* file; the characters read are then |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
474 |
* returned as a {@code String}. Note |
2 | 475 |
* that because this |
476 |
* method processes bytes, |
|
477 |
* it does not support input of the full Unicode |
|
478 |
* character set. |
|
479 |
* <p> |
|
480 |
* If end of file is encountered |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
481 |
* before even one byte can be read, then {@code null} |
2 | 482 |
* is returned. Otherwise, each byte that is |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
483 |
* read is converted to type {@code char} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
484 |
* by zero-extension. If the character {@code '\n'} |
2 | 485 |
* is encountered, it is discarded and reading |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
486 |
* ceases. If the character {@code '\r'} |
2 | 487 |
* is encountered, it is discarded and, if |
488 |
* the following byte converts  to the |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
489 |
* character {@code '\n'}, then that is |
2 | 490 |
* discarded also; reading then ceases. If |
491 |
* end of file is encountered before either |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
492 |
* of the characters {@code '\n'} and |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
493 |
* {@code '\r'} is encountered, reading |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
494 |
* ceases. Once reading has ceased, a {@code String} |
2 | 495 |
* is returned that contains all the characters |
496 |
* read and not discarded, taken in order. |
|
497 |
* Note that every character in this string |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
498 |
* will have a value less than {@code \u005Cu0100}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
499 |
* that is, {@code (char)256}. |
2 | 500 |
* |
501 |
* @return the next line of text from the input stream, |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
502 |
* or {@code null} if the end of file is |
2 | 503 |
* encountered before a byte can be read. |
504 |
* @exception IOException if an I/O error occurs. |
|
505 |
*/ |
|
506 |
String readLine() throws IOException; |
|
507 |
||
508 |
/** |
|
509 |
* Reads in a string that has been encoded using a |
|
510 |
* <a href="#modified-utf-8">modified UTF-8</a> |
|
511 |
* format. |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
512 |
* The general contract of {@code readUTF} |
2 | 513 |
* is that it reads a representation of a Unicode |
514 |
* character string encoded in modified |
|
515 |
* UTF-8 format; this string of characters |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
516 |
* is then returned as a {@code String}. |
2 | 517 |
* <p> |
518 |
* First, two bytes are read and used to |
|
519 |
* construct an unsigned 16-bit integer in |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
520 |
* exactly the manner of the {@code readUnsignedShort} |
2 | 521 |
* method . This integer value is called the |
522 |
* <i>UTF length</i> and specifies the number |
|
523 |
* of additional bytes to be read. These bytes |
|
524 |
* are then converted to characters by considering |
|
525 |
* them in groups. The length of each group |
|
526 |
* is computed from the value of the first |
|
527 |
* byte of the group. The byte following a |
|
528 |
* group, if any, is the first byte of the |
|
529 |
* next group. |
|
530 |
* <p> |
|
531 |
* If the first byte of a group |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
532 |
* matches the bit pattern {@code 0xxxxxxx} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
533 |
* (where {@code x} means "may be {@code 0} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
534 |
* or {@code 1}"), then the group consists |
2 | 535 |
* of just that byte. The byte is zero-extended |
536 |
* to form a character. |
|
537 |
* <p> |
|
538 |
* If the first byte |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
539 |
* of a group matches the bit pattern {@code 110xxxxx}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
540 |
* then the group consists of that byte {@code a} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
541 |
* and a second byte {@code b}. If there |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
542 |
* is no byte {@code b} (because byte |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
543 |
* {@code a} was the last of the bytes |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
544 |
* to be read), or if byte {@code b} does |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
545 |
* not match the bit pattern {@code 10xxxxxx}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
546 |
* then a {@code UTFDataFormatException} |
2 | 547 |
* is thrown. Otherwise, the group is converted |
21334 | 548 |
* to the character: |
549 |
* <pre>{@code (char)(((a & 0x1F) << 6) | (b & 0x3F)) |
|
550 |
* }</pre> |
|
2 | 551 |
* If the first byte of a group |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
552 |
* matches the bit pattern {@code 1110xxxx}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
553 |
* then the group consists of that byte {@code a} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
554 |
* and two more bytes {@code b} and {@code c}. |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
555 |
* If there is no byte {@code c} (because |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
556 |
* byte {@code a} was one of the last |
2 | 557 |
* two of the bytes to be read), or either |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
558 |
* byte {@code b} or byte {@code c} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
559 |
* does not match the bit pattern {@code 10xxxxxx}, |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
560 |
* then a {@code UTFDataFormatException} |
2 | 561 |
* is thrown. Otherwise, the group is converted |
21334 | 562 |
* to the character: |
563 |
* <pre>{@code |
|
564 |
* (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F)) |
|
565 |
* }</pre> |
|
2 | 566 |
* If the first byte of a group matches the |
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
567 |
* pattern {@code 1111xxxx} or the pattern |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
568 |
* {@code 10xxxxxx}, then a {@code UTFDataFormatException} |
2 | 569 |
* is thrown. |
570 |
* <p> |
|
571 |
* If end of file is encountered |
|
572 |
* at any time during this entire process, |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
573 |
* then an {@code EOFException} is thrown. |
2 | 574 |
* <p> |
575 |
* After every group has been converted to |
|
576 |
* a character by this process, the characters |
|
577 |
* are gathered, in the same order in which |
|
578 |
* their corresponding groups were read from |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
579 |
* the input stream, to form a {@code String}, |
2 | 580 |
* which is returned. |
581 |
* <p> |
|
11676
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
582 |
* The {@code writeUTF} |
7e75ec031b97
7132338: Use @code friendly idiom for '\' in javadoc
darcy
parents:
5506
diff
changeset
|
583 |
* method of interface {@code DataOutput} |
2 | 584 |
* may be used to write data that is suitable |
585 |
* for reading by this method. |
|
586 |
* @return a Unicode string. |
|
587 |
* @exception EOFException if this stream reaches the end |
|
588 |
* before reading all the bytes. |
|
589 |
* @exception IOException if an I/O error occurs. |
|
590 |
* @exception UTFDataFormatException if the bytes do not represent a |
|
591 |
* valid modified UTF-8 encoding of a string. |
|
592 |
*/ |
|
593 |
String readUTF() throws IOException; |
|
594 |
} |