old-autovect-branch/libjava/classpath/javax/imageio/stream/ImageInputStream.java

   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 }