1/* 2 * Copyright (c) 1999, 2013, 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 26package javax.imageio.stream; 27 28import java.io.Closeable; 29import java.io.DataInput; 30import java.io.IOException; 31import 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 */ 46public 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/io/DataInput.html#modified-utf-8">modified 418 * UTF-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} 1000