1 /*
2 * Copyright (c) 1999, 2018, 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.Closeable;
29 import java.io.DataInput;
30 import java.io.IOException;
31 import java.nio.ByteOrder;
32
33 /**
34 * A seekable input stream interface for use by
35 * {@code ImageReader}s. Various input sources, such as
36 * {@code InputStream}s and {@code File}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} is
56 * used to specify the byte order. A value of
57 * {@code ByteOrder.BIG_ENDIAN} 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} order.
62 *
63 * <p> The byte order has no effect on the results returned from
64 * the {@code readBits} method (or the value written by
65 * {@code ImageOutputStream.writeBits}).
66 *
67 * @param byteOrder one of {@code ByteOrder.BIG_ENDIAN} or
68 * {@code java.nio.ByteOrder.LITTLE_ENDIAN}, 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} enumeration.
82 *
83 * @return one of {@code ByteOrder.BIG_ENDIAN} or
84 * {@code ByteOrder.LITTLE_ENDIAN}, 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} bytes from the stream, and
109 * stores them into {@code b} 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}
119 * to indicate EOF.
120 *
121 * @exception NullPointerException if {@code b} is
122 * {@code null}.
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} bytes from the stream, and stores
130 * them into {@code b} starting at index {@code off}.
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}
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} to write to.
140 * @param len the maximum number of {@code byte}s to read.
141 *
142 * @return the number of bytes actually read, or {@code -1}
143 * to indicate EOF.
144 *
145 * @exception NullPointerException if {@code b} is
146 * {@code null}.
147 * @exception IndexOutOfBoundsException if {@code off} is
148 * negative, {@code len} is negative, or {@code off + len}
149 * is greater than {@code b.length}.
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} bytes from the stream, and
156 * modifies the supplied {@code IIOByteBuffer} 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}.
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}s to read.
166 *
167 * @exception IndexOutOfBoundsException if {@code len} is
168 * negative.
169 * @exception NullPointerException if {@code buf} is
170 * {@code null}.
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}
178 * value of {@code true} if it is nonzero, {@code false}
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 java.io.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} value. Byte values between {@code 0x00}
194 * and {@code 0x7f} represent integer values between
195 * {@code 0} and {@code 127}. Values between
196 * {@code 0x80} and {@code 0xff} represent negative
197 * values from {@code -128} to {@code /1}.
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 java.io.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} in order to strip off
212 * any sign-extension bits, and returns it as a {@code byte}
213 * value.
214 *
215 * <p> Thus, byte values between {@code 0x00} and
216 * {@code 0x7f} are simply returned as integer values between
217 * {@code 0} and {@code 127}. Values between
218 * {@code 0x80} and {@code 0xff}, which normally
219 * represent negative {@code byte} values, will be mapped into
220 * positive integers between {@code 128} and
221 * {@code 255}.
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 java.io.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} 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 java.io.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}, masks it with
255 * {@code 0xffff} in order to strip off any sign-extension
256 * buts, and returns the result as an unsigned {@code int}
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 java.io.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}, except that the
274 * result is returned using the {@code char} 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 java.io.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}.
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 java.io.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} in order to
311 * strip off any sign-extension bits, and returns the result as an
312 * unsigned {@code long} 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 java.io.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}.
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 java.io.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}.
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 java.io.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}.
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 java.io.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}. 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} is returned. Otherwise, each byte
392 * that is read is converted to type {@code char} by
393 * zero-extension. If the character {@code '\n'} is
394 * encountered, it is discarded and reading ceases. If the
395 * character {@code '\r'} is encountered, it is discarded
396 * and, if the following byte converts to the character
397 * {@code '\n'}, then that is discarded also; reading then
398 * ceases. If end of file is encountered before either of the
399 * characters {@code '\n'} and {@code '\r'} is
400 * encountered, reading ceases. Once reading has ceased, a
401 * {@code String} 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}.
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.base/java/io/DataInput.html#modified-utf-8">
418 * modifiedUTF-8</a>
419 * format. The general contract of {@code readUTF} 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}.
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} 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} (where {@code x} means "may be
437 * {@code 0} or {@code 1}"), 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}, then the group consists of that byte
442 * {@code a} and a second byte {@code b}. If there is no
443 * byte {@code b} (because byte {@code a} was the last
444 * of the bytes to be read), or if byte {@code b} does not
445 * match the bit pattern {@code 10xxxxxx}, then a
446 * {@code UTFDataFormatException} is thrown. Otherwise, the
447 * group is converted to the character:
448 *
449 * <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}, then the group consists of that byte
455 * {@code a} and two more bytes {@code b} and
456 * {@code c}. If there is no byte {@code c} (because
457 * byte {@code a} was one of the last two of the bytes to be
458 * read), or either byte {@code b} or byte {@code c}
459 * does not match the bit pattern {@code 10xxxxxx}, then a
460 * {@code UTFDataFormatException} is thrown. Otherwise, the
461 * group is converted to the character:
462 *
463 * <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} or the pattern {@code 10xxxxxx},
469 * then a {@code UTFDataFormatException} is thrown.
470 *
471 * <p> If end of file is encountered at any time during this
472 * entire process, then a {@code java.io.EOFException} 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}, 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 java.io.EOFException if this stream reaches the end
492 * before reading all the bytes.
493 * @exception java.io.UTFDataFormatException if the bytes do not represent
494 * a 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} bytes from the stream, and stores them
501 * into {@code b} starting at index {@code off}.
502 * If the end of the stream is reached, a {@code java.io.EOFException}
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} to write to.
510 * @param len the maximum number of {@code byte}s to read.
511 *
512 * @exception IndexOutOfBoundsException if {@code off} is
513 * negative, {@code len} is negative, or {@code off + len}
514 * is greater than {@code b.length}.
515 * @exception NullPointerException if {@code b} is
516 * {@code null}.
517 * @exception java.io.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} bytes from the stream, and stores them
525 * into {@code b} starting at index {@code 0}.
526 * If the end of the stream is reached, a {@code java.io.EOFException}
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}s.
533 *
534 * @exception NullPointerException if {@code b} is
535 * {@code null}.
536 * @exception java.io.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} shorts (signed 16-bit integers) from the
544 * stream according to the current byte order, and
545 * stores them into {@code s} starting at index
546 * {@code off}. If the end of the stream is reached,
547 * a {@code java.io.EOFException} 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 within {@code s} to write to.
554 * @param len the maximum number of {@code short}s to read.
555 *
556 * @exception IndexOutOfBoundsException if {@code off} is
557 * negative, {@code len} is negative, or {@code off + len}
558 * is greater than {@code s.length}.
559 * @exception NullPointerException if {@code s} is
560 * {@code null}.
561 * @exception java.io.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} chars (unsigned 16-bit integers) from the
569 * stream according to the current byte order, and
570 * stores them into {@code c} starting at index
571 * {@code off}. If the end of the stream is reached,
572 * a {@code java.io.EOFException} 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 within {@code c} to write to.
579 * @param len the maximum number of {@code char}s to read.
580 *
581 * @exception IndexOutOfBoundsException if {@code off} is
582 * negative, {@code len} is negative, or {@code off + len}
583 * is greater than {@code c.length}.
584 * @exception NullPointerException if {@code c} is
585 * {@code null}.
586 * @exception java.io.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} ints (signed 32-bit integers) from the
594 * stream according to the current byte order, and
595 * stores them into {@code i} starting at index
596 * {@code off}. If the end of the stream is reached,
597 * a {@code java.io.EOFException} 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 within {@code i} to write to.
604 * @param len the maximum number of {@code int}s to read.
605 *
606 * @exception IndexOutOfBoundsException if {@code off} is
607 * negative, {@code len} is negative, or {@code off + len}
608 * is greater than {@code i.length}.
609 * @exception NullPointerException if {@code i} is
610 * {@code null}.
611 * @exception java.io.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} longs (signed 64-bit integers) from the
619 * stream according to the current byte order, and
620 * stores them into {@code l} starting at index
621 * {@code off}. If the end of the stream is reached,
622 * a {@code java.io.EOFException} 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 within {@code l} to write to.
629 * @param len the maximum number of {@code long}s to read.
630 *
631 * @exception IndexOutOfBoundsException if {@code off} is
632 * negative, {@code len} is negative, or {@code off + len}
633 * is greater than {@code l.length}.
634 * @exception NullPointerException if {@code l} is
635 * {@code null}.
636 * @exception java.io.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} floats (32-bit IEEE single-precision
644 * floats) from the stream according to the current byte order,
645 * and stores them into {@code f} starting at
646 * index {@code off}. If the end of the stream is reached,
647 * a {@code java.io.EOFException} 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 within {@code f} to write to.
654 * @param len the maximum number of {@code float}s to read.
655 *
656 * @exception IndexOutOfBoundsException if {@code off} is
657 * negative, {@code len} is negative, or {@code off + len}
658 * is greater than {@code f.length}.
659 * @exception NullPointerException if {@code f} is
660 * {@code null}.
661 * @exception java.io.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} doubles (64-bit IEEE double-precision
669 * floats) from the stream according to the current byte order,
670 * and stores them into {@code d} starting at
671 * index {@code off}. If the end of the stream is reached,
672 * a {@code java.io.EOFException} 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 within {@code d} to write to.
679 * @param len the maximum number of {@code double}s to read.
680 *
681 * @exception IndexOutOfBoundsException if {@code off} is
682 * negative, {@code len} is negative, or {@code off + len}
683 * is greater than {@code d.length}.
684 * @exception NullPointerException if {@code d} is
685 * {@code null}.
686 * @exception java.io.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} 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},
711 * {@code skipBytes}, or any {@code read} or
712 * {@code readFully} method.
713 *
714 * @return an {@code int} 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}, 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}
732 * between 0 and 7, inclusive.
733 *
734 * @exception IllegalArgumentException if {@code bitOffset}
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} with the value {@code 0} or
745 * {@code 1}. The bit offset is advanced by one and reduced
746 * modulo 8.
747 *
748 * @return an {@code int} containing the value {@code 0}
749 * or {@code 1}.
750 *
751 * @exception java.io.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}, 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}, at the bit given
762 * by {@code getBitOffset}. The bit offset is advanced by
763 * {@code numBits} 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>{@code
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)} may thus not
780 * be equal to that of {@code readInt()} if a reverse network
781 * byte order is being used (i.e., {@code getByteOrder() == false}).
782 *
783 * <p> If the end of the stream is encountered before all the bits
784 * have been read, a {@code java.io.EOFException} is thrown.
785 *
786 * @param numBits the number of bits to read, as an {@code int}
787 * between 0 and 64, inclusive.
788 * @return the bitstring, as a {@code long} with the last bit
789 * read stored in the least significant bit.
790 *
791 * @exception IllegalArgumentException if {@code numBits}
792 * is not between 0 and 64, inclusive.
793 * @exception java.io.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} is returned.
802 *
803 * @return a {@code long} containing the length of the
804 * stream, if known, or else {@code -1}.
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} containing the number of bytes to
819 * be skipped.
820 *
821 * @return an {@code int} 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)} except
830 * that it allows for a larger skip distance.
831 *
832 * @param n a {@code long} containing the number of bytes to
833 * be skipped.
834 *
835 * @return a {@code long} 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} will be thrown if
848 * {@code pos} is smaller than the flushed position (as
849 * returned by {@code getflushedPosition}).
850 *
851 * <p> It is legal to seek past the end of the file;
852 * a {@code java.io.EOFException} will be thrown only if a read is
853 * performed.
854 *
855 * @param pos a {@code long} containing the desired file
856 * pointer position.
857 *
858 * @exception IndexOutOfBoundsException if {@code pos} 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}. Unlike a standard
867 * {@code InputStream}, all {@code ImageInputStream}s
868 * support marking. Additionally, calls to {@code mark} and
869 * {@code reset} may be nested arbitrarily.
870 *
871 * <p> Unlike the {@code mark} methods declared by the
872 * {@code Reader} and {@code InputStream} interfaces, no
873 * {@code readLimit} parameter is used. An arbitrary amount
874 * of data may be read following the call to {@code mark}.
875 *
876 * <p> The bit position used by the {@code readBits} method
877 * is saved and restored by each pair of calls to
878 * {@code mark} and {@code reset}.
879 *
880 * <p> Note that it is valid for an {@code ImageReader} to call
881 * {@code flushBefore} as part of a read operation.
882 * Therefore, if an application calls {@code mark} prior to
883 * passing that stream to an {@code ImageReader}, 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}.
893 *
894 * <p> Calls to {@code reset} without a corresponding call
895 * to {@code mark} have no effect.
896 *
897 * <p> An {@code IOException} 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 position. Attempting to seek to an offset within the
907 * flushed portion of the stream will result in an
908 * {@code IndexOutOfBoundsException}.
909 *
910 * <p> Calling {@code flushBefore} 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} containing the length of the
916 * stream prefix that may be flushed.
917 *
918 * @exception IndexOutOfBoundsException if {@code pos} 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())}.
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}.
939 *
940 * @return the earliest legal position for seeking, as a
941 * {@code long}.
942 */
943 long getFlushedPosition();
944
945 /**
946 * Returns {@code true} if this {@code ImageInputStream}
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} if this {@code ImageInputStream}
952 * caches data.
953 *
954 * @see #isCachedMemory
955 * @see #isCachedFile
956 */
957 boolean isCached();
958
959 /**
960 * Returns {@code true} if this {@code ImageInputStream}
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} if this {@code ImageInputStream}
967 * caches data in main memory.
968 *
969 * @see #isCached
970 * @see #isCachedFile
971 */
972 boolean isCachedMemory();
973
974 /**
975 * Returns {@code true} if this {@code ImageInputStream}
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} if this {@code ImageInputStream}
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}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 }