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