001/* ImageInputStream.java 002 Copyright (C) 2004, 2005 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package javax.imageio.stream; 040 041import java.io.DataInput; 042import java.io.EOFException; 043import java.io.IOException; 044import java.nio.ByteOrder; 045 046 047/** 048 * An input stream for use by {@link javax.imageio.ImageReader 049 * ImageReaders}. 050 * 051 * @since 1.4 052 * 053 * @author Sascha Brawer (brawer@dandelis.ch) 054 */ 055public interface ImageInputStream 056 extends DataInput 057{ 058 void setByteOrder(ByteOrder order); 059 060 ByteOrder getByteOrder(); 061 062 int read() 063 throws IOException; 064 065 int read(byte[] b) 066 throws IOException; 067 068 int read(byte[] b, int offset, int length) 069 throws IOException; 070 071 072 /** 073 * Reads up to a specified number of bytes, and modifies a 074 * {@link IIOByteBuffer} to hold the read data. 075 * 076 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 077 * before any data is read. 078 * 079 * @param buf an <code>IIOByteBuffer</code> that will hold the read 080 * data. 081 * 082 * @param numBytes the maximum number of bytes to read. 083 * 084 * @throws IndexOutOfBoundsException if <code>numBytes</code> is 085 * negative. 086 * 087 * @throws NullPointerException if <code>buf</code> is 088 * <code>null</code>. 089 * 090 * @throws IOException if some general problem happens with 091 * accessing data. 092 */ 093 void readBytes(IIOByteBuffer buf, int numBytes) 094 throws IOException; 095 096 097 /** 098 * Reads a byte and checks whether or not its value is zero. 099 * 100 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 101 * before the byte is read. 102 * 103 * @throws EOFException if the input stream is at its end. 104 * 105 * @throws IOException if some general problem happens with 106 * accessing data. 107 * 108 * @see #readBit() 109 * @see #readByte() 110 * @see #readFully(byte[], int, int) 111 */ 112 boolean readBoolean() 113 throws IOException; 114 115 116 /** 117 * Reads a signed byte. 118 * 119 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 120 * before any data is read. 121 * 122 * @throws EOFException if the input stream is at its end. 123 * 124 * @throws IOException if some general problem happens with 125 * accessing data. 126 * 127 * @see #readUnsignedByte() 128 * @see #readFully(byte[], int, int) 129 */ 130 byte readByte() 131 throws IOException; 132 133 134 /** 135 * Reads an unsigned byte. 136 * 137 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 138 * before any data is read. 139 * 140 * @throws EOFException if the input stream is at its end. 141 * 142 * @throws IOException if some general problem happens with 143 * accessing data. 144 * 145 * @see #readByte() 146 * @see #readFully(byte[], int, int) 147 */ 148 int readUnsignedByte() 149 throws IOException; 150 151 152 /** 153 * Reads an signed 16-bit integer. If necessary, the value gets 154 * converted from the stream’s {@linkplain #getByteOrder() 155 * current byte order}. 156 * 157 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 158 * before any data is read. 159 * 160 * @throws EOFException if the input stream ends before all two 161 * bytes were read. 162 * 163 * @throws IOException if some general problem happens with 164 * accessing data. 165 * 166 * @see #readUnsignedShort() 167 * @see #readChar() 168 * @see #readFully(short[], int, int) 169 */ 170 short readShort() 171 throws IOException; 172 173 174 /** 175 * Reads an unsigned 16-bit integer. If necessary, the value gets 176 * converted from the stream’s {@linkplain #getByteOrder() 177 * current byte order}. 178 * 179 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 180 * before any data is read. 181 * 182 * <p>This method does the same as {@link #readChar()}. 183 * 184 * @throws EOFException if the input stream ends before all two 185 * bytes were read. 186 * 187 * @throws IOException if some general problem happens with 188 * accessing data. 189 * 190 * @see #readShort() 191 * @see #readChar() 192 * @see #readFully(char[], int, int) 193 */ 194 int readUnsignedShort() 195 throws IOException; 196 197 198 /** 199 * Reads an unsigned 16-bit integer. If necessary, the value gets 200 * converted from the stream’s {@linkplain #getByteOrder() 201 * current byte order}. 202 * 203 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 204 * before any data is read. 205 * 206 * <p>This method does the same as {@link #readUnsignedShort()}. 207 * 208 * @throws EOFException if the input stream ends before all two 209 * bytes were read. 210 * 211 * @throws IOException if some general problem happens with 212 * accessing data. 213 * 214 * @see #readFully(char[], int, int) 215 */ 216 char readChar() 217 throws IOException; 218 219 220 /** 221 * Reads a signed 32-bit integer. If necessary, the value gets 222 * converted from the stream’s {@linkplain #getByteOrder() 223 * current byte order}. 224 * 225 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 226 * before any data is read. 227 * 228 * @throws EOFException if the input stream ends before all four 229 * bytes were read. 230 * 231 * @throws IOException if some general problem happens with 232 * accessing data. 233 * 234 * @see #readUnsignedInt() 235 * @see #readFully(int[], int, int) 236 */ 237 int readInt() 238 throws IOException; 239 240 241 /** 242 * Reads an unsigned 32-bit integer. If necessary, the value gets 243 * converted from the stream’s {@linkplain #getByteOrder() 244 * current byte order}. 245 * 246 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 247 * before any data is read. 248 * 249 * @throws EOFException if the input stream ends before all four 250 * bytes were read. 251 * 252 * @throws IOException if some general problem happens with 253 * accessing data. 254 * 255 * @see #readInt() 256 * @see #readFully(int[], int, int) 257 */ 258 long readUnsignedInt() 259 throws IOException; 260 261 262 /** 263 * Reads a signed 64-bit integer. If necessary, the value gets 264 * converted from the stream’s {@linkplain #getByteOrder() 265 * current byte order}. 266 * 267 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 268 * before any data is read. 269 * 270 * @throws EOFException if the input stream ends before all eight 271 * bytes were read. 272 * 273 * @throws IOException if some general problem happens with 274 * accessing data. 275 * 276 * @see #readFully(long[], int, int) 277 */ 278 long readLong() 279 throws IOException; 280 281 282 /** 283 * Reads an IEEE 32-bit single-precision floating point number. If 284 * necessary, the value gets converted from the stream’s 285 * {@linkplain #getByteOrder() current byte order}. 286 * 287 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 288 * before any data is read. 289 * 290 * @throws EOFException if the input stream ends before all four 291 * bytes were read. 292 * 293 * @throws IOException if some general problem happens with 294 * accessing data. 295 * 296 * @see #readFully(float[], int, int) 297 */ 298 float readFloat() 299 throws IOException; 300 301 302 /** 303 * Reads an IEEE 64-bit double-precision floating point number. If 304 * necessary, the value gets converted from the stream’s 305 * {@linkplain #getByteOrder() current byte order}. 306 * 307 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 308 * before any data is read. 309 * 310 * @throws EOFException if the input stream ends before all eight 311 * bytes were read. 312 * 313 * @throws IOException if some general problem happens with 314 * accessing data. 315 * 316 * @see #readFully(double[], int, int) 317 */ 318 double readDouble() 319 throws IOException; 320 321 String readLine() 322 throws IOException; 323 324 String readUTF() 325 throws IOException; 326 327 328 /** 329 * Reads a sequence of signed 8-bit integers into a 330 * <code>byte[]</code> array. 331 * 332 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 333 * before any data is read. 334 * 335 * @param b an array for storing the read values. 336 * 337 * @param offset the index of the first element in <code>b</code> 338 * that will hold read data. 339 * 340 * @param numBytes the number of bytes to read. 341 * 342 * @throws IndexOutOfBoundsException if <code>offset</code> or 343 * <code>numBytes</code> is negative, or if <code>offset + 344 * numBytes</code> exceeds <code>b.length</code>. 345 * 346 * @throws NullPointerException if <code>b</code> is 347 * <code>null</code>. 348 * 349 * @throws EOFException if the input stream ends before all content 350 * was read. 351 * 352 * @throws IOException if some general problem happens with 353 * accessing data. 354 * 355 * @see #readByte() 356 */ 357 void readFully(byte[] b, int offset, int numBytes) 358 throws IOException; 359 360 361 /** 362 * Reads a sequence of signed 8-bit integers into a 363 * <code>byte[]</code> array. 364 * 365 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 366 * before any data is read. 367 * 368 * @param b an array for storing the read values. 369 * 370 * @throws NullPointerException if <code>b</code> is 371 * <code>null</code>. 372 * 373 * @throws EOFException if the input stream ends before all content 374 * was read. 375 * 376 * @throws IOException if some general problem happens with 377 * accessing data. 378 * 379 * @see #readByte() 380 * @see #readFully(byte[], int, int) 381 */ 382 void readFully(byte[] b) 383 throws IOException; 384 385 386 /** 387 * Reads a sequence of signed 16-bit integers into a 388 * <code>short[]</code> array. If necessary, values are converted 389 * from the stream’s {@linkplain #getByteOrder() current byte 390 * order}. 391 * 392 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 393 * before any data is read. 394 * 395 * @param s an array for storing the read values. 396 * 397 * @param offset the index of the first element in <code>s</code> 398 * that will hold read data. 399 * 400 * @param numShorts the number of signed 16-bit integers to read 401 * (which is one half of the number of bytes). 402 * 403 * @throws IndexOutOfBoundsException if <code>offset</code> or 404 * <code>numShorts</code> is negative, or if <code>offset + 405 * numShorts</code> exceeds <code>s.length</code>. 406 * 407 * @throws NullPointerException if <code>s</code> is 408 * <code>null</code>. 409 * 410 * @throws EOFException if the input stream ends before all content 411 * was read. 412 * 413 * @throws IOException if some general problem happens with 414 * accessing data. 415 * 416 * @see #readShort() 417 */ 418 void readFully(short[] s, int offset, int numShorts) 419 throws IOException; 420 421 422 /** 423 * Reads a sequence of unsigned 16-bit integers into a 424 * <code>char[]</code> array. If necessary, values are converted 425 * from the stream’s {@linkplain #getByteOrder() current byte 426 * order}. 427 * 428 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 429 * before any data is read. 430 * 431 * @param c an array for storing the read values. 432 * 433 * @param offset the index of the first element in <code>c</code> 434 * that will hold read data. 435 * 436 * @param numChars the number of unsigned 16-bit integers to read 437 * (which is one half of the number of bytes). 438 * 439 * @throws IndexOutOfBoundsException if <code>offset</code> or 440 * <code>numChars</code> is negative, or if <code>offset + 441 * numChars</code> exceeds <code>c.length</code>. 442 * 443 * @throws NullPointerException if <code>c</code> is 444 * <code>null</code>. 445 * 446 * @throws EOFException if the input stream ends before all content 447 * was read. 448 * 449 * @throws IOException if some general problem happens with 450 * accessing data. 451 * 452 * @see #readChar() 453 */ 454 void readFully(char[] c, int offset, int numChars) 455 throws IOException; 456 457 458 /** 459 * Reads a sequence of signed 32-bit integers into a 460 * <code>long[]</code> array. If necessary, values are converted 461 * from the stream’s {@linkplain #getByteOrder() current byte 462 * order}. 463 * 464 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 465 * before any data is read. 466 * 467 * @param i an array for storing the read values. 468 * 469 * @param offset the index of the first element in <code>i</code> 470 * that will hold read data. 471 * 472 * @param numInts the number of signed 32-bit integers to read 473 * (which is one fourth of the number of bytes). 474 * 475 * @throws IndexOutOfBoundsException if <code>offset</code> or 476 * <code>numInts</code> is negative, or if <code>offset + 477 * numInts</code> exceeds <code>i.length</code>. 478 * 479 * @throws NullPointerException if <code>i</code> is 480 * <code>null</code>. 481 * 482 * @throws EOFException if the input stream ends before all content 483 * was read. 484 * 485 * @throws IOException if some general problem happens with 486 * accessing data. 487 * 488 * @see #readInt() 489 */ 490 void readFully(int[] i, int offset, int numInts) 491 throws IOException; 492 493 494 /** 495 * Reads a sequence of signed 64-bit integers into a 496 * <code>long[]</code> array. If necessary, values are converted 497 * from the stream’s {@linkplain #getByteOrder() current byte 498 * order}. 499 * 500 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 501 * before any data is read. 502 * 503 * @param l an array for storing the read values. 504 * 505 * @param offset the index of the first element in <code>l</code> 506 * that will hold read data. 507 * 508 * @param numLongs the number of signed 64-bit integers to read 509 * (which is one eight of the number of bytes). 510 * 511 * @throws IndexOutOfBoundsException if <code>offset</code> or 512 * <code>numLongs</code> is negative, or if <code>offset + 513 * numLongs</code> exceeds <code>l.length</code>. 514 * 515 * @throws NullPointerException if <code>l</code> is 516 * <code>null</code>. 517 * 518 * @throws EOFException if the input stream ends before all content 519 * was read. 520 * 521 * @throws IOException if some general problem happens with 522 * accessing data. 523 * 524 * @see #readLong() 525 */ 526 void readFully(long[] l, int offset, int numLongs) 527 throws IOException; 528 529 530 /** 531 * Reads a sequence of IEEE 32-bit single-precision floating point 532 * numbers into a <code>float[]</code> array. If necessary, values 533 * are converted from the stream’s {@linkplain 534 * #getByteOrder() current byte order}. 535 * 536 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 537 * before any data is read. 538 * 539 * @param d an array for storing the read values. 540 * 541 * @param offset the index of the first element in <code>d</code> 542 * that will hold read data. 543 * 544 * @param numFloats the number of IEEE 32-bit single-precision 545 * floating point numbers to read (which is one fourth of the number 546 * of bytes). 547 * 548 * @throws IndexOutOfBoundsException if <code>offset</code> or 549 * <code>numFloats</code> is negative, or if <code>offset + 550 * numFloats</code> exceeds <code>f.length</code>. 551 * 552 * @throws NullPointerException if <code>f</code> is 553 * <code>null</code>. 554 * 555 * @throws EOFException if the input stream ends before all content 556 * was read. 557 * 558 * @throws IOException if some general problem happens with 559 * accessing data. 560 * 561 * @see #readFloat() 562 */ 563 void readFully(float[] f, int offset, int numFloats) 564 throws IOException; 565 566 567 /** 568 * Reads a sequence of IEEE 64-bit double-precision floating point 569 * numbers into a <code>double[]</code> array. If necessary, values 570 * are converted from the stream’s {@linkplain 571 * #getByteOrder() current byte order}. 572 * 573 * <p>The {@linkplain #getBitOffset() bit offset} is set to zero 574 * before any data is read. 575 * 576 * @param d an array for storing the read values. 577 * 578 * @param offset the index of the first element in <code>d</code> 579 * that will hold read data. 580 * 581 * @param numDoubles the number of IEEE 64-bit double-precision 582 * floating point numbers to read (which is one eight of the number 583 * of bytes). 584 * 585 * @throws IndexOutOfBoundsException if <code>offset</code> or 586 * <code>numDoubles</code> is negative, or if <code>offset + 587 * numDoubles</code> exceeds <code>d.length</code>. 588 * 589 * @throws NullPointerException if <code>d</code> is 590 * <code>null</code>. 591 * 592 * @throws EOFException if the input stream ends before all content 593 * was read. 594 * 595 * @throws IOException if some general problem happens with 596 * accessing data. 597 * 598 * @see #readDouble() 599 */ 600 void readFully(double[] d, int offset, int numDoubles) 601 throws IOException; 602 603 long getStreamPosition() 604 throws IOException; 605 606 int getBitOffset() 607 throws IOException; 608 609 void setBitOffset(int bitOffset) 610 throws IOException; 611 612 int readBit() 613 throws IOException; 614 615 long readBits(int numBits) 616 throws IOException; 617 618 long length() 619 throws IOException; 620 621 int skipBytes(int numBytes) 622 throws IOException; 623 624 long skipBytes(long numBytes) 625 throws IOException; 626 627 void seek(long pos) 628 throws IOException; 629 630 void mark(); 631 632 void reset() 633 throws IOException; 634 635 void flushBefore(long pos) 636 throws IOException; 637 638 void flush() 639 throws IOException; 640 641 long getFlushedPosition(); 642 643 boolean isCached(); 644 645 boolean isCachedMemory(); 646 647 boolean isCachedFile(); 648 649 void close() 650 throws IOException; 651}