44 |
* Status: Believed complete and correct. */ |
* Status: Believed complete and correct. */ |
45 |
|
|
46 |
/** |
/** |
47 |
* This interface is implemented by classes that can data from streams |
* This interface is implemented by classes that can data from streams |
48 |
* into Java primitive types. |
* into Java primitive types. |
49 |
* |
* |
50 |
* @author Aaron M. Renn (arenn@urbanophile.com) |
* @author Aaron M. Renn (arenn@urbanophile.com) |
51 |
* @author Warren Levy <warrenl@cygnus.com> |
* @author Warren Levy <warrenl@cygnus.com> |
52 |
*/ |
*/ |
53 |
public interface DataInput |
public interface DataInput |
54 |
{ |
{ |
55 |
|
|
56 |
/** |
/** |
57 |
* This method reads a Java boolean value from an input stream. It does |
* This method reads a Java boolean value from an input stream. It does |
58 |
* so by reading a single byte of data. If that byte is zero, then the |
* so by reading a single byte of data. If that byte is zero, then the |
59 |
* value returned is <code>false</code>. If the byte is non-zero, then |
* value returned is <code>false</code>. If the byte is non-zero, then |
60 |
* the value returned is <code>true</code>. |
* the value returned is <code>true</code>. |
61 |
* <p> |
* <p> |
62 |
* This method can read a <code>boolean</code> written by an object |
* This method can read a <code>boolean</code> written by an object |
63 |
* implementing the <code>writeBoolean()</code> method in the |
* implementing the <code>writeBoolean()</code> method in the |
64 |
* <code>DataOutput</code> interface. |
* <code>DataOutput</code> interface. |
65 |
* |
* |
66 |
* @return The <code>boolean</code> value read |
* @return The <code>boolean</code> value read |
67 |
* |
* |
68 |
* @exception EOFException If end of file is reached before |
* @exception EOFException If end of file is reached before |
69 |
* reading the boolean |
* reading the boolean |
70 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
71 |
*/ |
*/ |
72 |
boolean readBoolean() throws EOFException, IOException; |
boolean readBoolean() throws EOFException, IOException; |
73 |
|
|
|
/*************************************************************************/ |
|
|
|
|
74 |
/** |
/** |
75 |
* This method reads a Java byte value from an input stream. The value |
* This method reads a Java byte value from an input stream. The value |
76 |
* is in the range of -128 to 127. |
* is in the range of -128 to 127. |
77 |
* <p> |
* <p> |
78 |
* This method can read a <code>byte</code> written by an object |
* This method can read a <code>byte</code> written by an object |
79 |
* implementing the |
* implementing the |
80 |
* <code>writeByte()</code> method in the <code>DataOutput</code> interface. |
* <code>writeByte()</code> method in the <code>DataOutput</code> interface. |
81 |
* <p> |
* <p> |
82 |
* @return The <code>byte</code> value read |
* @return The <code>byte</code> value read |
83 |
* |
* |
84 |
* @exception EOFException If end of file is reached before reading the byte |
* @exception EOFException If end of file is reached before reading the byte |
85 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
86 |
* |
* |
87 |
* @see DataOutput |
* @see DataOutput |
88 |
*/ |
*/ |
89 |
byte readByte() throws EOFException, IOException; |
byte readByte() throws EOFException, IOException; |
90 |
|
|
|
/*************************************************************************/ |
|
|
|
|
91 |
/** |
/** |
92 |
* This method reads 8 unsigned bits into a Java <code>int</code> value from |
* This method reads 8 unsigned bits into a Java <code>int</code> value from |
93 |
* the stream. The value returned is in the range of 0 to 255. |
* the stream. The value returned is in the range of 0 to 255. |
94 |
* <p> |
* <p> |
95 |
* This method can read an unsigned byte written by an object |
* This method can read an unsigned byte written by an object |
96 |
* implementing the |
* implementing the |
97 |
* <code>writeUnsignedByte()</code> method in the <code>DataOutput</code> |
* <code>writeUnsignedByte()</code> method in the <code>DataOutput</code> |
98 |
* interface. |
* interface. |
99 |
* |
* |
100 |
* @return The unsigned bytes value read as a Java <code>int</code>. |
* @return The unsigned bytes value read as a Java <code>int</code>. |
101 |
* |
* |
102 |
* @exception EOFException If end of file is reached before reading the value |
* @exception EOFException If end of file is reached before reading the value |
103 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
104 |
* |
* |
105 |
* @see DataOutput |
* @see DataOutput |
106 |
*/ |
*/ |
107 |
int readUnsignedByte() throws EOFException, IOException; |
int readUnsignedByte() throws EOFException, IOException; |
108 |
|
|
|
/*************************************************************************/ |
|
|
|
|
109 |
/** |
/** |
110 |
* This method reads a Java <code>char</code> value from an input stream. |
* This method reads a Java <code>char</code> value from an input stream. |
111 |
* It operates by reading two bytes from the stream and converting them to |
* It operates by reading two bytes from the stream and converting them to |
112 |
* a single 16-bit Java <code>char</code>. The two bytes are stored most |
* a single 16-bit Java <code>char</code>. The two bytes are stored most |
113 |
* significant byte first (i.e., "big endian") regardless of the native |
* significant byte first (i.e., "big endian") regardless of the native |
114 |
* host byte ordering. |
* host byte ordering. |
115 |
* <p> |
* <p> |
116 |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
117 |
* first and second byte read from the stream respectively, they will be |
* first and second byte read from the stream respectively, they will be |
118 |
* transformed to a <code>char</code> in the following manner: |
* transformed to a <code>char</code> in the following manner: |
119 |
* <p> |
* <p> |
120 |
* <code>(char)((byte1 << 8) + byte2)</code> |
* <code>(char)((byte1 << 8) + byte2)</code> |
121 |
* <p> |
* <p> |
122 |
* This method can read a <code>char</code> written by an object implementing |
* This method can read a <code>char</code> written by an object implementing |
123 |
* the |
* the |
124 |
* <code>writeChar()</code> method in the <code>DataOutput</code> interface. |
* <code>writeChar()</code> method in the <code>DataOutput</code> interface. |
125 |
* |
* |
126 |
* @return The <code>char</code> value read |
* @return The <code>char</code> value read |
127 |
* |
* |
128 |
* @exception EOFException If end of file is reached before reading the char |
* @exception EOFException If end of file is reached before reading the char |
129 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
130 |
* |
* |
131 |
* @see DataOutput |
* @see DataOutput |
132 |
*/ |
*/ |
133 |
char readChar() throws EOFException, IOException; |
char readChar() throws EOFException, IOException; |
134 |
|
|
|
/*************************************************************************/ |
|
|
|
|
135 |
/** |
/** |
136 |
* This method reads a signed 16-bit value into a Java in from the stream. |
* This method reads a signed 16-bit value into a Java in from the stream. |
137 |
* It operates by reading two bytes from the stream and converting them to |
* It operates by reading two bytes from the stream and converting them to |
138 |
* a single 16-bit Java <code>short</code>. The two bytes are stored most |
* a single 16-bit Java <code>short</code>. The two bytes are stored most |
139 |
* significant byte first (i.e., "big endian") regardless of the native |
* significant byte first (i.e., "big endian") regardless of the native |
140 |
* host byte ordering. |
* host byte ordering. |
141 |
* <p> |
* <p> |
142 |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
143 |
* first and second byte read from the stream respectively, they will be |
* first and second byte read from the stream respectively, they will be |
144 |
* transformed to a <code>short</code> in the following manner: |
* transformed to a <code>short</code> in the following manner: |
145 |
* <p> |
* <p> |
146 |
* <code>(short)((byte1 << 8) + byte2)</code> |
* <code>(short)((byte1 << 8) + byte2)</code> |
147 |
* <p> |
* <p> |
148 |
* The value returned is in the range of -32768 to 32767. |
* The value returned is in the range of -32768 to 32767. |
149 |
* <p> |
* <p> |
150 |
* This method can read a <code>short</code> written by an object |
* This method can read a <code>short</code> written by an object |
151 |
* implementing |
* implementing |
152 |
* the <code>writeShort()</code> method in the <code>DataOutput</code> |
* the <code>writeShort()</code> method in the <code>DataOutput</code> |
153 |
* interface. |
* interface. |
154 |
* |
* |
155 |
* @return The <code>short</code> value read |
* @return The <code>short</code> value read |
156 |
* |
* |
157 |
* @exception EOFException If end of file is reached before reading the value |
* @exception EOFException If end of file is reached before reading the value |
158 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
159 |
* |
* |
160 |
* @see DataOutput |
* @see DataOutput |
161 |
*/ |
*/ |
162 |
short readShort() throws EOFException, IOException; |
short readShort() throws EOFException, IOException; |
163 |
|
|
|
/*************************************************************************/ |
|
|
|
|
164 |
/** |
/** |
165 |
* This method reads 16 unsigned bits into a Java int value from the stream. |
* This method reads 16 unsigned bits into a Java int value from the stream. |
166 |
* It operates by reading two bytes from the stream and converting them to |
* It operates by reading two bytes from the stream and converting them to |
167 |
* a single Java <code>int</code>. The two bytes are stored most |
* a single Java <code>int</code>. The two bytes are stored most |
168 |
* significant byte first (i.e., "big endian") regardless of the native |
* significant byte first (i.e., "big endian") regardless of the native |
169 |
* host byte ordering. |
* host byte ordering. |
170 |
* <p> |
* <p> |
171 |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
* As an example, if <code>byte1</code> and <code>byte2</code> represent the |
172 |
* first and second byte read from the stream respectively, they will be |
* first and second byte read from the stream respectively, they will be |
173 |
* transformed to an <code>int</code> in the following manner: |
* transformed to an <code>int</code> in the following manner: |
174 |
* <p> |
* <p> |
175 |
* <code>(int)((byte1 << 8) + byte2)</code> |
* <code>(int)((byte1 << 8) + byte2)</code> |
176 |
* <p> |
* <p> |
177 |
* The value returned is in the range of 0 to 65535. |
* The value returned is in the range of 0 to 65535. |
178 |
* <p> |
* <p> |
179 |
* This method can read an unsigned short written by an object implementing |
* This method can read an unsigned short written by an object implementing |
180 |
* the <code>writeUnsignedShort()</code> method in the |
* the <code>writeUnsignedShort()</code> method in the |
181 |
* <code>DataOutput</code> |
* <code>DataOutput</code> |
182 |
* interface. |
* interface. |
183 |
* |
* |
184 |
* @return The unsigned short value read as a Java <code>int</code>. |
* @return The unsigned short value read as a Java <code>int</code>. |
185 |
* |
* |
186 |
* @exception EOFException If end of file is reached before reading |
* @exception EOFException If end of file is reached before reading |
187 |
* the value |
* the value |
188 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
189 |
*/ |
*/ |
190 |
int readUnsignedShort() throws EOFException, IOException; |
int readUnsignedShort() throws EOFException, IOException; |
191 |
|
|
|
/*************************************************************************/ |
|
|
|
|
192 |
/** |
/** |
193 |
* This method reads a Java <code>int</code> value from an input stream |
* This method reads a Java <code>int</code> value from an input stream |
194 |
* It operates by reading four bytes from the stream and converting them to |
* It operates by reading four bytes from the stream and converting them to |
195 |
* a single Java <code>int</code>. The bytes are stored most |
* a single Java <code>int</code>. The bytes are stored most |
196 |
* significant byte first (i.e., "big endian") regardless of the native |
* significant byte first (i.e., "big endian") regardless of the native |
197 |
* host byte ordering. |
* host byte ordering. |
198 |
* <p> |
* <p> |
199 |
* As an example, if <code>byte1</code> through <code>byte4</code> represent |
* As an example, if <code>byte1</code> through <code>byte4</code> represent |
200 |
* the first four bytes read from the stream, they will be |
* the first four bytes read from the stream, they will be |
201 |
* transformed to an <code>int</code> in the following manner: |
* transformed to an <code>int</code> in the following manner: |
202 |
* <p> |
* <p> |
203 |
* <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code> |
* <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code> |
204 |
* <p> |
* <p> |
205 |
* The value returned is in the range of -2147483648 to 2147483647. |
* The value returned is in the range of -2147483648 to 2147483647. |
206 |
* <p> |
* <p> |
207 |
* This method can read an <code>int</code> written by an object |
* This method can read an <code>int</code> written by an object |
208 |
* implementing the <code>writeInt()</code> method in the |
* implementing the <code>writeInt()</code> method in the |
209 |
* <code>DataOutput</code> interface. |
* <code>DataOutput</code> interface. |
210 |
* |
* |
211 |
* @return The <code>int</code> value read |
* @return The <code>int</code> value read |
212 |
* |
* |
213 |
* @exception EOFException If end of file is reached before reading the int |
* @exception EOFException If end of file is reached before reading the int |
214 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
215 |
* |
* |
216 |
* @see DataOutput |
* @see DataOutput |
217 |
*/ |
*/ |
218 |
int readInt() throws EOFException, IOException; |
int readInt() throws EOFException, IOException; |
219 |
|
|
|
/*************************************************************************/ |
|
|
|
|
220 |
/** |
/** |
221 |
* This method reads a Java <code>long</code> value from an input stream |
* This method reads a Java <code>long</code> value from an input stream |
222 |
* It operates by reading eight bytes from the stream and converting them to |
* It operates by reading eight bytes from the stream and converting them to |
223 |
* a single Java <code>long</code>. The bytes are stored most |
* a single Java <code>long</code>. The bytes are stored most |
224 |
* significant byte first (i.e., "big endian") regardless of the native |
* significant byte first (i.e., "big endian") regardless of the native |
225 |
* host byte ordering. |
* host byte ordering. |
226 |
* <p> |
* <p> |
227 |
* As an example, if <code>byte1</code> through <code>byte8</code> represent |
* As an example, if <code>byte1</code> through <code>byte8</code> represent |
228 |
* the first eight bytes read from the stream, they will be |
* the first eight bytes read from the stream, they will be |
229 |
* transformed to an <code>long</code> in the following manner: |
* transformed to an <code>long</code> in the following manner: |
230 |
* <p> |
* <p> |
231 |
* <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) + |
* <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) + |
232 |
* (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9)) |
* (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9)) |
233 |
* </code> |
* </code> |
234 |
* <p> |
* <p> |
235 |
* The value returned is in the range of -9223372036854775808 to |
* The value returned is in the range of -9223372036854775808 to |
236 |
* 9223372036854775807. |
* 9223372036854775807. |
237 |
* <p> |
* <p> |
238 |
* This method can read an <code>long</code> written by an object |
* This method can read an <code>long</code> written by an object |
239 |
* implementing the <code>writeLong()</code> method in the |
* implementing the <code>writeLong()</code> method in the |
240 |
* <code>DataOutput</code> interface. |
* <code>DataOutput</code> interface. |
241 |
* |
* |
242 |
* @return The <code>long</code> value read |
* @return The <code>long</code> value read |
243 |
* |
* |
244 |
* @exception EOFException If end of file is reached before reading the long |
* @exception EOFException If end of file is reached before reading the long |
245 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
246 |
* |
* |
247 |
* @see DataOutput |
* @see DataOutput |
248 |
*/ |
*/ |
249 |
long readLong() throws EOFException, IOException; |
long readLong() throws EOFException, IOException; |
250 |
|
|
|
/*************************************************************************/ |
|
|
|
|
251 |
/** |
/** |
252 |
* This method reads a Java float value from an input stream. It operates |
* This method reads a Java float value from an input stream. It operates |
253 |
* by first reading an <code>int</code> value from the stream by calling the |
* by first reading an <code>int</code> value from the stream by calling the |
254 |
* <code>readInt()</code> method in this interface, then converts that |
* <code>readInt()</code> method in this interface, then converts that |
255 |
* <code>int</code> to a <code>float</code> using the |
* <code>int</code> to a <code>float</code> using the |
256 |
* <code>intBitsToFloat</code> method in the class |
* <code>intBitsToFloat</code> method in the class |
257 |
* <code>java.lang.Float</code>. |
* <code>java.lang.Float</code>. |
258 |
* <p> |
* <p> |
259 |
* This method can read a <code>float</code> written by an object |
* This method can read a <code>float</code> written by an object |
260 |
* implementing |
* implementing |
261 |
* the <code>writeFloat()</code> method in the <code>DataOutput</code> |
* the <code>writeFloat()</code> method in the <code>DataOutput</code> |
262 |
* interface. |
* interface. |
263 |
* |
* |
264 |
* @return The <code>float</code> value read |
* @return The <code>float</code> value read |
265 |
* |
* |
266 |
* @exception EOFException If end of file is reached before reading the |
* @exception EOFException If end of file is reached before reading the |
267 |
* float |
* float |
268 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
269 |
* |
* |
270 |
* @see java.lang.Float |
* @see java.lang.Float |
271 |
* @see DataOutput |
* @see DataOutput |
272 |
*/ |
*/ |
273 |
float readFloat() throws EOFException, IOException; |
float readFloat() throws EOFException, IOException; |
274 |
|
|
|
/*************************************************************************/ |
|
|
|
|
275 |
/** |
/** |
276 |
* This method reads a Java double value from an input stream. It operates |
* This method reads a Java double value from an input stream. It operates |
277 |
* by first reading a <code>long</code> value from the stream by calling the |
* by first reading a <code>long</code> value from the stream by calling the |
278 |
* <code>readLong()</code> method in this interface, then converts that |
* <code>readLong()</code> method in this interface, then converts that |
279 |
* <code>long</code> to a <code>double</code> using the |
* <code>long</code> to a <code>double</code> using the |
280 |
* <code>longBitsToDouble</code> method in the class |
* <code>longBitsToDouble</code> method in the class |
281 |
* <code>java.lang.Double</code>. |
* <code>java.lang.Double</code>. |
282 |
* <p> |
* <p> |
283 |
* This method can read a <code>double</code> written by an object |
* This method can read a <code>double</code> written by an object |
284 |
* implementing the <code>writeDouble()</code> method in the |
* implementing the <code>writeDouble()</code> method in the |
285 |
* <code>DataOutput</code> interface. |
* <code>DataOutput</code> interface. |
286 |
* |
* |
287 |
* @return The <code>double</code> value read |
* @return The <code>double</code> value read |
288 |
* |
* |
289 |
* @exception EOFException If end of file is reached before reading the |
* @exception EOFException If end of file is reached before reading the |
290 |
* double |
* double |
291 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
292 |
* |
* |
293 |
* @see java.lang.Double |
* @see java.lang.Double |
294 |
* @see DataOutput |
* @see DataOutput |
295 |
*/ |
*/ |
296 |
double readDouble() throws EOFException, IOException; |
double readDouble() throws EOFException, IOException; |
297 |
|
|
|
/*************************************************************************/ |
|
|
|
|
298 |
/** |
/** |
299 |
* This method reads the next line of text data from an input stream. |
* This method reads the next line of text data from an input stream. |
300 |
* It operates by reading bytes and converting those bytes to |
* It operates by reading bytes and converting those bytes to |
301 |
* <code>char</code> |
* <code>char</code> |
302 |
* values by treating the byte read as the low eight bits of the |
* values by treating the byte read as the low eight bits of the |
303 |
* <code>char</code> and using 0 as the high eight bits. Because of this, |
* <code>char</code> and using 0 as the high eight bits. Because of this, |
304 |
* it does not support the full 16-bit Unicode character set. |
* it does not support the full 16-bit Unicode character set. |
305 |
* <P> |
* <P> |
306 |
* The reading of bytes ends when either the end of file or a line terminator |
* The reading of bytes ends when either the end of file or a line terminator |
307 |
* is encountered. The bytes read are then returned as a |
* is encountered. The bytes read are then returned as a |
308 |
* <code>String</code>. |
* <code>String</code>. |
309 |
* A line terminator is a byte sequence consisting of either |
* A line terminator is a byte sequence consisting of either |
310 |
* <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination |
* <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination |
311 |
* charaters are discarded and are not returned as part of the string. |
* charaters are discarded and are not returned as part of the string. |
312 |
* <p> |
* <p> |
313 |
* This method can read data that was written by an object implementing the |
* This method can read data that was written by an object implementing the |
314 |
* <code>writeLine()</code> method in <code>DataOutput</code>. |
* <code>writeLine()</code> method in <code>DataOutput</code>. |
315 |
* |
* |
316 |
* @return The line read as a <code>String</code> |
* @return The line read as a <code>String</code> |
317 |
* |
* |
318 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
319 |
* |
* |
320 |
* @see DataOutput |
* @see DataOutput |
321 |
*/ |
*/ |
322 |
String readLine() throws IOException; |
String readLine() throws IOException; |
323 |
|
|
|
/*************************************************************************/ |
|
|
|
|
324 |
/** |
/** |
325 |
* This method reads a <code>String</code> from an input stream that is |
* This method reads a <code>String</code> from an input stream that is |
326 |
* encoded in a modified UTF-8 format. This format has a leading two byte |
* encoded in a modified UTF-8 format. This format has a leading two byte |
327 |
* sequence that contains the remaining number of bytes to read. |
* sequence that contains the remaining number of bytes to read. |
328 |
* This two byte |
* This two byte |
329 |
* sequence is read using the <code>readUnsignedShort()</code> method of this |
* sequence is read using the <code>readUnsignedShort()</code> method of this |
330 |
* interface. |
* interface. |
331 |
* |
* |
332 |
* After the number of remaining bytes have been determined, these bytes |
* After the number of remaining bytes have been determined, these bytes |
333 |
* are read an transformed into <code>char</code> values. These |
* are read an transformed into <code>char</code> values. These |
334 |
* <code>char</code> values are encoded in the stream using either a one, |
* <code>char</code> values are encoded in the stream using either a one, |
335 |
* two, or three byte format. |
* two, or three byte format. |
336 |
* The particular format in use can be determined by examining the first |
* The particular format in use can be determined by examining the first |
337 |
* byte read. |
* byte read. |
338 |
* <p> |
* <p> |
339 |
* If the first byte has a high order bit of 0, then |
* If the first byte has a high order bit of 0, then |
340 |
* that character consists on only one byte. This character value consists |
* that character consists on only one byte. This character value consists |
341 |
* of seven bits that are at positions 0 through 6 of the byte. As an |
* of seven bits that are at positions 0 through 6 of the byte. As an |
342 |
* example, if <code>byte1</code> is the byte read from the stream, it would |
* example, if <code>byte1</code> is the byte read from the stream, it would |
343 |
* be converted to a <code>char</code> like so: |
* be converted to a <code>char</code> like so: |
344 |
* <p> |
* <p> |
345 |
* <code>(char)byte1</code> |
* <code>(char)byte1</code> |
346 |
* <p> |
* <p> |
347 |
* If the first byte has 110 as its high order bits, then the |
* If the first byte has 110 as its high order bits, then the |
348 |
* character consists of two bytes. The bits that make up the character |
* character consists of two bytes. The bits that make up the character |
349 |
* value are in positions 0 through 4 of the first byte and bit positions |
* value are in positions 0 through 4 of the first byte and bit positions |
350 |
* 0 through 5 of the second byte. (The second byte should have |
* 0 through 5 of the second byte. (The second byte should have |
351 |
* 10 as its high order bits). These values are in most significant |
* 10 as its high order bits). These values are in most significant |
352 |
* byte first (i.e., "big endian") order. |
* byte first (i.e., "big endian") order. |
353 |
* <p> |
* <p> |
354 |
* As an example, if <code>byte1</code> and <code>byte2</code> are the first |
* As an example, if <code>byte1</code> and <code>byte2</code> are the first |
355 |
* two bytes read respectively, and the high order bits of them match the |
* two bytes read respectively, and the high order bits of them match the |
356 |
* patterns which indicate a two byte character encoding, then they would be |
* patterns which indicate a two byte character encoding, then they would be |
357 |
* converted to a Java <code>char</code> like so: |
* converted to a Java <code>char</code> like so: |
358 |
* <p> |
* <p> |
359 |
* <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code> |
* <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code> |
360 |
* <p> |
* <p> |
361 |
* If the first byte has a 1110 as its high order bits, then the |
* If the first byte has a 1110 as its high order bits, then the |
362 |
* character consists of three bytes. The bits that make up the character |
* character consists of three bytes. The bits that make up the character |
363 |
* value are in positions 0 through 3 of the first byte and bit positions |
* value are in positions 0 through 3 of the first byte and bit positions |
364 |
* 0 through 5 of the other two bytes. (The second and third bytes should |
* 0 through 5 of the other two bytes. (The second and third bytes should |
365 |
* have 10 as their high order bits). These values are in most |
* have 10 as their high order bits). These values are in most |
366 |
* significant byte first (i.e., "big endian") order. |
* significant byte first (i.e., "big endian") order. |
367 |
* <p> |
* <p> |
368 |
* As an example, if <code>byte1</code>, <code>byte2</code>, and |
* As an example, if <code>byte1</code>, <code>byte2</code>, and |
369 |
* <code>byte3</code> are the three bytes read, and the high order bits of |
* <code>byte3</code> are the three bytes read, and the high order bits of |
370 |
* them match the patterns which indicate a three byte character encoding, |
* them match the patterns which indicate a three byte character encoding, |
371 |
* then they would be converted to a Java <code>char</code> like so: |
* then they would be converted to a Java <code>char</code> like so: |
372 |
* |
* |
373 |
* <code> |
* <code> |
374 |
* (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F)) |
* (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F)) |
375 |
* </code> |
* </code> |
376 |
* |
* |
377 |
* Note that all characters are encoded in the method that requires the |
* Note that all characters are encoded in the method that requires the |
378 |
* fewest number of bytes with the exception of the character with the |
* fewest number of bytes with the exception of the character with the |
379 |
* value of <code>\<llll>u0000</code> which is encoded as two bytes. |
* value of <code>\<llll>u0000</code> which is encoded as two bytes. |
380 |
* This is a modification of the UTF standard used to prevent C language |
* This is a modification of the UTF standard used to prevent C language |
381 |
* style <code>NUL</code> values from appearing in the byte stream. |
* style <code>NUL</code> values from appearing in the byte stream. |
382 |
* <p> |
* <p> |
383 |
* This method can read data that was written by an object implementing the |
* This method can read data that was written by an object implementing the |
384 |
* <code>writeUTF()</code> method in <code>DataOutput</code>. |
* <code>writeUTF()</code> method in <code>DataOutput</code>. |
385 |
* |
* |
386 |
* @returns The <code>String</code> read |
* @returns The <code>String</code> read |
387 |
* |
* |
388 |
* @exception EOFException If end of file is reached before reading the |
* @exception EOFException If end of file is reached before reading the |
389 |
* String |
* String |
390 |
* @exception UTFDataFormatException If the data is not in UTF-8 format |
* @exception UTFDataFormatException If the data is not in UTF-8 format |
391 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
392 |
* |
* |
393 |
* @see DataOutput |
* @see DataOutput |
394 |
*/ |
*/ |
395 |
String readUTF() throws EOFException, UTFDataFormatException, IOException; |
String readUTF() throws EOFException, UTFDataFormatException, IOException; |
396 |
|
|
|
/*************************************************************************/ |
|
|
|
|
397 |
/** |
/** |
398 |
* This method reads raw bytes into the passed array until the array is |
* This method reads raw bytes into the passed array until the array is |
399 |
* full. Note that this method blocks until the data is available and |
* full. Note that this method blocks until the data is available and |
400 |
* throws an exception if there is not enough data left in the stream to |
* throws an exception if there is not enough data left in the stream to |
401 |
* fill the buffer |
* fill the buffer |
402 |
* |
* |
403 |
* @param buf The buffer into which to read the data |
* @param buf The buffer into which to read the data |
404 |
* |
* |
405 |
* @exception EOFException If end of file is reached before filling the |
* @exception EOFException If end of file is reached before filling the |
406 |
* buffer |
* buffer |
407 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
408 |
*/ |
*/ |
409 |
void readFully(byte[] buf) throws EOFException, IOException; |
void readFully(byte[] buf) throws EOFException, IOException; |
410 |
|
|
|
/*************************************************************************/ |
|
|
|
|
411 |
/** |
/** |
412 |
* This method reads raw bytes into the passed array <code>buf</code> |
* This method reads raw bytes into the passed array <code>buf</code> |
413 |
* starting |
* starting |
414 |
* <code>offset</code> bytes into the buffer. The number of bytes read |
* <code>offset</code> bytes into the buffer. The number of bytes read |
415 |
* will be |
* will be |
416 |
* exactly <code>len</code>. Note that this method blocks until the data is |
* exactly <code>len</code>. Note that this method blocks until the data is |
417 |
* available and * throws an exception if there is not enough data left in |
* available and * throws an exception if there is not enough data left in |
418 |
* the stream to read <code>len</code> bytes. |
* the stream to read <code>len</code> bytes. |
419 |
* |
* |
420 |
* @param buf The buffer into which to read the data |
* @param buf The buffer into which to read the data |
421 |
* @param offset The offset into the buffer to start storing data |
* @param offset The offset into the buffer to start storing data |
422 |
* @param len The number of bytes to read into the buffer |
* @param len The number of bytes to read into the buffer |
423 |
* |
* |
424 |
* @exception EOFException If end of file is reached before filling the |
* @exception EOFException If end of file is reached before filling the |
425 |
* buffer |
* buffer |
426 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
427 |
*/ |
*/ |
428 |
void readFully(byte[] buf, int offset, int len) |
void readFully(byte[] buf, int offset, int len) |
429 |
throws EOFException, IOException; |
throws EOFException, IOException; |
430 |
|
|
|
/*************************************************************************/ |
|
|
|
|
431 |
/** |
/** |
432 |
* This method skips and discards the specified number of bytes in an |
* This method skips and discards the specified number of bytes in an |
433 |
* input stream |
* input stream |
434 |
* |
* |
435 |
* @param num_bytes The number of bytes to skip |
* @param num_bytes The number of bytes to skip |
436 |
* |
* |
437 |
* @return The number of bytes actually skipped, which will always be |
* @return The number of bytes actually skipped, which will always be |
438 |
* <code>num_bytes</code> |
* <code>num_bytes</code> |
439 |
* |
* |
440 |
* @exception EOFException If end of file is reached before all bytes can be |
* @exception EOFException If end of file is reached before all bytes can be |
441 |
* skipped |
* skipped |
442 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
443 |
*/ |
*/ |
444 |
int skipBytes(int n) throws EOFException, IOException; |
int skipBytes(int n) throws EOFException, IOException; |
445 |
|
|
446 |
} // interface DataInput |
} // interface DataInput |