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&#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 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&#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}