001    /* ImageInputStream.java
002       Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.imageio.stream;
040    
041    import java.io.DataInput;
042    import java.io.EOFException;
043    import java.io.IOException;
044    import 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     */
055    public 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    }