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’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’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’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’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’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’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’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’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’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’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’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’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’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’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 }