001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.io;
028:
029: /**
030: * The <code>DataInput</code> interface provides
031: * for reading bytes from a binary stream and
032: * reconstructing from them data in any of
033: * the Java primitive types. There is also
034: * a
035: * facility for reconstructing a <code>String</code>
036: * from data in Java modified UTF-8 format.
037: * <p>
038: * It is generally true of all the reading
039: * routines in this interface that if end of
040: * file is reached before the desired number
041: * of bytes has been read, an <code>EOFException</code>
042: * (which is a kind of <code>IOException</code>)
043: * is thrown. If any byte cannot be read for
044: * any reason other than end of file, an <code>IOException</code>
045: * other than <code>EOFException</code> is
046: * thrown. In particular, an <code>IOException</code>
047: * may be thrown if the input stream has been
048: * closed.
049: *
050: * @version 12/17/01 (CLDC 1.1)
051: * @see java.io.DataInputStream
052: * @see java.io.DataOutput
053: * @since JDK1.0, CLDC 1.0
054: */
055: public interface DataInput {
056: /**
057: * Reads some bytes from an input
058: * stream and stores them into the buffer
059: * array <code>b</code>. The number of bytes
060: * read is equal
061: * to the length of <code>b</code>.
062: * <p>
063: * This method blocks until one of the
064: * following conditions occurs:<p>
065: * <ul>
066: * <li><code>b.length</code>
067: * bytes of input data are available, in which
068: * case a normal return is made.
069: *
070: * <li>End of file is detected, in which case
071: * an <code>EOFException</code> is thrown.
072: *
073: * <li>An I/O error occurs, in which case an
074: * <code>IOException</code> other than
075: * <code>EOFException</code> is thrown.
076: * </ul>
077: * <p>
078: * If <code>b</code> is <code>null</code>,
079: * a <code>NullPointerException</code> is thrown.
080: * If <code>b.length</code> is zero, then
081: * no bytes are read. Otherwise, the first
082: * byte read is stored into element <code>b[0]</code>,
083: * the next one into <code>b[1]</code>, and
084: * so on.
085: * If an exception is thrown from
086: * this method, then it may be that some but
087: * not all bytes of <code>b</code> have been
088: * updated with data from the input stream.
089: *
090: * @param b the buffer into which the data is read.
091: * @exception EOFException if this stream reaches the end
092: * before reading all the bytes.
093: * @exception IOException if an I/O error occurs.
094: */
095: void readFully(byte b[]) throws IOException;
096:
097: /**
098: * Reads <code>len</code>
099: * bytes from
100: * an input stream.
101: * <p>
102: * This method
103: * blocks until one of the following conditions
104: * occurs:<p>
105: * <ul>
106: * <li><code>len</code> bytes
107: * of input data are available, in which case
108: * a normal return is made.
109: *
110: * <li>End of file
111: * is detected, in which case an <code>EOFException</code>
112: * is thrown.
113: *
114: * <li>An I/O error occurs, in
115: * which case an <code>IOException</code> other
116: * than <code>EOFException</code> is thrown.
117: * </ul>
118: * <p>
119: * If <code>b</code> is <code>null</code>,
120: * a <code>NullPointerException</code> is thrown.
121: * If <code>off</code> is negative, or <code>len</code>
122: * is negative, or <code>off+len</code> is
123: * greater than the length of the array <code>b</code>,
124: * then an <code>IndexOutOfBoundsException</code>
125: * is thrown.
126: * If <code>len</code> is zero,
127: * then no bytes are read. Otherwise, the first
128: * byte read is stored into element <code>b[off]</code>,
129: * the next one into <code>b[off+1]</code>,
130: * and so on. The number of bytes read is,
131: * at most, equal to <code>len</code>.
132: *
133: * @param b the buffer into which the data is read.
134: * @param off an int specifying the offset into the data.
135: * @param len an int specifying the number of bytes to read.
136: * @exception EOFException if this stream reaches the end
137: * before reading all the bytes.
138: * @exception IOException if an I/O error occurs.
139: */
140: void readFully(byte b[], int off, int len) throws IOException;
141:
142: /**
143: * Makes an attempt to skip over <code>n</code> bytes
144: * of data from the input stream, discarding the skipped
145: * bytes. However, it may skip over some smaller number of
146: * bytes, possibly zero. This may result from any of a
147: * number of conditions; reaching end of file before
148: * <code>n</code> bytes have been skipped is only one
149: * possibility.
150: * This method never throws an <code>EOFException</code>.
151: * The actual number of bytes skipped is returned.
152: *
153: * @param n the number of bytes to be skipped.
154: * @return the actual number of bytes skipped.
155: * @exception IOException if an I/O error occurs.
156: */
157: int skipBytes(int n) throws IOException;
158:
159: /**
160: * Reads one input byte and returns
161: * <code>true</code> if that byte is nonzero,
162: * <code>false</code> if that byte is zero.
163: * This method is suitable for reading
164: * the byte written by the <code>writeBoolean</code>
165: * method of interface <code>DataOutput</code>.
166: *
167: * @return the <code>boolean</code> value read.
168: * @exception EOFException if this stream reaches the end
169: * before reading all the bytes.
170: * @exception IOException if an I/O error occurs.
171: */
172: boolean readBoolean() throws IOException;
173:
174: /**
175: * Reads and returns one input byte.
176: * The byte is treated as a signed value in
177: * the range <code>-128</code> through <code>127</code>,
178: * inclusive.
179: * This method is suitable for
180: * reading the byte written by the <code>writeByte</code>
181: * method of interface <code>DataOutput</code>.
182: *
183: * @return the 8-bit value read.
184: * @exception EOFException if this stream reaches the end
185: * before reading all the bytes.
186: * @exception IOException if an I/O error occurs.
187: */
188: byte readByte() throws IOException;
189:
190: /**
191: * Reads one input byte, zero-extends
192: * it to type <code>int</code>, and returns
193: * the result, which is therefore in the range
194: * <code>0</code>
195: * through <code>255</code>.
196: * This method is suitable for reading
197: * the byte written by the <code>writeByte</code>
198: * method of interface <code>DataOutput</code>
199: * if the argument to <code>writeByte</code>
200: * was intended to be a value in the range
201: * <code>0</code> through <code>255</code>.
202: *
203: * @return the unsigned 8-bit value read.
204: * @exception EOFException if this stream reaches the end
205: * before reading all the bytes.
206: * @exception IOException if an I/O error occurs.
207: */
208: int readUnsignedByte() throws IOException;
209:
210: /**
211: * Reads two input bytes and returns
212: * a <code>short</code> value. Let <code>a</code>
213: * be the first byte read and <code>b</code>
214: * be the second byte. The value
215: * returned is:
216: * <p><pre><code>(short)((a << 8) | (b & 0xff))
217: * </code></pre>
218: * This method is suitable for reading the bytes
219: * written by the <code>writeShort</code> method of
220: * interface <code>DataOutput</code>.
221: *
222: * @return the 16-bit value read.
223: * @exception EOFException if this stream reaches the end
224: * before reading all the bytes.
225: * @exception IOException if an I/O error occurs.
226: */
227: short readShort() throws IOException;
228:
229: /**
230: * Reads two input bytes, zero-extends
231: * it to type <code>int</code>, and returns
232: * an <code>int</code> value in the range <code>0</code>
233: * through <code>65535</code>. Let <code>a</code>
234: * be the first byte read and
235: * <code>b</code>
236: * be the second byte. The value returned is:
237: * <p><pre><code>(((a & 0xff) << 8) | (b & 0xff))
238: * </code></pre>
239: * This method is suitable for reading the bytes
240: * written by the <code>writeShort</code> method
241: * of interface <code>DataOutput</code> if
242: * the argument to <code>writeShort</code>
243: * was intended to be a value in the range
244: * <code>0</code> through <code>65535</code>.
245: *
246: * @return the unsigned 16-bit value read.
247: * @exception EOFException if this stream reaches the end
248: * before reading all the bytes.
249: * @exception IOException if an I/O error occurs.
250: */
251: int readUnsignedShort() throws IOException;
252:
253: /**
254: * Reads an input <code>char</code> and returns the <code>char</code> value.
255: * A Unicode <code>char</code> is made up of two bytes.
256: * Let <code>a</code>
257: * be the first byte read and <code>b</code>
258: * be the second byte. The value
259: * returned is:
260: * <p><pre><code>(char)((a << 8) | (b & 0xff))
261: * </code></pre>
262: * This method is suitable for reading bytes written by
263: * the <code>writeChar</code> method of interface
264: * <code>DataOutput</code>.
265: *
266: * @return the Unicode <code>char</code> read.
267: * @exception EOFException if this stream reaches the end
268: * before reading all the bytes.
269: * @exception IOException if an I/O error occurs.
270: */
271: char readChar() throws IOException;
272:
273: /**
274: * Reads four input bytes and returns an
275: * <code>int</code> value. Let <code>a</code>
276: * be the first byte read, <code>b</code> be
277: * the second byte, <code>c</code> be the third
278: * byte, and <code>d</code> be the fourth
279: * byte. The value returned is:
280: * <p><pre>
281: * <code>
282: * (((a & 0xff) << 24) | ((b & 0xff) << 16) |
283: *  ((c & 0xff) << 8) | (d & 0xff))
284: * </code></pre>
285: * This method is suitable
286: * for reading bytes written by the <code>writeInt</code>
287: * method of interface <code>DataOutput</code>.
288: *
289: * @return the <code>int</code> value read.
290: * @exception EOFException if this stream reaches the end
291: * before reading all the bytes.
292: * @exception IOException if an I/O error occurs.
293: */
294: int readInt() throws IOException;
295:
296: /**
297: * Reads eight input bytes and returns
298: * a <code>long</code> value. Let <code>a</code>
299: * be the first byte read, <code>b</code> be
300: * the second byte, <code>c</code> be the third
301: * byte, <code>d</code> be the fourth byte,
302: * <code>e</code> be the fifth byte, <code>f</code>
303: * be the sixth byte, <code>g</code> be the
304: * seventh byte, and <code>h</code> be the
305: * eighth byte. The value returned is:
306: * <p><pre> <code>
307: * (((long)(a & 0xff) << 56) |
308: * ((long)(b & 0xff) << 48) |
309: * ((long)(c & 0xff) << 40) |
310: * ((long)(d & 0xff) << 32) |
311: * ((long)(e & 0xff) << 24) |
312: * ((long)(f & 0xff) << 16) |
313: * ((long)(g & 0xff) << 8) |
314: * ((long)(h & 0xff)))
315: * </code></pre>
316: * <p>
317: * This method is suitable
318: * for reading bytes written by the <code>writeLong</code>
319: * method of interface <code>DataOutput</code>.
320: *
321: * @return the <code>long</code> value read.
322: * @exception EOFException if this stream reaches the end
323: * before reading all the bytes.
324: * @exception IOException if an I/O error occurs.
325: */
326: long readLong() throws IOException;
327:
328: /**
329: * Reads four input bytes and returns
330: * a <code>float</code> value. It does this
331: * by first constructing an <code>int</code>
332: * value in exactly the manner
333: * of the <code>readInt</code>
334: * method, then converting this <code>int</code>
335: * value to a <code>float</code> in
336: * exactly the manner of the method <code>Float.intBitsToFloat</code>.
337: * This method is suitable for reading
338: * bytes written by the <code>writeFloat</code>
339: * method of interface <code>DataOutput</code>.
340: *
341: * @return the <code>float</code> value read.
342: * @exception EOFException if this stream reaches the end
343: * before reading all the bytes.
344: * @exception IOException if an I/O error occurs.
345: * @since CLDC 1.1
346: */
347: float readFloat() throws IOException;
348:
349: /**
350: * Reads eight input bytes and returns
351: * a <code>double</code> value. It does this
352: * by first constructing a <code>long</code>
353: * value in exactly the manner
354: * of the <code>readlong</code>
355: * method, then converting this <code>long</code>
356: * value to a <code>double</code> in exactly
357: * the manner of the method <code>Double.longBitsToDouble</code>.
358: * This method is suitable for reading
359: * bytes written by the <code>writeDouble</code>
360: * method of interface <code>DataOutput</code>.
361: *
362: * @return the <code>double</code> value read.
363: * @exception EOFException if this stream reaches the end
364: * before reading all the bytes.
365: * @exception IOException if an I/O error occurs.
366: * @since CLDC 1.1
367: */
368: double readDouble() throws IOException;
369:
370: /**
371: * Reads in a string that has been encoded using a modified UTF-8 format.
372: * The general contract of <code>readUTF</code>
373: * is that it reads a representation of a Unicode
374: * character string encoded in Java modified
375: * UTF-8 format; this string of characters
376: * is then returned as a <code>String</code>.
377: * <p>
378: * First, two bytes are read and used to
379: * construct an unsigned 16-bit integer in
380: * exactly the manner of the <code>readUnsignedShort</code>
381: * method . This integer value is called the
382: * <i>UTF length</i> and specifies the number
383: * of additional bytes to be read. These bytes
384: * are then converted to characters by considering
385: * them in groups. The length of each group
386: * is computed from the value of the first
387: * byte of the group. The byte following a
388: * group, if any, is the first byte of the
389: * next group.
390: * <p>
391: * If the first byte of a group
392: * matches the bit pattern <code>0xxxxxxx</code>
393: * (where <code>x</code> means "may be <code>0</code>
394: * or <code>1</code>"), then the group consists
395: * of just that byte. The byte is zero-extended
396: * to form a character.
397: * <p>
398: * If the first byte
399: * of a group matches the bit pattern <code>110xxxxx</code>,
400: * then the group consists of that byte <code>a</code>
401: * and a second byte <code>b</code>. If there
402: * is no byte <code>b</code> (because byte
403: * <code>a</code> was the last of the bytes
404: * to be read), or if byte <code>b</code> does
405: * not match the bit pattern <code>10xxxxxx</code>,
406: * then a <code>UTFDataFormatException</code>
407: * is thrown. Otherwise, the group is converted
408: * to the character:<p>
409: * <pre><code>(char)(((a& 0x1F) << 6) | (b & 0x3F))
410: * </code></pre>
411: * If the first byte of a group
412: * matches the bit pattern <code>1110xxxx</code>,
413: * then the group consists of that byte <code>a</code>
414: * and two more bytes <code>b</code> and <code>c</code>.
415: * If there is no byte <code>c</code> (because
416: * byte <code>a</code> was one of the last
417: * two of the bytes to be read), or either
418: * byte <code>b</code> or byte <code>c</code>
419: * does not match the bit pattern <code>10xxxxxx</code>,
420: * then a <code>UTFDataFormatException</code>
421: * is thrown. Otherwise, the group is converted
422: * to the character:<p>
423: * <pre><code>
424: * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
425: * </code></pre>
426: * If the first byte of a group matches the
427: * pattern <code>1111xxxx</code> or the pattern
428: * <code>10xxxxxx</code>, then a <code>UTFDataFormatException</code>
429: * is thrown.
430: * <p>
431: * If end of file is encountered
432: * at any time during this entire process,
433: * then an <code>EOFException</code> is thrown.
434: * <p>
435: * After every group has been converted to
436: * a character by this process, the characters
437: * are gathered, in the same order in which
438: * their corresponding groups were read from
439: * the input stream, to form a <code>String</code>,
440: * which is returned.
441: * <p>
442: * The <code>writeUTF</code>
443: * method of interface <code>DataOutput</code>
444: * may be used to write data that is suitable
445: * for reading by this method.
446: * @return a Unicode string.
447: * @exception EOFException if this stream reaches the end
448: * before reading all the bytes.
449: * @exception IOException if an I/O error occurs.
450: * @exception UTFDataFormatException if the bytes do not represent a
451: * valid UTF-8 encoding of a string.
452: */
453: String readUTF() throws IOException;
454:
455: }
|