History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/imageio/stream/ImageInputStream.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/imageio/stream/ImageInputStream.java+1000−0
@@ -0,0 +1,1000 @@
1+/*
2+ * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.imageio.stream;
27+
28+import java.io.Closeable;
29+import java.io.DataInput;
30+import java.io.IOException;
31+import java.nio.ByteOrder;
32+
33+/**
34+ * A seekable input stream interface for use by
35+ * <code>ImageReader</code>s. Various input sources, such as
36+ * <code>InputStream</code>s and <code>File</code>s,
37+ * as well as future fast I/O sources may be "wrapped" by a suitable
38+ * implementation of this interface for use by the Image I/O API.
39+ *
40+ * @see ImageInputStreamImpl
41+ * @see FileImageInputStream
42+ * @see FileCacheImageInputStream
43+ * @see MemoryCacheImageInputStream
44+ *
45+ */
46+public interface ImageInputStream extends DataInput, Closeable {
47+
48+ /**
49+ * Sets the desired byte order for future reads of data values
50+ * from this stream. For example, the sequence of bytes '0x01
51+ * 0x02 0x03 0x04' if read as a 4-byte integer would have the
52+ * value '0x01020304' using network byte order and the value
53+ * '0x04030201' under the reverse byte order.
54+ *
55+ * <p> The enumeration class <code>java.nio.ByteOrder</code> is
56+ * used to specify the byte order. A value of
57+ * <code>ByteOrder.BIG_ENDIAN</code> specifies so-called
58+ * big-endian or network byte order, in which the high-order byte
59+ * comes first. Motorola and Sparc processors store data in this
60+ * format, while Intel processors store data in the reverse
61+ * <code>ByteOrder.LITTLE_ENDIAN</code> order.
62+ *
63+ * <p> The byte order has no effect on the results returned from
64+ * the <code>readBits</code> method (or the value written by
65+ * <code>ImageOutputStream.writeBits</code>).
66+ *
67+ * @param byteOrder one of <code>ByteOrder.BIG_ENDIAN</code> or
68+ * <code>java.nio.ByteOrder.LITTLE_ENDIAN</code>, indicating whether
69+ * network byte order or its reverse will be used for future
70+ * reads.
71+ *
72+ * @see java.nio.ByteOrder
73+ * @see #getByteOrder
74+ * @see #readBits(int)
75+ */
76+ void setByteOrder(ByteOrder byteOrder);
77+
78+ /**
79+ * Returns the byte order with which data values will be read from
80+ * this stream as an instance of the
81+ * <code>java.nio.ByteOrder</code> enumeration.
82+ *
83+ * @return one of <code>ByteOrder.BIG_ENDIAN</code> or
84+ * <code>ByteOrder.LITTLE_ENDIAN</code>, indicating which byte
85+ * order is being used.
86+ *
87+ * @see java.nio.ByteOrder
88+ * @see #setByteOrder
89+ */
90+ ByteOrder getByteOrder();
91+
92+ /**
93+ * Reads a single byte from the stream and returns it as an
94+ * integer between 0 and 255. If the end of the stream is
95+ * reached, -1 is returned.
96+ *
97+ * <p> The bit offset within the stream is reset to zero before
98+ * the read occurs.
99+ *
100+ * @return a byte value from the stream, as an int, or -1 to
101+ * indicate EOF.
102+ *
103+ * @exception IOException if an I/O error occurs.
104+ */
105+ int read() throws IOException;
106+
107+ /**
108+ * Reads up to <code>b.length</code> bytes from the stream, and
109+ * stores them into <code>b</code> starting at index 0. The
110+ * number of bytes read is returned. If no bytes can be read
111+ * because the end of the stream has been reached, -1 is returned.
112+ *
113+ * <p> The bit offset within the stream is reset to zero before
114+ * the read occurs.
115+ *
116+ * @param b an array of bytes to be written to.
117+ *
118+ * @return the number of bytes actually read, or <code>-1</code>
119+ * to indicate EOF.
120+ *
121+ * @exception NullPointerException if <code>b</code> is
122+ * <code>null</code>.
123+ *
124+ * @exception IOException if an I/O error occurs.
125+ */
126+ int read(byte[] b) throws IOException;
127+
128+ /**
129+ * Reads up to <code>len</code> bytes from the stream, and stores
130+ * them into <code>b</code> starting at index <code>off</code>.
131+ * The number of bytes read is returned. If no bytes can be read
132+ * because the end of the stream has been reached, <code>-1</code>
133+ * is returned.
134+ *
135+ * <p> The bit offset within the stream is reset to zero before
136+ * the read occurs.
137+ *
138+ * @param b an array of bytes to be written to.
139+ * @param off the starting position within <code>b</code> to write to.
140+ * @param len the maximum number of <code>byte</code>s to read.
141+ *
142+ * @return the number of bytes actually read, or <code>-1</code>
143+ * to indicate EOF.
144+ *
145+ * @exception NullPointerException if <code>b</code> is
146+ * <code>null</code>.
147+ * @exception IndexOutOfBoundsException if <code>off</code> is
148+ * negative, <code>len</code> is negative, or <code>off +
149+ * len</code> is greater than <code>b.length</code>.
150+ * @exception IOException if an I/O error occurs.
151+ */
152+ int read(byte[] b, int off, int len) throws IOException;
153+
154+ /**
155+ * Reads up to <code>len</code> bytes from the stream, and
156+ * modifies the supplied <code>IIOByteBuffer</code> to indicate
157+ * the byte array, offset, and length where the data may be found.
158+ * The caller should not attempt to modify the data found in the
159+ * <code>IIOByteBuffer</code>.
160+ *
161+ * <p> The bit offset within the stream is reset to zero before
162+ * the read occurs.
163+ *
164+ * @param buf an IIOByteBuffer object to be modified.
165+ * @param len the maximum number of <code>byte</code>s to read.
166+ *
167+ * @exception IndexOutOfBoundsException if <code>len</code> is
168+ * negative.
169+ * @exception NullPointerException if <code>buf</code> is
170+ * <code>null</code>.
171+ *
172+ * @exception IOException if an I/O error occurs.
173+ */
174+ void readBytes(IIOByteBuffer buf, int len) throws IOException;
175+
176+ /**
177+ * Reads a byte from the stream and returns a <code>boolean</code>
178+ * value of <code>true</code> if it is nonzero, <code>false</code>
179+ * if it is zero.
180+ *
181+ * <p> The bit offset within the stream is reset to zero before
182+ * the read occurs.
183+ *
184+ * @return a boolean value from the stream.
185+ *
186+ * @exception EOFException if the end of the stream is reached.
187+ * @exception IOException if an I/O error occurs.
188+ */
189+ boolean readBoolean() throws IOException;
190+
191+ /**
192+ * Reads a byte from the stream and returns it as a
193+ * <code>byte</code> value. Byte values between <code>0x00</code>
194+ * and <code>0x7f</code> represent integer values between
195+ * <code>0</code> and <code>127</code>. Values between
196+ * <code>0x80</code> and <code>0xff</code> represent negative
197+ * values from <code>-128</code> to <code>/1</code>.
198+ *
199+ * <p> The bit offset within the stream is reset to zero before
200+ * the read occurs.
201+ *
202+ * @return a signed byte value from the stream.
203+ *
204+ * @exception EOFException if the end of the stream is reached.
205+ * @exception IOException if an I/O error occurs.
206+ */
207+ byte readByte() throws IOException;
208+
209+ /**
210+ * Reads a byte from the stream, and (conceptually) converts it to
211+ * an int, masks it with <code>0xff</code> in order to strip off
212+ * any sign-extension bits, and returns it as a <code>byte</code>
213+ * value.
214+ *
215+ * <p> Thus, byte values between <code>0x00</code> and
216+ * <code>0x7f</code> are simply returned as integer values between
217+ * <code>0</code> and <code>127</code>. Values between
218+ * <code>0x80</code> and <code>0xff</code>, which normally
219+ * represent negative <code>byte</code>values, will be mapped into
220+ * positive integers between <code>128</code> and
221+ * <code>255</code>.
222+ *
223+ * <p> The bit offset within the stream is reset to zero before
224+ * the read occurs.
225+ *
226+ * @return an unsigned byte value from the stream.
227+ *
228+ * @exception EOFException if the end of the stream is reached.
229+ * @exception IOException if an I/O error occurs.
230+ */
231+ int readUnsignedByte() throws IOException;
232+
233+ /**
234+ * Reads two bytes from the stream, and (conceptually)
235+ * concatenates them according to the current byte order, and
236+ * returns the result as a <code>short</code> value.
237+ *
238+ * <p> The bit offset within the stream is reset to zero before
239+ * the read occurs.
240+ *
241+ * @return a signed short value from the stream.
242+ *
243+ * @exception EOFException if the stream reaches the end before
244+ * reading all the bytes.
245+ * @exception IOException if an I/O error occurs.
246+ *
247+ * @see #getByteOrder
248+ */
249+ short readShort() throws IOException;
250+
251+ /**
252+ * Reads two bytes from the stream, and (conceptually)
253+ * concatenates them according to the current byte order, converts
254+ * the resulting value to an <code>int</code>, masks it with
255+ * <code>0xffff</code> in order to strip off any sign-extension
256+ * buts, and returns the result as an unsigned <code>int</code>
257+ * value.
258+ *
259+ * <p> The bit offset within the stream is reset to zero before
260+ * the read occurs.
261+ *
262+ * @return an unsigned short value from the stream, as an int.
263+ *
264+ * @exception EOFException if the stream reaches the end before
265+ * reading all the bytes.
266+ * @exception IOException if an I/O error occurs.
267+ *
268+ * @see #getByteOrder
269+ */
270+ int readUnsignedShort() throws IOException;
271+
272+ /**
273+ * Equivalent to <code>readUnsignedShort</code>, except that the
274+ * result is returned using the <code>char</code> datatype.
275+ *
276+ * <p> The bit offset within the stream is reset to zero before
277+ * the read occurs.
278+ *
279+ * @return an unsigned char value from the stream.
280+ *
281+ * @exception EOFException if the stream reaches the end before
282+ * reading all the bytes.
283+ * @exception IOException if an I/O error occurs.
284+ *
285+ * @see #readUnsignedShort
286+ */
287+ char readChar() throws IOException;
288+
289+ /**
290+ * Reads 4 bytes from the stream, and (conceptually) concatenates
291+ * them according to the current byte order and returns the result
292+ * as an <code>int</code>.
293+ *
294+ * <p> The bit offset within the stream is ignored and treated as
295+ * though it were zero.
296+ *
297+ * @return a signed int value from the stream.
298+ *
299+ * @exception EOFException if the stream reaches the end before
300+ * reading all the bytes.
301+ * @exception IOException if an I/O error occurs.
302+ *
303+ * @see #getByteOrder
304+ */
305+ int readInt() throws IOException;
306+
307+ /**
308+ * Reads 4 bytes from the stream, and (conceptually) concatenates
309+ * them according to the current byte order, converts the result
310+ * to a long, masks it with <code>0xffffffffL</code> in order to
311+ * strip off any sign-extension bits, and returns the result as an
312+ * unsigned <code>long</code> value.
313+ *
314+ * <p> The bit offset within the stream is reset to zero before
315+ * the read occurs.
316+ *
317+ * @return an unsigned int value from the stream, as a long.
318+ *
319+ * @exception EOFException if the stream reaches the end before
320+ * reading all the bytes.
321+ * @exception IOException if an I/O error occurs.
322+ *
323+ * @see #getByteOrder
324+ */
325+ long readUnsignedInt() throws IOException;
326+
327+ /**
328+ * Reads 8 bytes from the stream, and (conceptually) concatenates
329+ * them according to the current byte order and returns the result
330+ * as a <code>long</code>.
331+ *
332+ * <p> The bit offset within the stream is reset to zero before
333+ * the read occurs.
334+ *
335+ * @return a signed long value from the stream.
336+ *
337+ * @exception EOFException if the stream reaches the end before
338+ * reading all the bytes.
339+ * @exception IOException if an I/O error occurs.
340+ *
341+ * @see #getByteOrder
342+ */
343+ long readLong() throws IOException;
344+
345+ /**
346+ * Reads 4 bytes from the stream, and (conceptually) concatenates
347+ * them according to the current byte order and returns the result
348+ * as a <code>float</code>.
349+ *
350+ * <p> The bit offset within the stream is reset to zero before
351+ * the read occurs.
352+ *
353+ * @return a float value from the stream.
354+ *
355+ * @exception EOFException if the stream reaches the end before
356+ * reading all the bytes.
357+ * @exception IOException if an I/O error occurs.
358+ *
359+ * @see #getByteOrder
360+ */
361+ float readFloat() throws IOException;
362+
363+ /**
364+ * Reads 8 bytes from the stream, and (conceptually) concatenates
365+ * them according to the current byte order and returns the result
366+ * as a <code>double</code>.
367+ *
368+ * <p> The bit offset within the stream is reset to zero before
369+ * the read occurs.
370+ *
371+ * @return a double value from the stream.
372+ *
373+ * @exception EOFException if the stream reaches the end before
374+ * reading all the bytes.
375+ * @exception IOException if an I/O error occurs.
376+ *
377+ * @see #getByteOrder
378+ */
379+ double readDouble() throws IOException;
380+
381+ /**
382+ * Reads the next line of text from the input stream. It reads
383+ * successive bytes, converting each byte separately into a
384+ * character, until it encounters a line terminator or end of
385+ * file; the characters read are then returned as a
386+ * <code>String</code>. Note that because this method processes
387+ * bytes, it does not support input of the full Unicode character
388+ * set.
389+ *
390+ * <p> If end of file is encountered before even one byte can be
391+ * read, then <code>null</code> is returned. Otherwise, each byte
392+ * that is read is converted to type <code>char</code> by
393+ * zero-extension. If the character <code>'\n'</code> is
394+ * encountered, it is discarded and reading ceases. If the
395+ * character <code>'\r'</code> is encountered, it is discarded
396+ * and, if the following byte converts &#32;to the character
397+ * <code>'\n'</code>, then that is discarded also; reading then
398+ * ceases. If end of file is encountered before either of the
399+ * characters <code>'\n'</code> and <code>'\r'</code> is
400+ * encountered, reading ceases. Once reading has ceased, a
401+ * <code>String</code> is returned that contains all the
402+ * characters read and not discarded, taken in order. Note that
403+ * every character in this string will have a value less than
404+ * <code>&#92;u0100</code>, that is, <code>(char)256</code>.
405+ *
406+ * <p> The bit offset within the stream is reset to zero before
407+ * the read occurs.
408+ *
409+ * @return a String containing a line of text from the stream.
410+ *
411+ * @exception IOException if an I/O error occurs.
412+ */
413+ String readLine() throws IOException;
414+
415+ /**
416+ * Reads in a string that has been encoded using a
417+ * <a href="../../../java/io/DataInput.html#modified-utf-8">modified
418+ * UTF-8</a>
419+ * format. The general contract of <code>readUTF</code> is that
420+ * it reads a representation of a Unicode character string encoded
421+ * in modified UTF-8 format; this string of characters is
422+ * then returned as a <code>String</code>.
423+ *
424+ * <p> First, two bytes are read and used to construct an unsigned
425+ * 16-bit integer in the manner of the
426+ * <code>readUnsignedShort</code> method, using network byte order
427+ * (regardless of the current byte order setting). This integer
428+ * value is called the <i>UTF length</i> and specifies the number
429+ * of additional bytes to be read. These bytes are then converted
430+ * to characters by considering them in groups. The length of each
431+ * group is computed from the value of the first byte of the
432+ * group. The byte following a group, if any, is the first byte of
433+ * the next group.
434+ *
435+ * <p> If the first byte of a group matches the bit pattern
436+ * <code>0xxxxxxx</code> (where <code>x</code> means "may be
437+ * <code>0</code> or <code>1</code>"), then the group consists of
438+ * just that byte. The byte is zero-extended to form a character.
439+ *
440+ * <p> If the first byte of a group matches the bit pattern
441+ * <code>110xxxxx</code>, then the group consists of that byte
442+ * <code>a</code> and a second byte <code>b</code>. If there is no
443+ * byte <code>b</code> (because byte <code>a</code> was the last
444+ * of the bytes to be read), or if byte <code>b</code> does not
445+ * match the bit pattern <code>10xxxxxx</code>, then a
446+ * <code>UTFDataFormatException</code> is thrown. Otherwise, the
447+ * group is converted to the character:
448+ *
449+ * <p> <pre><code>
450+ * (char)(((a&amp; 0x1F) &lt;&lt; 6) | (b &amp; 0x3F))
451+ * </code></pre>
452+ *
453+ * If the first byte of a group matches the bit pattern
454+ * <code>1110xxxx</code>, then the group consists of that byte
455+ * <code>a</code> and two more bytes <code>b</code> and
456+ * <code>c</code>. If there is no byte <code>c</code> (because
457+ * byte <code>a</code> was one of the last two of the bytes to be
458+ * read), or either byte <code>b</code> or byte <code>c</code>
459+ * does not match the bit pattern <code>10xxxxxx</code>, then a
460+ * <code>UTFDataFormatException</code> is thrown. Otherwise, the
461+ * group is converted to the character:
462+ *
463+ * <p> <pre><code>
464+ * (char)(((a &amp; 0x0F) &lt;&lt; 12) | ((b &amp; 0x3F) &lt;&lt; 6) | (c &amp; 0x3F))
465+ * </code></pre>
466+ *
467+ * If the first byte of a group matches the pattern
468+ * <code>1111xxxx</code> or the pattern <code>10xxxxxx</code>,
469+ * then a <code>UTFDataFormatException</code> is thrown.
470+ *
471+ * <p> If end of file is encountered at any time during this
472+ * entire process, then an <code>EOFException</code> is thrown.
473+ *
474+ * <p> After every group has been converted to a character by this
475+ * process, the characters are gathered, in the same order in
476+ * which their corresponding groups were read from the input
477+ * stream, to form a <code>String</code>, which is returned.
478+ *
479+ * <p> The current byte order setting is ignored.
480+ *
481+ * <p> The bit offset within the stream is reset to zero before
482+ * the read occurs.
483+ *
484+ * <p><strong>Note:</strong> This method should not be used in
485+ * the implementation of image formats that use standard UTF-8,
486+ * because the modified UTF-8 used here is incompatible with
487+ * standard UTF-8.
488+ *
489+ * @return a String read from the stream.
490+ *
491+ * @exception EOFException if this stream reaches the end
492+ * before reading all the bytes.
493+ * @exception UTFDataFormatException if the bytes do not represent a
494+ * valid modified UTF-8 encoding of a string.
495+ * @exception IOException if an I/O error occurs.
496+ */
497+ String readUTF() throws IOException;
498+
499+ /**
500+ * Reads <code>len</code> bytes from the stream, and stores them
501+ * into <code>b</code> starting at index <code>off</code>.
502+ * If the end of the stream is reached, an <code>EOFException</code>
503+ * will be thrown.
504+ *
505+ * <p> The bit offset within the stream is reset to zero before
506+ * the read occurs.
507+ *
508+ * @param b an array of bytes to be written to.
509+ * @param off the starting position within <code>b</code> to write to.
510+ * @param len the maximum number of <code>byte</code>s to read.
511+ *
512+ * @exception IndexOutOfBoundsException if <code>off</code> is
513+ * negative, <code>len</code> is negative, or <code>off +
514+ * len</code> is greater than <code>b.length</code>.
515+ * @exception NullPointerException if <code>b</code> is
516+ * <code>null</code>.
517+ * @exception EOFException if the stream reaches the end before
518+ * reading all the bytes.
519+ * @exception IOException if an I/O error occurs.
520+ */
521+ void readFully(byte[] b, int off, int len) throws IOException;
522+
523+ /**
524+ * Reads <code>b.length</code> bytes from the stream, and stores them
525+ * into <code>b</code> starting at index <code>0</code>.
526+ * If the end of the stream is reached, an <code>EOFException</code>
527+ * will be thrown.
528+ *
529+ * <p> The bit offset within the stream is reset to zero before
530+ * the read occurs.
531+ *
532+ * @param b an array of <code>byte</code>s.
533+ *
534+ * @exception NullPointerException if <code>b</code> is
535+ * <code>null</code>.
536+ * @exception EOFException if the stream reaches the end before
537+ * reading all the bytes.
538+ * @exception IOException if an I/O error occurs.
539+ */
540+ void readFully(byte[] b) throws IOException;
541+
542+ /**
543+ * Reads <code>len</code> shorts (signed 16-bit integers) from the
544+ * stream according to the current byte order, and
545+ * stores them into <code>s</code> starting at index
546+ * <code>off</code>. If the end of the stream is reached, an
547+ * <code>EOFException</code> will be thrown.
548+ *
549+ * <p> The bit offset within the stream is reset to zero before
550+ * the read occurs.
551+ *
552+ * @param s an array of shorts to be written to.
553+ * @param off the starting position withinb to write to.
554+ * @param len the maximum number of <code>short</code>s to read.
555+ *
556+ * @exception IndexOutOfBoundsException if <code>off</code> is
557+ * negative, <code>len</code> is negative, or <code>off +
558+ * len</code> is greater than <code>s.length</code>.
559+ * @exception NullPointerException if <code>s</code> is
560+ * <code>null</code>.
561+ * @exception EOFException if the stream reaches the end before
562+ * reading all the bytes.
563+ * @exception IOException if an I/O error occurs.
564+ */
565+ void readFully(short[] s, int off, int len) throws IOException;
566+
567+ /**
568+ * Reads <code>len</code> chars (unsigned 16-bit integers) from the
569+ * stream according to the current byte order, and
570+ * stores them into <code>c</code> starting at index
571+ * <code>off</code>. If the end of the stream is reached, an
572+ * <code>EOFException</code> will be thrown.
573+ *
574+ * <p> The bit offset within the stream is reset to zero before
575+ * the read occurs.
576+ *
577+ * @param c an array of chars to be written to.
578+ * @param off the starting position withinb to write to.
579+ * @param len the maximum number of <code>char</code>s to read.
580+ *
581+ * @exception IndexOutOfBoundsException if <code>off</code> is
582+ * negative, <code>len</code> is negative, or <code>off +
583+ * len</code> is greater than <code>c.length</code>.
584+ * @exception NullPointerException if <code>c</code> is
585+ * <code>null</code>.
586+ * @exception EOFException if the stream reaches the end before
587+ * reading all the bytes.
588+ * @exception IOException if an I/O error occurs.
589+ */
590+ void readFully(char[] c, int off, int len) throws IOException;
591+
592+ /**
593+ * Reads <code>len</code> ints (signed 32-bit integers) from the
594+ * stream according to the current byte order, and
595+ * stores them into <code>i</code> starting at index
596+ * <code>off</code>. If the end of the stream is reached, an
597+ * <code>EOFException</code> will be thrown.
598+ *
599+ * <p> The bit offset within the stream is reset to zero before
600+ * the read occurs.
601+ *
602+ * @param i an array of ints to be written to.
603+ * @param off the starting position withinb to write to.
604+ * @param len the maximum number of <code>int</code>s to read.
605+ *
606+ * @exception IndexOutOfBoundsException if <code>off</code> is
607+ * negative, <code>len</code> is negative, or <code>off +
608+ * len</code> is greater than <code>i.length</code>.
609+ * @exception NullPointerException if <code>i</code> is
610+ * <code>null</code>.
611+ * @exception EOFException if the stream reaches the end before
612+ * reading all the bytes.
613+ * @exception IOException if an I/O error occurs.
614+ */
615+ void readFully(int[] i, int off, int len) throws IOException;
616+
617+ /**
618+ * Reads <code>len</code> longs (signed 64-bit integers) from the
619+ * stream according to the current byte order, and
620+ * stores them into <code>l</code> starting at index
621+ * <code>off</code>. If the end of the stream is reached, an
622+ * <code>EOFException</code> will be thrown.
623+ *
624+ * <p> The bit offset within the stream is reset to zero before
625+ * the read occurs.
626+ *
627+ * @param l an array of longs to be written to.
628+ * @param off the starting position withinb to write to.
629+ * @param len the maximum number of <code>long</code>s to read.
630+ *
631+ * @exception IndexOutOfBoundsException if <code>off</code> is
632+ * negative, <code>len</code> is negative, or <code>off +
633+ * len</code> is greater than <code>l.length</code>.
634+ * @exception NullPointerException if <code>l</code> is
635+ * <code>null</code>.
636+ * @exception EOFException if the stream reaches the end before
637+ * reading all the bytes.
638+ * @exception IOException if an I/O error occurs.
639+ */
640+ void readFully(long[] l, int off, int len) throws IOException;
641+
642+ /**
643+ * Reads <code>len</code> floats (32-bit IEEE single-precision
644+ * floats) from the stream according to the current byte order,
645+ * and stores them into <code>f</code> starting at
646+ * index <code>off</code>. If the end of the stream is reached,
647+ * an <code>EOFException</code> will be thrown.
648+ *
649+ * <p> The bit offset within the stream is reset to zero before
650+ * the read occurs.
651+ *
652+ * @param f an array of floats to be written to.
653+ * @param off the starting position withinb to write to.
654+ * @param len the maximum number of <code>float</code>s to read.
655+ *
656+ * @exception IndexOutOfBoundsException if <code>off</code> is
657+ * negative, <code>len</code> is negative, or <code>off +
658+ * len</code> is greater than <code>f.length</code>.
659+ * @exception NullPointerException if <code>f</code> is
660+ * <code>null</code>.
661+ * @exception EOFException if the stream reaches the end before
662+ * reading all the bytes.
663+ * @exception IOException if an I/O error occurs.
664+ */
665+ void readFully(float[] f, int off, int len) throws IOException;
666+
667+ /**
668+ * Reads <code>len</code> doubles (64-bit IEEE double-precision
669+ * floats) from the stream according to the current byte order,
670+ * and stores them into <code>d</code> starting at
671+ * index <code>off</code>. If the end of the stream is reached,
672+ * an <code>EOFException</code> will be thrown.
673+ *
674+ * <p> The bit offset within the stream is reset to zero before
675+ * the read occurs.
676+ *
677+ * @param d an array of doubles to be written to.
678+ * @param off the starting position withinb to write to.
679+ * @param len the maximum number of <code>double</code>s to read.
680+ *
681+ * @exception IndexOutOfBoundsException if <code>off</code> is
682+ * negative, <code>len</code> is negative, or <code>off +
683+ * len</code> is greater than <code>d.length</code>.
684+ * @exception NullPointerException if <code>d</code> is
685+ * <code>null</code>.
686+ * @exception EOFException if the stream reaches the end before
687+ * reading all the bytes.
688+ * @exception IOException if an I/O error occurs.
689+ */
690+ void readFully(double[] d, int off, int len) throws IOException;
691+
692+ /**
693+ * Returns the current byte position of the stream. The next read
694+ * will take place starting at this offset.
695+ *
696+ * @return a long containing the position of the stream.
697+ *
698+ * @exception IOException if an I/O error occurs.
699+ */
700+ long getStreamPosition() throws IOException;
701+
702+ /**
703+ * Returns the current bit offset, as an integer between 0 and 7,
704+ * inclusive. The bit offset is updated implicitly by calls to
705+ * the <code>readBits</code> method. A value of 0 indicates the
706+ * most-significant bit, and a value of 7 indicates the least
707+ * significant bit, of the byte being read.
708+ *
709+ * <p> The bit offset is set to 0 when a stream is first
710+ * opened, and is reset to 0 by calls to <code>seek</code>,
711+ * <code>skipBytes</code>, or any <code>read</code> or
712+ * <code>readFully</code> method.
713+ *
714+ * @return an <code>int</code> containing the bit offset between
715+ * 0 and 7, inclusive.
716+ *
717+ * @exception IOException if an I/O error occurs.
718+ *
719+ * @see #setBitOffset
720+ */
721+ int getBitOffset() throws IOException;
722+
723+ /**
724+ * Sets the bit offset to an integer between 0 and 7, inclusive.
725+ * The byte offset within the stream, as returned by
726+ * <code>getStreamPosition</code>, is left unchanged.
727+ * A value of 0 indicates the
728+ * most-significant bit, and a value of 7 indicates the least
729+ * significant bit, of the byte being read.
730+ *
731+ * @param bitOffset the desired offset, as an <code>int</code>
732+ * between 0 and 7, inclusive.
733+ *
734+ * @exception IllegalArgumentException if <code>bitOffset</code>
735+ * is not between 0 and 7, inclusive.
736+ * @exception IOException if an I/O error occurs.
737+ *
738+ * @see #getBitOffset
739+ */
740+ void setBitOffset(int bitOffset) throws IOException;
741+
742+ /**
743+ * Reads a single bit from the stream and returns it as an
744+ * <code>int</code> with the value <code>0</code> or
745+ * <code>1</code>. The bit offset is advanced by one and reduced
746+ * modulo 8.
747+ *
748+ * @return an <code>int</code> containing the value <code>0</code>
749+ * or <code>1</code>.
750+ *
751+ * @exception EOFException if the stream reaches the end before
752+ * reading all the bits.
753+ * @exception IOException if an I/O error occurs.
754+ */
755+ int readBit() throws IOException;
756+
757+ /**
758+ * Reads a bitstring from the stream and returns it as a
759+ * <code>long</code>, with the first bit read becoming the most
760+ * significant bit of the output. The read starts within the byte
761+ * indicated by <code>getStreamPosition</code>, at the bit given
762+ * by <code>getBitOffset</code>. The bit offset is advanced by
763+ * <code>numBits</code> and reduced modulo 8.
764+ *
765+ * <p> The byte order of the stream has no effect on this
766+ * method. The return value of this method is constructed as
767+ * though the bits were read one at a time, and shifted into
768+ * the right side of the return value, as shown by the following
769+ * pseudo-code:
770+ *
771+ * <pre>
772+ * long accum = 0L;
773+ * for (int i = 0; i < numBits; i++) {
774+ * accum <<= 1; // Shift left one bit to make room
775+ * accum |= readBit();
776+ * }
777+ * </pre>
778+ *
779+ * Note that the result of <code>readBits(32)</code> may thus not
780+ * be equal to that of <code>readInt()</code> if a reverse network
781+ * byte order is being used (i.e., <code>getByteOrder() ==
782+ * false</code>).
783+ *
784+ * <p> If the end of the stream is encountered before all the bits
785+ * have been read, an <code>EOFException</code> is thrown.
786+ *
787+ * @param numBits the number of bits to read, as an <code>int</code>
788+ * between 0 and 64, inclusive.
789+ * @return the bitstring, as a <code>long</code> with the last bit
790+ * read stored in the least significant bit.
791+ *
792+ * @exception IllegalArgumentException if <code>numBits</code>
793+ * is not between 0 and 64, inclusive.
794+ * @exception EOFException if the stream reaches the end before
795+ * reading all the bits.
796+ * @exception IOException if an I/O error occurs.
797+ */
798+ long readBits(int numBits) throws IOException;
799+
800+ /**
801+ * Returns the total length of the stream, if known. Otherwise,
802+ * <code>-1</code> is returned.
803+ *
804+ * @return a <code>long</code> containing the length of the
805+ * stream, if known, or else <code>-1</code>.
806+ *
807+ * @exception IOException if an I/O error occurs.
808+ */
809+ long length() throws IOException;
810+
811+ /**
812+ * Moves the stream position forward by a given number of bytes. It
813+ * is possible that this method will only be able to skip forward
814+ * by a smaller number of bytes than requested, for example if the
815+ * end of the stream is reached. In all cases, the actual number
816+ * of bytes skipped is returned. The bit offset is set to zero
817+ * prior to advancing the position.
818+ *
819+ * @param n an <code>int</code> containing the number of bytes to
820+ * be skipped.
821+ *
822+ * @return an <code>int</code> representing the number of bytes skipped.
823+ *
824+ * @exception IOException if an I/O error occurs.
825+ */
826+ int skipBytes(int n) throws IOException;
827+
828+ /**
829+ * Moves the stream position forward by a given number of bytes.
830+ * This method is identical to <code>skipBytes(int)</code> except
831+ * that it allows for a larger skip distance.
832+ *
833+ * @param n a <code>long</code> containing the number of bytes to
834+ * be skipped.
835+ *
836+ * @return a <code>long</code> representing the number of bytes
837+ * skipped.
838+ *
839+ * @exception IOException if an I/O error occurs.
840+ */
841+ long skipBytes(long n) throws IOException;
842+
843+ /**
844+ * Sets the current stream position to the desired location. The
845+ * next read will occur at this location. The bit offset is set
846+ * to 0.
847+ *
848+ * <p> An <code>IndexOutOfBoundsException</code> will be thrown if
849+ * <code>pos</code> is smaller than the flushed position (as
850+ * returned by <code>getflushedPosition</code>).
851+ *
852+ * <p> It is legal to seek past the end of the file; an
853+ * <code>EOFException</code> will be thrown only if a read is
854+ * performed.
855+ *
856+ * @param pos a <code>long</code> containing the desired file
857+ * pointer position.
858+ *
859+ * @exception IndexOutOfBoundsException if <code>pos</code> is smaller
860+ * than the flushed position.
861+ * @exception IOException if any other I/O error occurs.
862+ */
863+ void seek(long pos) throws IOException;
864+
865+ /**
866+ * Marks a position in the stream to be returned to by a
867+ * subsequent call to <code>reset</code>. Unlike a standard
868+ * <code>InputStream</code>, all <code>ImageInputStream</code>s
869+ * support marking. Additionally, calls to <code>mark</code> and
870+ * <code>reset</code> may be nested arbitrarily.
871+ *
872+ * <p> Unlike the <code>mark</code> methods declared by the
873+ * <code>Reader</code> and <code>InputStream</code> interfaces, no
874+ * <code>readLimit</code> parameter is used. An arbitrary amount
875+ * of data may be read following the call to <code>mark</code>.
876+ *
877+ * <p> The bit position used by the <code>readBits</code> method
878+ * is saved and restored by each pair of calls to
879+ * <code>mark</code> and <code>reset</code>.
880+ *
881+ * <p> Note that it is valid for an <code>ImageReader</code> to call
882+ * <code>flushBefore</code> as part of a read operation.
883+ * Therefore, if an application calls <code>mark</code> prior to
884+ * passing that stream to an <code>ImageReader</code>, the application
885+ * should not assume that the marked position will remain valid after
886+ * the read operation has completed.
887+ */
888+ void mark();
889+
890+ /**
891+ * Returns the stream pointer to its previous position, including
892+ * the bit offset, at the time of the most recent unmatched call
893+ * to <code>mark</code>.
894+ *
895+ * <p> Calls to <code>reset</code> without a corresponding call
896+ * to <code>mark</code> have no effect.
897+ *
898+ * <p> An <code>IOException</code> will be thrown if the previous
899+ * marked position lies in the discarded portion of the stream.
900+ *
901+ * @exception IOException if an I/O error occurs.
902+ */
903+ void reset() throws IOException;
904+
905+ /**
906+ * Discards the initial portion of the stream prior to the
907+ * indicated postion. Attempting to seek to an offset within the
908+ * flushed portion of the stream will result in an
909+ * <code>IndexOutOfBoundsException</code>.
910+ *
911+ * <p> Calling <code>flushBefore</code> may allow classes
912+ * implementing this interface to free up resources such as memory
913+ * or disk space that are being used to store data from the
914+ * stream.
915+ *
916+ * @param pos a <code>long</code> containing the length of the
917+ * stream prefix that may be flushed.
918+ *
919+ * @exception IndexOutOfBoundsException if <code>pos</code> lies
920+ * in the flushed portion of the stream or past the current stream
921+ * position.
922+ * @exception IOException if an I/O error occurs.
923+ */
924+ void flushBefore(long pos) throws IOException;
925+
926+ /**
927+ * Discards the initial position of the stream prior to the current
928+ * stream position. Equivalent to
929+ * <code>flushBefore(getStreamPosition())</code>.
930+ *
931+ * @exception IOException if an I/O error occurs.
932+ */
933+ void flush() throws IOException;
934+
935+ /**
936+ * Returns the earliest position in the stream to which seeking
937+ * may be performed. The returned value will be the maximum of
938+ * all values passed into previous calls to
939+ * <code>flushBefore</code>.
940+ *
941+ * @return the earliest legal position for seeking, as a
942+ * <code>long</code>.
943+ */
944+ long getFlushedPosition();
945+
946+ /**
947+ * Returns <code>true</code> if this <code>ImageInputStream</code>
948+ * caches data itself in order to allow seeking backwards.
949+ * Applications may consult this in order to decide how frequently,
950+ * or whether, to flush in order to conserve cache resources.
951+ *
952+ * @return <code>true</code> if this <code>ImageInputStream</code>
953+ * caches data.
954+ *
955+ * @see #isCachedMemory
956+ * @see #isCachedFile
957+ */
958+ boolean isCached();
959+
960+ /**
961+ * Returns <code>true</code> if this <code>ImageInputStream</code>
962+ * caches data itself in order to allow seeking backwards, and
963+ * the cache is kept in main memory. Applications may consult
964+ * this in order to decide how frequently, or whether, to flush
965+ * in order to conserve cache resources.
966+ *
967+ * @return <code>true</code> if this <code>ImageInputStream</code>
968+ * caches data in main memory.
969+ *
970+ * @see #isCached
971+ * @see #isCachedFile
972+ */
973+ boolean isCachedMemory();
974+
975+ /**
976+ * Returns <code>true</code> if this <code>ImageInputStream</code>
977+ * caches data itself in order to allow seeking backwards, and
978+ * the cache is kept in a temporary file. Applications may consult
979+ * this in order to decide how frequently, or whether, to flush
980+ * in order to conserve cache resources.
981+ *
982+ * @return <code>true</code> if this <code>ImageInputStream</code>
983+ * caches data in a temporary file.
984+ *
985+ * @see #isCached
986+ * @see #isCachedMemory
987+ */
988+ boolean isCachedFile();
989+
990+ /**
991+ * Closes the stream. Attempts to access a stream that has been
992+ * closed may result in <code>IOException</code>s or incorrect
993+ * behavior. Calling this method may allow classes implementing
994+ * this interface to release resources associated with the stream
995+ * such as memory, disk space, or file descriptors.
996+ *
997+ * @exception IOException if an I/O error occurs.
998+ */
999+ void close() throws IOException;
1000+}