1 /*
2 * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved.
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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 *
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.
24 */
25
26 package javax.imageio.stream;
27
28 import java.io.DataInput;
29 import java.io.IOException;
30 import java.nio.ByteOrder;
31
32 /**
33 * A seekable input stream interface for use by
34 * <code>ImageReader</code>s. Various input sources, such as
35 * <code>InputStream</code>s and <code>File</code>s,
36 * as well as future fast I/O sources may be "wrapped" by a suitable
37 * implementation of this interface for use by the Image I/O API.
38 *
39 * @see ImageInputStreamImpl
40 * @see FileImageInputStream
41 * @see FileCacheImageInputStream
42 * @see MemoryCacheImageInputStream
43 *
44 */
45 public interface ImageInputStream extends DataInput {
46
47 /**
48 * Sets the desired byte order for future reads of data values
49 * from this stream. For example, the sequence of bytes '0x01
50 * 0x02 0x03 0x04' if read as a 4-byte integer would have the
51 * value '0x01020304' using network byte order and the value
52 * '0x04030201' under the reverse byte order.
53 *
54 * <p> The enumeration class <code>java.nio.ByteOrder</code> is
55 * used to specify the byte order. A value of
56 * <code>ByteOrder.BIG_ENDIAN</code> specifies so-called
57 * big-endian or network byte order, in which the high-order byte
58 * comes first. Motorola and Sparc processors store data in this
59 * format, while Intel processors store data in the reverse
60 * <code>ByteOrder.LITTLE_ENDIAN</code> order.
61 *
62 * <p> The byte order has no effect on the results returned from
63 * the <code>readBits</code> method (or the value written by
64 * <code>ImageOutputStream.writeBits</code>).
65 *
66 * @param byteOrder one of <code>ByteOrder.BIG_ENDIAN</code> or
67 * <code>java.nio.ByteOrder.LITTLE_ENDIAN</code>, indicating whether
68 * network byte order or its reverse will be used for future
69 * reads.
70 *
71 * @see java.nio.ByteOrder
72 * @see #getByteOrder
73 * @see #readBits(int)
74 */
75 void setByteOrder(ByteOrder byteOrder);
76
77 /**
78 * Returns the byte order with which data values will be read from
79 * this stream as an instance of the
80 * <code>java.nio.ByteOrder</code> enumeration.
81 *
82 * @return one of <code>ByteOrder.BIG_ENDIAN</code> or
83 * <code>ByteOrder.LITTLE_ENDIAN</code>, indicating which byte
84 * order is being used.
85 *
86 * @see java.nio.ByteOrder
87 * @see #setByteOrder
88 */
89 ByteOrder getByteOrder();
90
91 /**
92 * Reads a single byte from the stream and returns it as an
93 * integer between 0 and 255. If the end of the stream is
94 * reached, -1 is returned.
95 *
96 * <p> The bit offset within the stream is reset to zero before
97 * the read occurs.
98 *
99 * @return a byte value from the stream, as an int, or -1 to
100 * indicate EOF.
101 *
102 * @exception IOException if an I/O error occurs.
103 */
104 int read() throws IOException;
105
106 /**
107 * Reads up to <code>b.length</code> bytes from the stream, and
108 * stores them into <code>b</code> starting at index 0. The
109 * number of bytes read is returned. If no bytes can be read
110 * because the end of the stream has been reached, -1 is returned.
111 *
112 * <p> The bit offset within the stream is reset to zero before
113 * the read occurs.
114 *
115 * @param b an array of bytes to be written to.
116 *
117 * @return the number of bytes actually read, or <code>-1</code>
118 * to indicate EOF.
119 *
120 * @exception NullPointerException if <code>b</code> is
121 * <code>null</code>.
122 *
123 * @exception IOException if an I/O error occurs.
124 */
125 int read(byte[] b) throws IOException;
126
127 /**
128 * Reads up to <code>len</code> bytes from the stream, and stores
129 * them into <code>b</code> starting at index <code>off</code>.
130 * The number of bytes read is returned. If no bytes can be read
131 * because the end of the stream has been reached, <code>-1</code>
132 * is returned.
133 *
134 * <p> The bit offset within the stream is reset to zero before
135 * the read occurs.
136 *
137 * @param b an array of bytes to be written to.
138 * @param off the starting position within <code>b</code> to write to.
139 * @param len the maximum number of <code>byte</code>s to read.
140 *
141 * @return the number of bytes actually read, or <code>-1</code>
142 * to indicate EOF.
143 *
144 * @exception NullPointerException if <code>b</code> is
145 * <code>null</code>.
146 * @exception IndexOutOfBoundsException if <code>off</code> is
147 * negative, <code>len</code> is negative, or <code>off +
148 * len</code> is greater than <code>b.length</code>.
149 * @exception IOException if an I/O error occurs.
150 */
151 int read(byte[] b, int off, int len) throws IOException;
152
153 /**
154 * Reads up to <code>len</code> bytes from the stream, and
155 * modifies the supplied <code>IIOByteBuffer</code> to indicate
156 * the byte array, offset, and length where the data may be found.
157 * The caller should not attempt to modify the data found in the
158 * <code>IIOByteBuffer</code>.
159 *
160 * <p> The bit offset within the stream is reset to zero before
161 * the read occurs.
162 *
163 * @param buf an IIOByteBuffer object to be modified.
164 * @param len the maximum number of <code>byte</code>s to read.
165 *
166 * @exception IndexOutOfBoundsException if <code>len</code> is
167 * negative.
168 * @exception NullPointerException if <code>buf</code> is
169 * <code>null</code>.
170 *
171 * @exception IOException if an I/O error occurs.
172 */
173 void readBytes(IIOByteBuffer buf, int len) throws IOException;
174
175 /**
176 * Reads a byte from the stream and returns a <code>boolean</code>
177 * value of <code>true</code> if it is nonzero, <code>false</code>
178 * if it is zero.
179 *
180 * <p> The bit offset within the stream is reset to zero before
181 * the read occurs.
182 *
183 * @return a boolean value from the stream.
184 *
185 * @exception EOFException if the end of the stream is reached.
186 * @exception IOException if an I/O error occurs.
187 */
188 boolean readBoolean() throws IOException;
189
190 /**
191 * Reads a byte from the stream and returns it as a
192 * <code>byte</code> value. Byte values between <code>0x00</code>
193 * and <code>0x7f</code> represent integer values between
194 * <code>0</code> and <code>127</code>. Values between
195 * <code>0x80</code> and <code>0xff</code> represent negative
196 * values from <code>-128</code> to <code>/1</code>.
197 *
198 * <p> The bit offset within the stream is reset to zero before
199 * the read occurs.
200 *
201 * @return a signed byte value from the stream.
202 *
203 * @exception EOFException if the end of the stream is reached.
204 * @exception IOException if an I/O error occurs.
205 */
206 byte readByte() throws IOException;
207
208 /**
209 * Reads a byte from the stream, and (conceptually) converts it to
210 * an int, masks it with <code>0xff</code> in order to strip off
211 * any sign-extension bits, and returns it as a <code>byte</code>
212 * value.
213 *
214 * <p> Thus, byte values between <code>0x00</code> and
215 * <code>0x7f</code> are simply returned as integer values between
216 * <code>0</code> and <code>127</code>. Values between
217 * <code>0x80</code> and <code>0xff</code>, which normally
218 * represent negative <code>byte</code>values, will be mapped into
219 * positive integers between <code>128</code> and
220 * <code>255</code>.
221 *
222 * <p> The bit offset within the stream is reset to zero before
223 * the read occurs.
224 *
225 * @return an unsigned byte value from the stream.
226 *
227 * @exception EOFException if the end of the stream is reached.
228 * @exception IOException if an I/O error occurs.
229 */
230 int readUnsignedByte() throws IOException;
231
232 /**
233 * Reads two bytes from the stream, and (conceptually)
234 * concatenates them according to the current byte order, and
235 * returns the result as a <code>short</code> value.
236 *
237 * <p> The bit offset within the stream is reset to zero before
238 * the read occurs.
239 *
240 * @return a signed short value from the stream.
241 *
242 * @exception EOFException if the stream reaches the end before
243 * reading all the bytes.
244 * @exception IOException if an I/O error occurs.
245 *
246 * @see #getByteOrder
247 */
248 short readShort() throws IOException;
249
250 /**
251 * Reads two bytes from the stream, and (conceptually)
252 * concatenates them according to the current byte order, converts
253 * the resulting value to an <code>int</code>, masks it with
254 * <code>0xffff</code> in order to strip off any sign-extension
255 * buts, and returns the result as an unsigned <code>int</code>
256 * value.
257 *
258 * <p> The bit offset within the stream is reset to zero before
259 * the read occurs.
260 *
261 * @return an unsigned short value from the stream, as an int.
262 *
263 * @exception EOFException if the stream reaches the end before
264 * reading all the bytes.
265 * @exception IOException if an I/O error occurs.
266 *
267 * @see #getByteOrder
268 */
269 int readUnsignedShort() throws IOException;
270
271 /**
272 * Equivalent to <code>readUnsignedShort</code>, except that the
273 * result is returned using the <code>char</code> datatype.
274 *
275 * <p> The bit offset within the stream is reset to zero before
276 * the read occurs.
277 *
278 * @return an unsigned char value from the stream.
279 *
280 * @exception EOFException if the stream reaches the end before
281 * reading all the bytes.
282 * @exception IOException if an I/O error occurs.
283 *
284 * @see #readUnsignedShort
285 */
286 char readChar() throws IOException;
287
288 /**
289 * Reads 4 bytes from the stream, and (conceptually) concatenates
290 * them according to the current byte order and returns the result
291 * as an <code>int</code>.
292 *
293 * <p> The bit offset within the stream is ignored and treated as
294 * though it were zero.
295 *
296 * @return a signed int value from the stream.
297 *
298 * @exception EOFException if the stream reaches the end before
299 * reading all the bytes.
300 * @exception IOException if an I/O error occurs.
301 *
302 * @see #getByteOrder
303 */
304 int readInt() throws IOException;
305
306 /**
307 * Reads 4 bytes from the stream, and (conceptually) concatenates
308 * them according to the current byte order, converts the result
309 * to a long, masks it with <code>0xffffffffL</code> in order to
310 * strip off any sign-extension bits, and returns the result as an
311 * unsigned <code>long</code> value.
312 *
313 * <p> The bit offset within the stream is reset to zero before
314 * the read occurs.
315 *
316 * @return an unsigned int value from the stream, as a long.
317 *
318 * @exception EOFException if the stream reaches the end before
319 * reading all the bytes.
320 * @exception IOException if an I/O error occurs.
321 *
322 * @see #getByteOrder
323 */
324 long readUnsignedInt() throws IOException;
325
326 /**
327 * Reads 8 bytes from the stream, and (conceptually) concatenates
328 * them according to the current byte order and returns the result
329 * as a <code>long</code>.
330 *
331 * <p> The bit offset within the stream is reset to zero before
332 * the read occurs.
333 *
334 * @return a signed long value from the stream.
335 *
336 * @exception EOFException if the stream reaches the end before
337 * reading all the bytes.
338 * @exception IOException if an I/O error occurs.
339 *
340 * @see #getByteOrder
341 */
342 long readLong() throws IOException;
343
344 /**
345 * Reads 4 bytes from the stream, and (conceptually) concatenates
346 * them according to the current byte order and returns the result
347 * as a <code>float</code>.
348 *
349 * <p> The bit offset within the stream is reset to zero before
350 * the read occurs.
351 *
352 * @return a float value from the stream.
353 *
354 * @exception EOFException if the stream reaches the end before
355 * reading all the bytes.
356 * @exception IOException if an I/O error occurs.
357 *
358 * @see #getByteOrder
359 */
360 float readFloat() throws IOException;
361
362 /**
363 * Reads 8 bytes from the stream, and (conceptually) concatenates
364 * them according to the current byte order and returns the result
365 * as a <code>double</code>.
366 *
367 * <p> The bit offset within the stream is reset to zero before
368 * the read occurs.
369 *
370 * @return a double value from the stream.
371 *
372 * @exception EOFException if the stream reaches the end before
373 * reading all the bytes.
374 * @exception IOException if an I/O error occurs.
375 *
376 * @see #getByteOrder
377 */
378 double readDouble() throws IOException;
379
380 /**
381 * Reads the next line of text from the input stream. It reads
382 * successive bytes, converting each byte separately into a
383 * character, until it encounters a line terminator or end of
384 * file; the characters read are then returned as a
385 * <code>String</code>. Note that because this method processes
386 * bytes, it does not support input of the full Unicode character
387 * set.
388 *
389 * <p> If end of file is encountered before even one byte can be
390 * read, then <code>null</code> is returned. Otherwise, each byte
391 * that is read is converted to type <code>char</code> by
392 * zero-extension. If the character <code>'\n'</code> is
393 * encountered, it is discarded and reading ceases. If the
394 * character <code>'\r'</code> is encountered, it is discarded
395 * and, if the following byte converts  to the character
396 * <code>'\n'</code>, then that is discarded also; reading then
397 * ceases. If end of file is encountered before either of the
398 * characters <code>'\n'</code> and <code>'\r'</code> is
399 * encountered, reading ceases. Once reading has ceased, a
400 * <code>String</code> is returned that contains all the
401 * characters read and not discarded, taken in order. Note that
402 * every character in this string will have a value less than
403 * <code>\u0100</code>, that is, <code>(char)256</code>.
404 *
405 * <p> The bit offset within the stream is reset to zero before
406 * the read occurs.
407 *
408 * @return a String containing a line of text from the stream.
409 *
410 * @exception IOException if an I/O error occurs.
411 */
412 String readLine() throws IOException;
413
414 /**
415 * Reads in a string that has been encoded using a
416 * <a href="../../../java/io/DataInput.html#modified-utf-8">modified
417 * UTF-8</a>
418 * format. The general contract of <code>readUTF</code> is that
419 * it reads a representation of a Unicode character string encoded
420 * in modified UTF-8 format; this string of characters is
421 * then returned as a <code>String</code>.
422 *
423 * <p> First, two bytes are read and used to construct an unsigned
424 * 16-bit integer in the manner of the
425 * <code>readUnsignedShort</code> method, using network byte order
426 * (regardless of the current byte order setting). This integer
427 * value is called the <i>UTF length</i> and specifies the number
428 * of additional bytes to be read. These bytes are then converted
429 * to characters by considering them in groups. The length of each
430 * group is computed from the value of the first byte of the
431 * group. The byte following a group, if any, is the first byte of
432 * the next group.
433 *
434 * <p> If the first byte of a group matches the bit pattern
435 * <code>0xxxxxxx</code> (where <code>x</code> means "may be
436 * <code>0</code> or <code>1</code>"), then the group consists of
437 * just that byte. The byte is zero-extended to form a character.
438 *
439 * <p> If the first byte of a group matches the bit pattern
440 * <code>110xxxxx</code>, then the group consists of that byte
441 * <code>a</code> and a second byte <code>b</code>. If there is no
442 * byte <code>b</code> (because byte <code>a</code> was the last
443 * of the bytes to be read), or if byte <code>b</code> does not
444 * match the bit pattern <code>10xxxxxx</code>, then a
445 * <code>UTFDataFormatException</code> is thrown. Otherwise, the
446 * group is converted to the character:
447 *
448 * <p> <pre><code>
449 * (char)(((a& 0x1F) << 6) | (b & 0x3F))
450 * </code></pre>
451 *
452 * If the first byte of a group matches the bit pattern
453 * <code>1110xxxx</code>, then the group consists of that byte
454 * <code>a</code> and two more bytes <code>b</code> and
455 * <code>c</code>. If there is no byte <code>c</code> (because
456 * byte <code>a</code> was one of the last two of the bytes to be
457 * read), or either byte <code>b</code> or byte <code>c</code>
458 * does not match the bit pattern <code>10xxxxxx</code>, then a
459 * <code>UTFDataFormatException</code> is thrown. Otherwise, the
460 * group is converted to the character:
461 *
462 * <p> <pre><code>
463 * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
464 * </code></pre>
465 *
466 * If the first byte of a group matches the pattern
467 * <code>1111xxxx</code> or the pattern <code>10xxxxxx</code>,
468 * then a <code>UTFDataFormatException</code> is thrown.
469 *
470 * <p> If end of file is encountered at any time during this
471 * entire process, then an <code>EOFException</code> is thrown.
472 *
473 * <p> After every group has been converted to a character by this
474 * process, the characters are gathered, in the same order in
475 * which their corresponding groups were read from the input
476 * stream, to form a <code>String</code>, which is returned.
477 *
478 * <p> The current byte order setting is ignored.
479 *
480 * <p> The bit offset within the stream is reset to zero before
481 * the read occurs.
482 *
483 * <p><strong>Note:</strong> This method should not be used in
484 * the implementation of image formats that use standard UTF-8,
485 * because the modified UTF-8 used here is incompatible with
486 * standard UTF-8.
487 *
488 * @return a String read from the stream.
489 *
490 * @exception EOFException if this stream reaches the end
491 * before reading all the bytes.
492 * @exception UTFDataFormatException if the bytes do not represent a
493 * valid modified UTF-8 encoding of a string.
494 * @exception IOException if an I/O error occurs.
495 */
496 String readUTF() throws IOException;
497
498 /**
499 * Reads <code>len</code> bytes from the stream, and stores them
500 * into <code>b</code> starting at index <code>off</code>.
501 * If the end of the stream is reached, an <code>EOFException</code>
502 * will be thrown.
503 *
504 * <p> The bit offset within the stream is reset to zero before
505 * the read occurs.
506 *
507 * @param b an array of bytes to be written to.
508 * @param off the starting position within <code>b</code> to write to.
509 * @param len the maximum number of <code>byte</code>s to read.
510 *
511 * @exception IndexOutOfBoundsException if <code>off</code> is
512 * negative, <code>len</code> is negative, or <code>off +
513 * len</code> is greater than <code>b.length</code>.
514 * @exception NullPointerException if <code>b</code> is
515 * <code>null</code>.
516 * @exception EOFException if the stream reaches the end before
517 * reading all the bytes.
518 * @exception IOException if an I/O error occurs.
519 */
520 void readFully(byte[] b, int off, int len) throws IOException;
521
522 /**
523 * Reads <code>b.length</code> bytes from the stream, and stores them
524 * into <code>b</code> starting at index <code>0</code>.
525 * If the end of the stream is reached, an <code>EOFException</code>
526 * will be thrown.
527 *
528 * <p> The bit offset within the stream is reset to zero before
529 * the read occurs.
530 *
531 * @param b an array of <code>byte</code>s.
532 *
533 * @exception NullPointerException if <code>b</code> is
534 * <code>null</code>.
535 * @exception EOFException if the stream reaches the end before
536 * reading all the bytes.
537 * @exception IOException if an I/O error occurs.
538 */
539 void readFully(byte[] b) throws IOException;
540
541 /**
542 * Reads <code>len</code> shorts (signed 16-bit integers) from the
543 * stream according to the current byte order, and
544 * stores them into <code>s</code> starting at index
545 * <code>off</code>. If the end of the stream is reached, an
546 * <code>EOFException</code> will be thrown.
547 *
548 * <p> The bit offset within the stream is reset to zero before
549 * the read occurs.
550 *
551 * @param s an array of shorts to be written to.
552 * @param off the starting position withinb to write to.
553 * @param len the maximum number of <code>short</code>s to read.
554 *
555 * @exception IndexOutOfBoundsException if <code>off</code> is
556 * negative, <code>len</code> is negative, or <code>off +
557 * len</code> is greater than <code>s.length</code>.
558 * @exception NullPointerException if <code>s</code> is
559 * <code>null</code>.
560 * @exception EOFException if the stream reaches the end before
561 * reading all the bytes.
562 * @exception IOException if an I/O error occurs.
563 */
564 void readFully(short[] s, int off, int len) throws IOException;
565
566 /**
567 * Reads <code>len</code> chars (unsigned 16-bit integers) from the
568 * stream according to the current byte order, and
569 * stores them into <code>c</code> starting at index
570 * <code>off</code>. If the end of the stream is reached, an
571 * <code>EOFException</code> will be thrown.
572 *
573 * <p> The bit offset within the stream is reset to zero before
574 * the read occurs.
575 *
576 * @param c an array of chars to be written to.
577 * @param off the starting position withinb to write to.
578 * @param len the maximum number of <code>char</code>s to read.
579 *
580 * @exception IndexOutOfBoundsException if <code>off</code> is
581 * negative, <code>len</code> is negative, or <code>off +
582 * len</code> is greater than <code>c.length</code>.
583 * @exception NullPointerException if <code>c</code> is
584 * <code>null</code>.
585 * @exception EOFException if the stream reaches the end before
586 * reading all the bytes.
587 * @exception IOException if an I/O error occurs.
588 */
589 void readFully(char[] c, int off, int len) throws IOException;
590
591 /**
592 * Reads <code>len</code> ints (signed 32-bit integers) from the
593 * stream according to the current byte order, and
594 * stores them into <code>i</code> starting at index
595 * <code>off</code>. If the end of the stream is reached, an
596 * <code>EOFException</code> will be thrown.
597 *
598 * <p> The bit offset within the stream is reset to zero before
599 * the read occurs.
600 *
601 * @param i an array of ints to be written to.
602 * @param off the starting position withinb to write to.
603 * @param len the maximum number of <code>int</code>s to read.
604 *
605 * @exception IndexOutOfBoundsException if <code>off</code> is
606 * negative, <code>len</code> is negative, or <code>off +
607 * len</code> is greater than <code>i.length</code>.
608 * @exception NullPointerException if <code>i</code> is
609 * <code>null</code>.
610 * @exception EOFException if the stream reaches the end before
611 * reading all the bytes.
612 * @exception IOException if an I/O error occurs.
613 */
614 void readFully(int[] i, int off, int len) throws IOException;
615
616 /**
617 * Reads <code>len</code> longs (signed 64-bit integers) from the
618 * stream according to the current byte order, and
619 * stores them into <code>l</code> starting at index
620 * <code>off</code>. If the end of the stream is reached, an
621 * <code>EOFException</code> will be thrown.
622 *
623 * <p> The bit offset within the stream is reset to zero before
624 * the read occurs.
625 *
626 * @param l an array of longs to be written to.
627 * @param off the starting position withinb to write to.
628 * @param len the maximum number of <code>long</code>s to read.
629 *
630 * @exception IndexOutOfBoundsException if <code>off</code> is
631 * negative, <code>len</code> is negative, or <code>off +
632 * len</code> is greater than <code>l.length</code>.
633 * @exception NullPointerException if <code>l</code> is
634 * <code>null</code>.
635 * @exception EOFException if the stream reaches the end before
636 * reading all the bytes.
637 * @exception IOException if an I/O error occurs.
638 */
639 void readFully(long[] l, int off, int len) throws IOException;
640
641 /**
642 * Reads <code>len</code> floats (32-bit IEEE single-precision
643 * floats) from the stream according to the current byte order,
644 * and stores them into <code>f</code> starting at
645 * index <code>off</code>. If the end of the stream is reached,
646 * an <code>EOFException</code> will be thrown.
647 *
648 * <p> The bit offset within the stream is reset to zero before
649 * the read occurs.
650 *
651 * @param f an array of floats to be written to.
652 * @param off the starting position withinb to write to.
653 * @param len the maximum number of <code>float</code>s to read.
654 *
655 * @exception IndexOutOfBoundsException if <code>off</code> is
656 * negative, <code>len</code> is negative, or <code>off +
657 * len</code> is greater than <code>f.length</code>.
658 * @exception NullPointerException if <code>f</code> is
659 * <code>null</code>.
660 * @exception EOFException if the stream reaches the end before
661 * reading all the bytes.
662 * @exception IOException if an I/O error occurs.
663 */
664 void readFully(float[] f, int off, int len) throws IOException;
665
666 /**
667 * Reads <code>len</code> doubles (64-bit IEEE double-precision
668 * floats) from the stream according to the current byte order,
669 * and stores them into <code>d</code> starting at
670 * index <code>off</code>. If the end of the stream is reached,
671 * an <code>EOFException</code> will be thrown.
672 *
673 * <p> The bit offset within the stream is reset to zero before
674 * the read occurs.
675 *
676 * @param d an array of doubles to be written to.
677 * @param off the starting position withinb to write to.
678 * @param len the maximum number of <code>double</code>s to read.
679 *
680 * @exception IndexOutOfBoundsException if <code>off</code> is
681 * negative, <code>len</code> is negative, or <code>off +
682 * len</code> is greater than <code>d.length</code>.
683 * @exception NullPointerException if <code>d</code> is
684 * <code>null</code>.
685 * @exception EOFException if the stream reaches the end before
686 * reading all the bytes.
687 * @exception IOException if an I/O error occurs.
688 */
689 void readFully(double[] d, int off, int len) throws IOException;
690
691 /**
692 * Returns the current byte position of the stream. The next read
693 * will take place starting at this offset.
694 *
695 * @return a long containing the position of the stream.
696 *
697 * @exception IOException if an I/O error occurs.
698 */
699 long getStreamPosition() throws IOException;
700
701 /**
702 * Returns the current bit offset, as an integer between 0 and 7,
703 * inclusive. The bit offset is updated implicitly by calls to
704 * the <code>readBits</code> method. A value of 0 indicates the
705 * most-significant bit, and a value of 7 indicates the least
706 * significant bit, of the byte being read.
707 *
708 * <p> The bit offset is set to 0 when a stream is first
709 * opened, and is reset to 0 by calls to <code>seek</code>,
710 * <code>skipBytes</code>, or any <code>read</code> or
711 * <code>readFully</code> method.
712 *
713 * @return an <code>int</code> containing the bit offset between
714 * 0 and 7, inclusive.
715 *
716 * @exception IOException if an I/O error occurs.
717 *
718 * @see #setBitOffset
719 */
720 int getBitOffset() throws IOException;
721
722 /**
723 * Sets the bit offset to an integer between 0 and 7, inclusive.
724 * The byte offset within the stream, as returned by
725 * <code>getStreamPosition</code>, is left unchanged.
726 * A value of 0 indicates the
727 * most-significant bit, and a value of 7 indicates the least
728 * significant bit, of the byte being read.
729 *
730 * @param bitOffset the desired offset, as an <code>int</code>
731 * between 0 and 7, inclusive.
732 *
733 * @exception IllegalArgumentException if <code>bitOffset</code>
734 * is not between 0 and 7, inclusive.
735 * @exception IOException if an I/O error occurs.
736 *
737 * @see #getBitOffset
738 */
739 void setBitOffset(int bitOffset) throws IOException;
740
741 /**
742 * Reads a single bit from the stream and returns it as an
743 * <code>int</code> with the value <code>0</code> or
744 * <code>1</code>. The bit offset is advanced by one and reduced
745 * modulo 8.
746 *
747 * @return an <code>int</code> containing the value <code>0</code>
748 * or <code>1</code>.
749 *
750 * @exception EOFException if the stream reaches the end before
751 * reading all the bits.
752 * @exception IOException if an I/O error occurs.
753 */
754 int readBit() throws IOException;
755
756 /**
757 * Reads a bitstring from the stream and returns it as a
758 * <code>long</code>, with the first bit read becoming the most
759 * significant bit of the output. The read starts within the byte
760 * indicated by <code>getStreamPosition</code>, at the bit given
761 * by <code>getBitOffset</code>. The bit offset is advanced by
762 * <code>numBits</code> and reduced modulo 8.
763 *
764 * <p> The byte order of the stream has no effect on this
765 * method. The return value of this method is constructed as
766 * though the bits were read one at a time, and shifted into
767 * the right side of the return value, as shown by the following
768 * pseudo-code:
769 *
770 * <pre>
771 * long accum = 0L;
772 * for (int i = 0; i < numBits; i++) {
773 * accum <<= 1; // Shift left one bit to make room
774 * accum |= readBit();
775 * }
776 * </pre>
777 *
778 * Note that the result of <code>readBits(32)</code> may thus not
779 * be equal to that of <code>readInt()</code> if a reverse network
780 * byte order is being used (i.e., <code>getByteOrder() ==
781 * false</code>).
782 *
783 * <p> If the end of the stream is encountered before all the bits
784 * have been read, an <code>EOFException</code> is thrown.
785 *
786 * @param numBits the number of bits to read, as an <code>int</code>
787 * between 0 and 64, inclusive.
788 * @return the bitstring, as a <code>long</code> with the last bit
789 * read stored in the least significant bit.
790 *
791 * @exception IllegalArgumentException if <code>numBits</code>
792 * is not between 0 and 64, inclusive.
793 * @exception EOFException if the stream reaches the end before
794 * reading all the bits.
795 * @exception IOException if an I/O error occurs.
796 */
797 long readBits(int numBits) throws IOException;
798
799 /**
800 * Returns the total length of the stream, if known. Otherwise,
801 * <code>-1</code> is returned.
802 *
803 * @return a <code>long</code> containing the length of the
804 * stream, if known, or else <code>-1</code>.
805 *
806 * @exception IOException if an I/O error occurs.
807 */
808 long length() throws IOException;
809
810 /**
811 * Moves the stream position forward by a given number of bytes. It
812 * is possible that this method will only be able to skip forward
813 * by a smaller number of bytes than requested, for example if the
814 * end of the stream is reached. In all cases, the actual number
815 * of bytes skipped is returned. The bit offset is set to zero
816 * prior to advancing the position.
817 *
818 * @param n an <code>int</code> containing the number of bytes to
819 * be skipped.
820 *
821 * @return an <code>int</code> representing the number of bytes skipped.
822 *
823 * @exception IOException if an I/O error occurs.
824 */
825 int skipBytes(int n) throws IOException;
826
827 /**
828 * Moves the stream position forward by a given number of bytes.
829 * This method is identical to <code>skipBytes(int)</code> except
830 * that it allows for a larger skip distance.
831 *
832 * @param n a <code>long</code> containing the number of bytes to
833 * be skipped.
834 *
835 * @return a <code>long</code> representing the number of bytes
836 * skipped.
837 *
838 * @exception IOException if an I/O error occurs.
839 */
840 long skipBytes(long n) throws IOException;
841
842 /**
843 * Sets the current stream position to the desired location. The
844 * next read will occur at this location. The bit offset is set
845 * to 0.
846 *
847 * <p> An <code>IndexOutOfBoundsException</code> will be thrown if
848 * <code>pos</code> is smaller than the flushed position (as
849 * returned by <code>getflushedPosition</code>).
850 *
851 * <p> It is legal to seek past the end of the file; an
852 * <code>EOFException</code> will be thrown only if a read is
853 * performed.
854 *
855 * @param pos a <code>long</code> containing the desired file
856 * pointer position.
857 *
858 * @exception IndexOutOfBoundsException if <code>pos</code> is smaller
859 * than the flushed position.
860 * @exception IOException if any other I/O error occurs.
861 */
862 void seek(long pos) throws IOException;
863
864 /**
865 * Marks a position in the stream to be returned to by a
866 * subsequent call to <code>reset</code>. Unlike a standard
867 * <code>InputStream</code>, all <code>ImageInputStream</code>s
868 * support marking. Additionally, calls to <code>mark</code> and
869 * <code>reset</code> may be nested arbitrarily.
870 *
871 * <p> Unlike the <code>mark</code> methods declared by the
872 * <code>Reader</code> and <code>InputStream</code> interfaces, no
873 * <code>readLimit</code> parameter is used. An arbitrary amount
874 * of data may be read following the call to <code>mark</code>.
875 *
876 * <p> The bit position used by the <code>readBits</code> method
877 * is saved and restored by each pair of calls to
878 * <code>mark</code> and <code>reset</code>.
879 *
880 * <p> Note that it is valid for an <code>ImageReader</code> to call
881 * <code>flushBefore</code> as part of a read operation.
882 * Therefore, if an application calls <code>mark</code> prior to
883 * passing that stream to an <code>ImageReader</code>, the application
884 * should not assume that the marked position will remain valid after
885 * the read operation has completed.
886 */
887 void mark();
888
889 /**
890 * Returns the stream pointer to its previous position, including
891 * the bit offset, at the time of the most recent unmatched call
892 * to <code>mark</code>.
893 *
894 * <p> Calls to <code>reset</code> without a corresponding call
895 * to <code>mark</code> have no effect.
896 *
897 * <p> An <code>IOException</code> will be thrown if the previous
898 * marked position lies in the discarded portion of the stream.
899 *
900 * @exception IOException if an I/O error occurs.
901 */
902 void reset() throws IOException;
903
904 /**
905 * Discards the initial portion of the stream prior to the
906 * indicated postion. Attempting to seek to an offset within the
907 * flushed portion of the stream will result in an
908 * <code>IndexOutOfBoundsException</code>.
909 *
910 * <p> Calling <code>flushBefore</code> may allow classes
911 * implementing this interface to free up resources such as memory
912 * or disk space that are being used to store data from the
913 * stream.
914 *
915 * @param pos a <code>long</code> containing the length of the
916 * stream prefix that may be flushed.
917 *
918 * @exception IndexOutOfBoundsException if <code>pos</code> lies
919 * in the flushed portion of the stream or past the current stream
920 * position.
921 * @exception IOException if an I/O error occurs.
922 */
923 void flushBefore(long pos) throws IOException;
924
925 /**
926 * Discards the initial position of the stream prior to the current
927 * stream position. Equivalent to
928 * <code>flushBefore(getStreamPosition())</code>.
929 *
930 * @exception IOException if an I/O error occurs.
931 */
932 void flush() throws IOException;
933
934 /**
935 * Returns the earliest position in the stream to which seeking
936 * may be performed. The returned value will be the maximum of
937 * all values passed into previous calls to
938 * <code>flushBefore</code>.
939 *
940 * @return the earliest legal position for seeking, as a
941 * <code>long</code>.
942 */
943 long getFlushedPosition();
944
945 /**
946 * Returns <code>true</code> if this <code>ImageInputStream</code>
947 * caches data itself in order to allow seeking backwards.
948 * Applications may consult this in order to decide how frequently,
949 * or whether, to flush in order to conserve cache resources.
950 *
951 * @return <code>true</code> if this <code>ImageInputStream</code>
952 * caches data.
953 *
954 * @see #isCachedMemory
955 * @see #isCachedFile
956 */
957 boolean isCached();
958
959 /**
960 * Returns <code>true</code> if this <code>ImageInputStream</code>
961 * caches data itself in order to allow seeking backwards, and
962 * the cache is kept in main memory. Applications may consult
963 * this in order to decide how frequently, or whether, to flush
964 * in order to conserve cache resources.
965 *
966 * @return <code>true</code> if this <code>ImageInputStream</code>
967 * caches data in main memory.
968 *
969 * @see #isCached
970 * @see #isCachedFile
971 */
972 boolean isCachedMemory();
973
974 /**
975 * Returns <code>true</code> if this <code>ImageInputStream</code>
976 * caches data itself in order to allow seeking backwards, and
977 * the cache is kept in a temporary file. Applications may consult
978 * this in order to decide how frequently, or whether, to flush
979 * in order to conserve cache resources.
980 *
981 * @return <code>true</code> if this <code>ImageInputStream</code>
982 * caches data in a temporary file.
983 *
984 * @see #isCached
985 * @see #isCachedMemory
986 */
987 boolean isCachedFile();
988
989 /**
990 * Closes the stream. Attempts to access a stream that has been
991 * closed may result in <code>IOException</code>s or incorrect
992 * behavior. Calling this method may allow classes implementing
993 * this interface to release resources associated with the stream
994 * such as memory, disk space, or file descriptors.
995 *
996 * @exception IOException if an I/O error occurs.
997 */
998 void close() throws IOException;
999 }