1 /* DataInput.java -- Interface for reading data from a stream
2 Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
41 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
42 * "The Java Language Specification", ISBN 0-201-63451-1
43 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
44 * Status: Believed complete and correct.
48 * This interface is implemented by classes that can data from streams
49 * into Java primitive types.
51 * @author Aaron M. Renn (arenn@urbanophile.com)
52 * @author Warren Levy <warrenl@cygnus.com>
54 public interface DataInput
58 * This method reads a Java boolean value from an input stream. It does
59 * so by reading a single byte of data. If that byte is zero, then the
60 * value returned is <code>false</code>. If the byte is non-zero, then
61 * the value returned is <code>true</code>.
63 * This method can read a <code>boolean</code> written by an object
64 * implementing the <code>writeBoolean()</code> method in the
65 * <code>DataOutput</code> interface.
67 * @return The <code>boolean</code> value read
69 * @exception EOFException If end of file is reached before reading the boolean
70 * @exception IOException If any other error occurs
73 readBoolean() throws EOFException, IOException;
75 /*************************************************************************/
78 * This method reads a Java byte value from an input stream. The value
79 * is in the range of -128 to 127.
81 * This method can read a <code>byte</code> written by an object
83 * <code>writeByte()</code> method in the <code>DataOutput</code> interface.
85 * @return The <code>byte</code> value read
87 * @exception EOFException If end of file is reached before reading the byte
88 * @exception IOException If any other error occurs
93 readByte() throws EOFException, IOException;
95 /*************************************************************************/
98 * This method reads 8 unsigned bits into a Java <code>int</code> value from
99 * the stream. The value returned is in the range of 0 to 255.
101 * This method can read an unsigned byte written by an object implementing the
102 * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code>
105 * @return The unsigned bytes value read as a Java <code>int</code>.
107 * @exception EOFException If end of file is reached before reading the value
108 * @exception IOException If any other error occurs
113 readUnsignedByte() throws EOFException, IOException;
115 /*************************************************************************/
118 * This method reads a Java <code>char</code> value from an input stream.
119 * It operates by reading two bytes from the stream and converting them to
120 * a single 16-bit Java <code>char</code>. The two bytes are stored most
121 * significant byte first (i.e., "big endian") regardless of the native
122 * host byte ordering.
124 * As an example, if <code>byte1</code> and <code>byte2</code> represent the
125 * first and second byte read from the stream respectively, they will be
126 * transformed to a <code>char</code> in the following manner:
128 * <code>(char)((byte1 << 8) + byte2)</code>
130 * This method can read a <code>char</code> written by an object implementing
132 * <code>writeChar()</code> method in the <code>DataOutput</code> interface.
134 * @return The <code>char</code> value read
136 * @exception EOFException If end of file is reached before reading the char
137 * @exception IOException If any other error occurs
142 readChar() throws EOFException, IOException;
144 /*************************************************************************/
147 * This method reads a signed 16-bit value into a Java in from the stream.
148 * It operates by reading two bytes from the stream and converting them to
149 * a single 16-bit Java <code>short</code>. The two bytes are stored most
150 * significant byte first (i.e., "big endian") regardless of the native
151 * host byte ordering.
153 * As an example, if <code>byte1</code> and <code>byte2</code> represent the
154 * first and second byte read from the stream respectively, they will be
155 * transformed to a <code>short</code> in the following manner:
157 * <code>(short)((byte1 << 8) + byte2)</code>
159 * The value returned is in the range of -32768 to 32767.
161 * This method can read a <code>short</code> written by an object implementing
162 * the <code>writeShort()</code> method in the <code>DataOutput</code>
165 * @return The <code>short</code> value read
167 * @exception EOFException If end of file is reached before reading the value
168 * @exception IOException If any other error occurs
173 readShort() throws EOFException, IOException;
175 /*************************************************************************/
178 * This method reads 16 unsigned bits into a Java int value from the stream.
179 * It operates by reading two bytes from the stream and converting them to
180 * a single Java <code>int</code>. The two bytes are stored most
181 * significant byte first (i.e., "big endian") regardless of the native
182 * host byte ordering.
184 * As an example, if <code>byte1</code> and <code>byte2</code> represent the
185 * first and second byte read from the stream respectively, they will be
186 * transformed to an <code>int</code> in the following manner:
188 * <code>(int)((byte1 << 8) + byte2)</code>
190 * The value returned is in the range of 0 to 65535.
192 * This method can read an unsigned short written by an object implementing
193 * the <code>writeUnsignedShort()</code> method in the <code>DataOutput</code>
196 * @return The unsigned short value read as a Java <code>int</code>.
198 * @exception EOFException If end of file is reached before reading the value
199 * @exception IOException If any other error occurs
202 readUnsignedShort() throws EOFException, IOException;
204 /*************************************************************************/
207 * This method reads a Java <code>int</code> value from an input stream
208 * It operates by reading four bytes from the stream and converting them to
209 * a single Java <code>int</code>. The bytes are stored most
210 * significant byte first (i.e., "big endian") regardless of the native
211 * host byte ordering.
213 * As an example, if <code>byte1</code> through <code>byte4</code> represent
214 * the first four bytes read from the stream, they will be
215 * transformed to an <code>int</code> in the following manner:
217 * <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code>
219 The value returned is in the range of -2147483648 to 2147483647.
221 * This method can read an <code>int</code> written by an object implementing
222 * the <code>writeInt()</code> method in the <code>DataOutput</code> interface.
224 * @return The <code>int</code> value read
226 * @exception EOFException If end of file is reached before reading the int
227 * @exception IOException If any other error occurs
232 readInt() throws EOFException, IOException;
234 /*************************************************************************/
237 * This method reads a Java <code>long</code> value from an input stream
238 * It operates by reading eight bytes from the stream and converting them to
239 * a single Java <code>long</code>. The bytes are stored most
240 * significant byte first (i.e., "big endian") regardless of the native
241 * host byte ordering.
243 * As an example, if <code>byte1</code> through <code>byte8</code> represent
244 * the first eight bytes read from the stream, they will be
245 * transformed to an <code>long</code> in the following manner:
247 * <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) +
248 * (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9))
251 * The value returned is in the range of -9223372036854775808 to
252 * 9223372036854775807.
254 * This method can read an <code>long</code> written by an object implementing
255 * the <code>writeLong()</code> method in the <code>DataOutput</code>
258 * @return The <code>long</code> value read
260 * @exception EOFException If end of file is reached before reading the long
261 * @exception IOException If any other error occurs
266 readLong() throws EOFException, IOException;
268 /*************************************************************************/
271 * This method reads a Java float value from an input stream. It operates
272 * by first reading an <code>int</code> value from the stream by calling the
273 * <code>readInt()</code> method in this interface, then converts that
274 * <code>int</code> to a <code>float</code> using the
275 * <code>intBitsToFloat</code> method in the class
276 * <code>java.lang.Float</code>.
278 * This method can read a <code>float</code> written by an object implementing
279 * the <code>writeFloat()</code> method in the <code>DataOutput</code>
282 * @return The <code>float</code> value read
284 * @exception EOFException If end of file is reached before reading the float
285 * @exception IOException If any other error occurs
287 * @see java.lang.Float
291 readFloat() throws EOFException, IOException;
293 /*************************************************************************/
296 * This method reads a Java double value from an input stream. It operates
297 * by first reading a <code>long</code> value from the stream by calling the
298 * <code>readLong()</code> method in this interface, then converts that
299 * <code>long</code> to a <code>double</code> using the
300 * <code>longBitsToDouble</code> method in the class
301 * <code>java.lang.Double</code>.
303 * This method can read a <code>double</code> written by an object
304 * implementing the <code>writeDouble()</code> method in the
305 * <code>DataOutput</code> interface.
307 * @return The <code>double</code> value read
309 * @exception EOFException If end of file is reached before reading the double
310 * @exception IOException If any other error occurs
312 * @see java.lang.Double
316 readDouble() throws EOFException, IOException;
318 /*************************************************************************/
321 * This method reads the next line of text data from an input stream.
322 * It operates by reading bytes and converting those bytes to <code>char</code>
323 * values by treating the byte read as the low eight bits of the
324 * <code>char</code> and using 0 as the high eight bits. Because of this,
325 * it does not support the full 16-bit Unicode character set.
327 * The reading of bytes ends when either the end of file or a line terminator
328 * is encountered. The bytes read are then returned as a <code>String</code>.
329 * A line terminator is a byte sequence consisting of either
330 * <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination
331 * charaters are discarded and are not returned as part of the string.
333 * This method can read data that was written by an object implementing the
334 * <code>writeLine()</code> method in <code>DataOutput</code>.
336 * @return The line read as a <code>String</code>
338 * @exception IOException If an error occurs
343 readLine() throws IOException;
345 /*************************************************************************/
348 * This method reads a <code>String</code> from an input stream that is
349 * encoded in a modified UTF-8 format. This format has a leading two byte
350 * sequence that contains the remaining number of bytes to read. This two byte
351 * sequence is read using the <code>readUnsignedShort()</code> method of this
354 * After the number of remaining bytes have been determined, these bytes
355 * are read an transformed into <code>char</code> values. These
356 * <code>char</code> values are encoded in the stream using either a one, two,
357 * or three byte format.
358 * The particular format in use can be determined by examining the first
361 * If the first byte has a high order bit of 0, then
362 * that character consists on only one byte. This character value consists
363 * of seven bits that are at positions 0 through 6 of the byte. As an
364 * example, if <code>byte1</code> is the byte read from the stream, it would
365 * be converted to a <code>char</code> like so:
367 * <code>(char)byte1</code>
369 * If the first byte has 110 as its high order bits, then the
370 * character consists of two bytes. The bits that make up the character
371 * value are in positions 0 through 4 of the first byte and bit positions
372 * 0 through 5 of the second byte. (The second byte should have
373 * 10 as its high order bits). These values are in most significant
374 * byte first (i.e., "big endian") order.
376 * As an example, if <code>byte1</code> and <code>byte2</code> are the first
377 * two bytes read respectively, and the high order bits of them match the
378 * patterns which indicate a two byte character encoding, then they would be
379 * converted to a Java <code>char</code> like so:
381 * <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code>
383 * If the first byte has a 1110 as its high order bits, then the
384 * character consists of three bytes. The bits that make up the character
385 * value are in positions 0 through 3 of the first byte and bit positions
386 * 0 through 5 of the other two bytes. (The second and third bytes should
387 * have 10 as their high order bits). These values are in most
388 * significant byte first (i.e., "big endian") order.
390 * As an example, if <code>byte1</code>, <code>byte2</code>, and
391 * <code>byte3</code> are the three bytes read, and the high order bits of
392 * them match the patterns which indicate a three byte character encoding,
393 * then they would be converted to a Java <code>char</code> like so:
396 * (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F))
399 * Note that all characters are encoded in the method that requires the
400 * fewest number of bytes with the exception of the character with the
401 * value of <code>\<llll>u0000</code> which is encoded as two bytes. This is
402 * a modification of the UTF standard used to prevent C language style
403 * <code>NUL</code> values from appearing in the byte stream.
405 * This method can read data that was written by an object implementing the
406 * <code>writeUTF()</code> method in <code>DataOutput</code>.
408 * @returns The <code>String</code> read
410 * @exception EOFException If end of file is reached before reading the String
411 * @exception UTFDataFormatException If the data is not in UTF-8 format
412 * @exception IOException If any other error occurs
417 readUTF() throws EOFException, UTFDataFormatException, IOException;
419 /*************************************************************************/
422 * This method reads raw bytes into the passed array until the array is
423 * full. Note that this method blocks until the data is available and
424 * throws an exception if there is not enough data left in the stream to
427 * @param buf The buffer into which to read the data
429 * @exception EOFException If end of file is reached before filling the buffer
430 * @exception IOException If any other error occurs
433 readFully(byte[] buf) throws EOFException, IOException;
435 /*************************************************************************/
438 * This method reads raw bytes into the passed array <code>buf</code> starting
439 * <code>offset</code> bytes into the buffer. The number of bytes read will be
440 * exactly <code>len</code>. Note that this method blocks until the data is
441 * available and * throws an exception if there is not enough data left in
442 * the stream to read <code>len</code> bytes.
444 * @param buf The buffer into which to read the data
445 * @param offset The offset into the buffer to start storing data
446 * @param len The number of bytes to read into the buffer
448 * @exception EOFException If end of file is reached before filling the buffer
449 * @exception IOException If any other error occurs
452 readFully(byte[] buf, int offset, int len) throws EOFException, IOException;
454 /*************************************************************************/
457 * This method skips and discards the specified number of bytes in an
460 * @param num_bytes The number of bytes to skip
462 * @return The number of bytes actually skipped, which will always be
463 * <code>num_bytes</code>
465 * @exception EOFException If end of file is reached before all bytes can be
467 * @exception IOException If any other error occurs
470 skipBytes(int n) throws EOFException, IOException;
472 } // interface DataInput