Source for javax.imageio.stream.ImageInputStream

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