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.EOFException;
  43: import java.io.IOException;
  44: import java.nio.ByteOrder;
  45: 
  46: 
  47: /**
  48:  * An input stream for use by {@link javax.imageio.ImageReader
  49:  * ImageReaders}.
  50:  *
  51:  * @since 1.4
  52:  *
  53:  * @author Sascha Brawer (brawer@dandelis.ch)
  54:  */
  55: public interface ImageInputStream
  56:   extends DataInput
  57: {
  58:   void setByteOrder(ByteOrder order);
  59: 
  60:   ByteOrder getByteOrder();
  61:   
  62:   int read()
  63:     throws IOException;
  64: 
  65:   int read(byte[] b)
  66:     throws IOException;
  67: 
  68:   int read(byte[] b, int offset, int length)
  69:     throws IOException;
  70: 
  71: 
  72:   /**
  73:    * Reads up to a specified number of bytes, and modifies a
  74:    * {@link IIOByteBuffer} to hold the read data.
  75:    *
  76:    * <p>The {@linkplain #getBitOffset() bit offset} is set to zero
  77:    * before any data is read.
  78:    *
  79:    * @param buf an <code>IIOByteBuffer</code> that will hold the read
  80:    * data.
  81:    *
  82:    * @param numBytes the maximum number of bytes to read.
  83:    *
  84:    * @throws IndexOutOfBoundsException if <code>numBytes</code> is
  85:    * negative.
  86:    *
  87:    * @throws NullPointerException if <code>buf</code> is
  88:    * <code>null</code>.
  89:    *
  90:    * @throws IOException if some general problem happens with
  91:    * accessing data.
  92:    */
  93:   void readBytes(IIOByteBuffer buf, int numBytes)
  94:     throws IOException;
  95: 
  96: 
  97:   /**
  98:    * Reads a byte and checks whether or not its value is zero.
  99:    *
 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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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 numLongs 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&#x2019;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&#x2019;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&#x2019;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: }