0001 /*
0002 * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package javax.imageio.stream;
0027
0028 import java.io.DataInput;
0029 import java.io.EOFException;
0030 import java.io.IOException;
0031 import java.io.UTFDataFormatException;
0032 import java.nio.ByteOrder;
0033
0034 /**
0035 * A seekable input stream interface for use by
0036 * <code>ImageReader</code>s. Various input sources, such as
0037 * <code>InputStream</code>s and <code>File</code>s,
0038 * as well as future fast I/O sources may be "wrapped" by a suitable
0039 * implementation of this interface for use by the Image I/O API.
0040 *
0041 * @see ImageInputStreamImpl
0042 * @see FileImageInputStream
0043 * @see FileCacheImageInputStream
0044 * @see MemoryCacheImageInputStream
0045 *
0046 * @version 0.5
0047 */
0048 public interface ImageInputStream extends DataInput {
0049
0050 /**
0051 * Sets the desired byte order for future reads of data values
0052 * from this stream. For example, the sequence of bytes '0x01
0053 * 0x02 0x03 0x04' if read as a 4-byte integer would have the
0054 * value '0x01020304' using network byte order and the value
0055 * '0x04030201' under the reverse byte order.
0056 *
0057 * <p> The enumeration class <code>java.nio.ByteOrder</code> is
0058 * used to specify the byte order. A value of
0059 * <code>ByteOrder.BIG_ENDIAN</code> specifies so-called
0060 * big-endian or network byte order, in which the high-order byte
0061 * comes first. Motorola and Sparc processors store data in this
0062 * format, while Intel processors store data in the reverse
0063 * <code>ByteOrder.LITTLE_ENDIAN</code> order.
0064 *
0065 * <p> The byte order has no effect on the results returned from
0066 * the <code>readBits</code> method (or the value written by
0067 * <code>ImageOutputStream.writeBits</code>).
0068 *
0069 * @param byteOrder one of <code>ByteOrder.BIG_ENDIAN</code> or
0070 * <code>java.nio.ByteOrder.LITTLE_ENDIAN</code>, indicating whether
0071 * network byte order or its reverse will be used for future
0072 * reads.
0073 *
0074 * @see java.nio.ByteOrder
0075 * @see #getByteOrder
0076 * @see #readBits(int)
0077 */
0078 void setByteOrder(ByteOrder byteOrder);
0079
0080 /**
0081 * Returns the byte order with which data values will be read from
0082 * this stream as an instance of the
0083 * <code>java.nio.ByteOrder</code> enumeration.
0084 *
0085 * @return one of <code>ByteOrder.BIG_ENDIAN</code> or
0086 * <code>ByteOrder.LITTLE_ENDIAN</code>, indicating which byte
0087 * order is being used.
0088 *
0089 * @see java.nio.ByteOrder
0090 * @see #setByteOrder
0091 */
0092 ByteOrder getByteOrder();
0093
0094 /**
0095 * Reads a single byte from the stream and returns it as an
0096 * integer between 0 and 255. If the end of the stream is
0097 * reached, -1 is returned.
0098 *
0099 * <p> The bit offset within the stream is reset to zero before
0100 * the read occurs.
0101 *
0102 * @return a byte value from the stream, as an int, or -1 to
0103 * indicate EOF.
0104 *
0105 * @exception IOException if an I/O error occurs.
0106 */
0107 int read() throws IOException;
0108
0109 /**
0110 * Reads up to <code>b.length</code> bytes from the stream, and
0111 * stores them into <code>b</code> starting at index 0. The
0112 * number of bytes read is returned. If no bytes can be read
0113 * because the end of the stream has been reached, -1 is returned.
0114 *
0115 * <p> The bit offset within the stream is reset to zero before
0116 * the read occurs.
0117 *
0118 * @param b an array of bytes to be written to.
0119 *
0120 * @return the number of bytes actually read, or <code>-1</code>
0121 * to indicate EOF.
0122 *
0123 * @exception NullPointerException if <code>b</code> is
0124 * <code>null</code>.
0125 *
0126 * @exception IOException if an I/O error occurs.
0127 */
0128 int read(byte[] b) throws IOException;
0129
0130 /**
0131 * Reads up to <code>len</code> bytes from the stream, and stores
0132 * them into <code>b</code> starting at index <code>off</code>.
0133 * The number of bytes read is returned. If no bytes can be read
0134 * because the end of the stream has been reached, <code>-1</code>
0135 * is returned.
0136 *
0137 * <p> The bit offset within the stream is reset to zero before
0138 * the read occurs.
0139 *
0140 * @param b an array of bytes to be written to.
0141 * @param off the starting position within <code>b</code> to write to.
0142 * @param len the maximum number of <code>byte</code>s to read.
0143 *
0144 * @return the number of bytes actually read, or <code>-1</code>
0145 * to indicate EOF.
0146 *
0147 * @exception NullPointerException if <code>b</code> is
0148 * <code>null</code>.
0149 * @exception IndexOutOfBoundsException if <code>off</code> is
0150 * negative, <code>len</code> is negative, or <code>off +
0151 * len</code> is greater than <code>b.length</code>.
0152 * @exception IOException if an I/O error occurs.
0153 */
0154 int read(byte[] b, int off, int len) throws IOException;
0155
0156 /**
0157 * Reads up to <code>len</code> bytes from the stream, and
0158 * modifies the supplied <code>IIOByteBuffer</code> to indicate
0159 * the byte array, offset, and length where the data may be found.
0160 * The caller should not attempt to modify the data found in the
0161 * <code>IIOByteBuffer</code>.
0162 *
0163 * <p> The bit offset within the stream is reset to zero before
0164 * the read occurs.
0165 *
0166 * @param buf an IIOByteBuffer object to be modified.
0167 * @param len the maximum number of <code>byte</code>s to read.
0168 *
0169 * @exception IndexOutOfBoundsException if <code>len</code> is
0170 * negative.
0171 * @exception NullPointerException if <code>buf</code> is
0172 * <code>null</code>.
0173 *
0174 * @exception IOException if an I/O error occurs.
0175 */
0176 void readBytes(IIOByteBuffer buf, int len) throws IOException;
0177
0178 /**
0179 * Reads a byte from the stream and returns a <code>boolean</code>
0180 * value of <code>true</code> if it is nonzero, <code>false</code>
0181 * if it is zero.
0182 *
0183 * <p> The bit offset within the stream is reset to zero before
0184 * the read occurs.
0185 *
0186 * @return a boolean value from the stream.
0187 *
0188 * @exception EOFException if the end of the stream is reached.
0189 * @exception IOException if an I/O error occurs.
0190 */
0191 boolean readBoolean() throws IOException;
0192
0193 /**
0194 * Reads a byte from the stream and returns it as a
0195 * <code>byte</code> value. Byte values between <code>0x00</code>
0196 * and <code>0x7f</code> represent integer values between
0197 * <code>0</code> and <code>127</code>. Values between
0198 * <code>0x80</code> and <code>0xff</code> represent negative
0199 * values from <code>-128</code> to <code>/1</code>.
0200 *
0201 * <p> The bit offset within the stream is reset to zero before
0202 * the read occurs.
0203 *
0204 * @return a signed byte value from the stream.
0205 *
0206 * @exception EOFException if the end of the stream is reached.
0207 * @exception IOException if an I/O error occurs.
0208 */
0209 byte readByte() throws IOException;
0210
0211 /**
0212 * Reads a byte from the stream, and (conceptually) converts it to
0213 * an int, masks it with <code>0xff</code> in order to strip off
0214 * any sign-extension bits, and returns it as a <code>byte</code>
0215 * value.
0216 *
0217 * <p> Thus, byte values between <code>0x00</code> and
0218 * <code>0x7f</code> are simply returned as integer values between
0219 * <code>0</code> and <code>127</code>. Values between
0220 * <code>0x80</code> and <code>0xff</code>, which normally
0221 * represent negative <code>byte</code>values, will be mapped into
0222 * positive integers between <code>128</code> and
0223 * <code>255</code>.
0224 *
0225 * <p> The bit offset within the stream is reset to zero before
0226 * the read occurs.
0227 *
0228 * @return an unsigned byte value from the stream.
0229 *
0230 * @exception EOFException if the end of the stream is reached.
0231 * @exception IOException if an I/O error occurs.
0232 */
0233 int readUnsignedByte() throws IOException;
0234
0235 /**
0236 * Reads two bytes from the stream, and (conceptually)
0237 * concatenates them according to the current byte order, and
0238 * returns the result as a <code>short</code> value.
0239 *
0240 * <p> The bit offset within the stream is reset to zero before
0241 * the read occurs.
0242 *
0243 * @return a signed short value from the stream.
0244 *
0245 * @exception EOFException if the stream reaches the end before
0246 * reading all the bytes.
0247 * @exception IOException if an I/O error occurs.
0248 *
0249 * @see #getByteOrder
0250 */
0251 short readShort() throws IOException;
0252
0253 /**
0254 * Reads two bytes from the stream, and (conceptually)
0255 * concatenates them according to the current byte order, converts
0256 * the resulting value to an <code>int</code>, masks it with
0257 * <code>0xffff</code> in order to strip off any sign-extension
0258 * buts, and returns the result as an unsigned <code>int</code>
0259 * value.
0260 *
0261 * <p> The bit offset within the stream is reset to zero before
0262 * the read occurs.
0263 *
0264 * @return an unsigned short value from the stream, as an int.
0265 *
0266 * @exception EOFException if the stream reaches the end before
0267 * reading all the bytes.
0268 * @exception IOException if an I/O error occurs.
0269 *
0270 * @see #getByteOrder
0271 */
0272 int readUnsignedShort() throws IOException;
0273
0274 /**
0275 * Equivalent to <code>readUnsignedShort</code>, except that the
0276 * result is returned using the <code>char</code> datatype.
0277 *
0278 * <p> The bit offset within the stream is reset to zero before
0279 * the read occurs.
0280 *
0281 * @return an unsigned char value from the stream.
0282 *
0283 * @exception EOFException if the stream reaches the end before
0284 * reading all the bytes.
0285 * @exception IOException if an I/O error occurs.
0286 *
0287 * @see #readUnsignedShort
0288 */
0289 char readChar() throws IOException;
0290
0291 /**
0292 * Reads 4 bytes from the stream, and (conceptually) concatenates
0293 * them according to the current byte order and returns the result
0294 * as an <code>int</code>.
0295 *
0296 * <p> The bit offset within the stream is ignored and treated as
0297 * though it were zero.
0298 *
0299 * @return a signed int value from the stream.
0300 *
0301 * @exception EOFException if the stream reaches the end before
0302 * reading all the bytes.
0303 * @exception IOException if an I/O error occurs.
0304 *
0305 * @see #getByteOrder
0306 */
0307 int readInt() throws IOException;
0308
0309 /**
0310 * Reads 4 bytes from the stream, and (conceptually) concatenates
0311 * them according to the current byte order, converts the result
0312 * to a long, masks it with <code>0xffffffffL</code> in order to
0313 * strip off any sign-extension bits, and returns the result as an
0314 * unsigned <code>long</code> value.
0315 *
0316 * <p> The bit offset within the stream is reset to zero before
0317 * the read occurs.
0318 *
0319 * @return an unsigned int value from the stream, as a long.
0320 *
0321 * @exception EOFException if the stream reaches the end before
0322 * reading all the bytes.
0323 * @exception IOException if an I/O error occurs.
0324 *
0325 * @see #getByteOrder
0326 */
0327 long readUnsignedInt() throws IOException;
0328
0329 /**
0330 * Reads 8 bytes from the stream, and (conceptually) concatenates
0331 * them according to the current byte order and returns the result
0332 * as a <code>long</code>.
0333 *
0334 * <p> The bit offset within the stream is reset to zero before
0335 * the read occurs.
0336 *
0337 * @return a signed long value from the stream.
0338 *
0339 * @exception EOFException if the stream reaches the end before
0340 * reading all the bytes.
0341 * @exception IOException if an I/O error occurs.
0342 *
0343 * @see #getByteOrder
0344 */
0345 long readLong() throws IOException;
0346
0347 /**
0348 * Reads 4 bytes from the stream, and (conceptually) concatenates
0349 * them according to the current byte order and returns the result
0350 * as a <code>float</code>.
0351 *
0352 * <p> The bit offset within the stream is reset to zero before
0353 * the read occurs.
0354 *
0355 * @return a float value from the stream.
0356 *
0357 * @exception EOFException if the stream reaches the end before
0358 * reading all the bytes.
0359 * @exception IOException if an I/O error occurs.
0360 *
0361 * @see #getByteOrder
0362 */
0363 float readFloat() throws IOException;
0364
0365 /**
0366 * Reads 8 bytes from the stream, and (conceptually) concatenates
0367 * them according to the current byte order and returns the result
0368 * as a <code>double</code>.
0369 *
0370 * <p> The bit offset within the stream is reset to zero before
0371 * the read occurs.
0372 *
0373 * @return a double value from the stream.
0374 *
0375 * @exception EOFException if the stream reaches the end before
0376 * reading all the bytes.
0377 * @exception IOException if an I/O error occurs.
0378 *
0379 * @see #getByteOrder
0380 */
0381 double readDouble() throws IOException;
0382
0383 /**
0384 * Reads the next line of text from the input stream. It reads
0385 * successive bytes, converting each byte separately into a
0386 * character, until it encounters a line terminator or end of
0387 * file; the characters read are then returned as a
0388 * <code>String</code>. Note that because this method processes
0389 * bytes, it does not support input of the full Unicode character
0390 * set.
0391 *
0392 * <p> If end of file is encountered before even one byte can be
0393 * read, then <code>null</code> is returned. Otherwise, each byte
0394 * that is read is converted to type <code>char</code> by
0395 * zero-extension. If the character <code>'\n'</code> is
0396 * encountered, it is discarded and reading ceases. If the
0397 * character <code>'\r'</code> is encountered, it is discarded
0398 * and, if the following byte converts  to the character
0399 * <code>'\n'</code>, then that is discarded also; reading then
0400 * ceases. If end of file is encountered before either of the
0401 * characters <code>'\n'</code> and <code>'\r'</code> is
0402 * encountered, reading ceases. Once reading has ceased, a
0403 * <code>String</code> is returned that contains all the
0404 * characters read and not discarded, taken in order. Note that
0405 * every character in this string will have a value less than
0406 * <code>\u0100</code>, that is, <code>(char)256</code>.
0407 *
0408 * <p> The bit offset within the stream is reset to zero before
0409 * the read occurs.
0410 *
0411 * @return a String containing a line of text from the stream.
0412 *
0413 * @exception IOException if an I/O error occurs.
0414 */
0415 String readLine() throws IOException;
0416
0417 /**
0418 * Reads in a string that has been encoded using a
0419 * <a href="../../../java/io/DataInput.html#modified-utf-8">modified
0420 * UTF-8</a>
0421 * format. The general contract of <code>readUTF</code> is that
0422 * it reads a representation of a Unicode character string encoded
0423 * in modified UTF-8 format; this string of characters is
0424 * then returned as a <code>String</code>.
0425 *
0426 * <p> First, two bytes are read and used to construct an unsigned
0427 * 16-bit integer in the manner of the
0428 * <code>readUnsignedShort</code> method, using network byte order
0429 * (regardless of the current byte order setting). This integer
0430 * value is called the <i>UTF length</i> and specifies the number
0431 * of additional bytes to be read. These bytes are then converted
0432 * to characters by considering them in groups. The length of each
0433 * group is computed from the value of the first byte of the
0434 * group. The byte following a group, if any, is the first byte of
0435 * the next group.
0436 *
0437 * <p> If the first byte of a group matches the bit pattern
0438 * <code>0xxxxxxx</code> (where <code>x</code> means "may be
0439 * <code>0</code> or <code>1</code>"), then the group consists of
0440 * just that byte. The byte is zero-extended to form a character.
0441 *
0442 * <p> If the first byte of a group matches the bit pattern
0443 * <code>110xxxxx</code>, then the group consists of that byte
0444 * <code>a</code> and a second byte <code>b</code>. If there is no
0445 * byte <code>b</code> (because byte <code>a</code> was the last
0446 * of the bytes to be read), or if byte <code>b</code> does not
0447 * match the bit pattern <code>10xxxxxx</code>, then a
0448 * <code>UTFDataFormatException</code> is thrown. Otherwise, the
0449 * group is converted to the character:
0450 *
0451 * <p> <pre><code>
0452 * (char)(((a& 0x1F) << 6) | (b & 0x3F))
0453 * </code></pre>
0454 *
0455 * If the first byte of a group matches the bit pattern
0456 * <code>1110xxxx</code>, then the group consists of that byte
0457 * <code>a</code> and two more bytes <code>b</code> and
0458 * <code>c</code>. If there is no byte <code>c</code> (because
0459 * byte <code>a</code> was one of the last two of the bytes to be
0460 * read), or either byte <code>b</code> or byte <code>c</code>
0461 * does not match the bit pattern <code>10xxxxxx</code>, then a
0462 * <code>UTFDataFormatException</code> is thrown. Otherwise, the
0463 * group is converted to the character:
0464 *
0465 * <p> <pre><code>
0466 * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
0467 * </code></pre>
0468 *
0469 * If the first byte of a group matches the pattern
0470 * <code>1111xxxx</code> or the pattern <code>10xxxxxx</code>,
0471 * then a <code>UTFDataFormatException</code> is thrown.
0472 *
0473 * <p> If end of file is encountered at any time during this
0474 * entire process, then an <code>EOFException</code> is thrown.
0475 *
0476 * <p> After every group has been converted to a character by this
0477 * process, the characters are gathered, in the same order in
0478 * which their corresponding groups were read from the input
0479 * stream, to form a <code>String</code>, which is returned.
0480 *
0481 * <p> The current byte order setting is ignored.
0482 *
0483 * <p> The bit offset within the stream is reset to zero before
0484 * the read occurs.
0485 *
0486 * <p><strong>Note:</strong> This method should not be used in
0487 * the implementation of image formats that use standard UTF-8,
0488 * because the modified UTF-8 used here is incompatible with
0489 * standard UTF-8.
0490 *
0491 * @return a String read from the stream.
0492 *
0493 * @exception EOFException if this stream reaches the end
0494 * before reading all the bytes.
0495 * @exception UTFDataFormatException if the bytes do not represent a
0496 * valid modified UTF-8 encoding of a string.
0497 * @exception IOException if an I/O error occurs.
0498 */
0499 String readUTF() throws IOException;
0500
0501 /**
0502 * Reads <code>len</code> bytes from the stream, and stores them
0503 * into <code>b</code> starting at index <code>off</code>.
0504 * If the end of the stream is reached, an <code>EOFException</code>
0505 * will be thrown.
0506 *
0507 * <p> The bit offset within the stream is reset to zero before
0508 * the read occurs.
0509 *
0510 * @param b an array of bytes to be written to.
0511 * @param off the starting position within <code>b</code> to write to.
0512 * @param len the maximum number of <code>byte</code>s to read.
0513 *
0514 * @exception IndexOutOfBoundsException if <code>off</code> is
0515 * negative, <code>len</code> is negative, or <code>off +
0516 * len</code> is greater than <code>b.length</code>.
0517 * @exception NullPointerException if <code>b</code> is
0518 * <code>null</code>.
0519 * @exception EOFException if the stream reaches the end before
0520 * reading all the bytes.
0521 * @exception IOException if an I/O error occurs.
0522 */
0523 void readFully(byte[] b, int off, int len) throws IOException;
0524
0525 /**
0526 * Reads <code>b.length</code> bytes from the stream, and stores them
0527 * into <code>b</code> starting at index <code>0</code>.
0528 * If the end of the stream is reached, an <code>EOFException</code>
0529 * will be thrown.
0530 *
0531 * <p> The bit offset within the stream is reset to zero before
0532 * the read occurs.
0533 *
0534 * @param b an array of <code>byte</code>s.
0535 *
0536 * @exception NullPointerException if <code>b</code> is
0537 * <code>null</code>.
0538 * @exception EOFException if the stream reaches the end before
0539 * reading all the bytes.
0540 * @exception IOException if an I/O error occurs.
0541 */
0542 void readFully(byte[] b) throws IOException;
0543
0544 /**
0545 * Reads <code>len</code> shorts (signed 16-bit integers) from the
0546 * stream according to the current byte order, and
0547 * stores them into <code>s</code> starting at index
0548 * <code>off</code>. If the end of the stream is reached, an
0549 * <code>EOFException</code> will be thrown.
0550 *
0551 * <p> The bit offset within the stream is reset to zero before
0552 * the read occurs.
0553 *
0554 * @param s an array of shorts to be written to.
0555 * @param off the starting position withinb to write to.
0556 * @param len the maximum number of <code>short</code>s to read.
0557 *
0558 * @exception IndexOutOfBoundsException if <code>off</code> is
0559 * negative, <code>len</code> is negative, or <code>off +
0560 * len</code> is greater than <code>s.length</code>.
0561 * @exception NullPointerException if <code>s</code> is
0562 * <code>null</code>.
0563 * @exception EOFException if the stream reaches the end before
0564 * reading all the bytes.
0565 * @exception IOException if an I/O error occurs.
0566 */
0567 void readFully(short[] s, int off, int len) throws IOException;
0568
0569 /**
0570 * Reads <code>len</code> chars (unsigned 16-bit integers) from the
0571 * stream according to the current byte order, and
0572 * stores them into <code>c</code> starting at index
0573 * <code>off</code>. If the end of the stream is reached, an
0574 * <code>EOFException</code> will be thrown.
0575 *
0576 * <p> The bit offset within the stream is reset to zero before
0577 * the read occurs.
0578 *
0579 * @param c an array of chars to be written to.
0580 * @param off the starting position withinb to write to.
0581 * @param len the maximum number of <code>char</code>s to read.
0582 *
0583 * @exception IndexOutOfBoundsException if <code>off</code> is
0584 * negative, <code>len</code> is negative, or <code>off +
0585 * len</code> is greater than <code>c.length</code>.
0586 * @exception NullPointerException if <code>c</code> is
0587 * <code>null</code>.
0588 * @exception EOFException if the stream reaches the end before
0589 * reading all the bytes.
0590 * @exception IOException if an I/O error occurs.
0591 */
0592 void readFully(char[] c, int off, int len) throws IOException;
0593
0594 /**
0595 * Reads <code>len</code> ints (signed 32-bit integers) from the
0596 * stream according to the current byte order, and
0597 * stores them into <code>i</code> starting at index
0598 * <code>off</code>. If the end of the stream is reached, an
0599 * <code>EOFException</code> will be thrown.
0600 *
0601 * <p> The bit offset within the stream is reset to zero before
0602 * the read occurs.
0603 *
0604 * @param i an array of ints to be written to.
0605 * @param off the starting position withinb to write to.
0606 * @param len the maximum number of <code>int</code>s to read.
0607 *
0608 * @exception IndexOutOfBoundsException if <code>off</code> is
0609 * negative, <code>len</code> is negative, or <code>off +
0610 * len</code> is greater than <code>i.length</code>.
0611 * @exception NullPointerException if <code>i</code> is
0612 * <code>null</code>.
0613 * @exception EOFException if the stream reaches the end before
0614 * reading all the bytes.
0615 * @exception IOException if an I/O error occurs.
0616 */
0617 void readFully(int[] i, int off, int len) throws IOException;
0618
0619 /**
0620 * Reads <code>len</code> longs (signed 64-bit integers) from the
0621 * stream according to the current byte order, and
0622 * stores them into <code>l</code> starting at index
0623 * <code>off</code>. If the end of the stream is reached, an
0624 * <code>EOFException</code> will be thrown.
0625 *
0626 * <p> The bit offset within the stream is reset to zero before
0627 * the read occurs.
0628 *
0629 * @param l an array of longs to be written to.
0630 * @param off the starting position withinb to write to.
0631 * @param len the maximum number of <code>long</code>s to read.
0632 *
0633 * @exception IndexOutOfBoundsException if <code>off</code> is
0634 * negative, <code>len</code> is negative, or <code>off +
0635 * len</code> is greater than <code>l.length</code>.
0636 * @exception NullPointerException if <code>l</code> is
0637 * <code>null</code>.
0638 * @exception EOFException if the stream reaches the end before
0639 * reading all the bytes.
0640 * @exception IOException if an I/O error occurs.
0641 */
0642 void readFully(long[] l, int off, int len) throws IOException;
0643
0644 /**
0645 * Reads <code>len</code> floats (32-bit IEEE single-precision
0646 * floats) from the stream according to the current byte order,
0647 * and stores them into <code>f</code> starting at
0648 * index <code>off</code>. If the end of the stream is reached,
0649 * an <code>EOFException</code> will be thrown.
0650 *
0651 * <p> The bit offset within the stream is reset to zero before
0652 * the read occurs.
0653 *
0654 * @param f an array of floats to be written to.
0655 * @param off the starting position withinb to write to.
0656 * @param len the maximum number of <code>float</code>s to read.
0657 *
0658 * @exception IndexOutOfBoundsException if <code>off</code> is
0659 * negative, <code>len</code> is negative, or <code>off +
0660 * len</code> is greater than <code>f.length</code>.
0661 * @exception NullPointerException if <code>f</code> is
0662 * <code>null</code>.
0663 * @exception EOFException if the stream reaches the end before
0664 * reading all the bytes.
0665 * @exception IOException if an I/O error occurs.
0666 */
0667 void readFully(float[] f, int off, int len) throws IOException;
0668
0669 /**
0670 * Reads <code>len</code> doubles (64-bit IEEE double-precision
0671 * floats) from the stream according to the current byte order,
0672 * and stores them into <code>d</code> starting at
0673 * index <code>off</code>. If the end of the stream is reached,
0674 * an <code>EOFException</code> will be thrown.
0675 *
0676 * <p> The bit offset within the stream is reset to zero before
0677 * the read occurs.
0678 *
0679 * @param d an array of doubles to be written to.
0680 * @param off the starting position withinb to write to.
0681 * @param len the maximum number of <code>double</code>s to read.
0682 *
0683 * @exception IndexOutOfBoundsException if <code>off</code> is
0684 * negative, <code>len</code> is negative, or <code>off +
0685 * len</code> is greater than <code>d.length</code>.
0686 * @exception NullPointerException if <code>d</code> is
0687 * <code>null</code>.
0688 * @exception EOFException if the stream reaches the end before
0689 * reading all the bytes.
0690 * @exception IOException if an I/O error occurs.
0691 */
0692 void readFully(double[] d, int off, int len) throws IOException;
0693
0694 /**
0695 * Returns the current byte position of the stream. The next read
0696 * will take place starting at this offset.
0697 *
0698 * @return a long containing the position of the stream.
0699 *
0700 * @exception IOException if an I/O error occurs.
0701 */
0702 long getStreamPosition() throws IOException;
0703
0704 /**
0705 * Returns the current bit offset, as an integer between 0 and 7,
0706 * inclusive. The bit offset is updated implicitly by calls to
0707 * the <code>readBits</code> method. A value of 0 indicates the
0708 * most-significant bit, and a value of 7 indicates the least
0709 * significant bit, of the byte being read.
0710 *
0711 * <p> The bit offset is set to 0 when a stream is first
0712 * opened, and is reset to 0 by calls to <code>seek</code>,
0713 * <code>skipBytes</code>, or any <code>read</code> or
0714 * <code>readFully</code> method.
0715 *
0716 * @return an <code>int</code> containing the bit offset between
0717 * 0 and 7, inclusive.
0718 *
0719 * @exception IOException if an I/O error occurs.
0720 *
0721 * @see #setBitOffset
0722 */
0723 int getBitOffset() throws IOException;
0724
0725 /**
0726 * Sets the bit offset to an integer between 0 and 7, inclusive.
0727 * The byte offset within the stream, as returned by
0728 * <code>getStreamPosition</code>, is left unchanged.
0729 * A value of 0 indicates the
0730 * most-significant bit, and a value of 7 indicates the least
0731 * significant bit, of the byte being read.
0732 *
0733 * @param bitOffset the desired offset, as an <code>int</code>
0734 * between 0 and 7, inclusive.
0735 *
0736 * @exception IllegalArgumentException if <code>bitOffset</code>
0737 * is not between 0 and 7, inclusive.
0738 * @exception IOException if an I/O error occurs.
0739 *
0740 * @see #getBitOffset
0741 */
0742 void setBitOffset(int bitOffset) throws IOException;
0743
0744 /**
0745 * Reads a single bit from the stream and returns it as an
0746 * <code>int</code> with the value <code>0</code> or
0747 * <code>1</code>. The bit offset is advanced by one and reduced
0748 * modulo 8.
0749 *
0750 * @return an <code>int</code> containing the value <code>0</code>
0751 * or <code>1</code>.
0752 *
0753 * @exception EOFException if the stream reaches the end before
0754 * reading all the bits.
0755 * @exception IOException if an I/O error occurs.
0756 */
0757 int readBit() throws IOException;
0758
0759 /**
0760 * Reads a bitstring from the stream and returns it as a
0761 * <code>long</code>, with the first bit read becoming the most
0762 * significant bit of the output. The read starts within the byte
0763 * indicated by <code>getStreamPosition</code>, at the bit given
0764 * by <code>getBitOffset</code>. The bit offset is advanced by
0765 * <code>numBits</code> and reduced modulo 8.
0766 *
0767 * <p> The byte order of the stream has no effect on this
0768 * method. The return value of this method is constructed as
0769 * though the bits were read one at a time, and shifted into
0770 * the right side of the return value, as shown by the following
0771 * pseudo-code:
0772 *
0773 * <pre>
0774 * long accum = 0L;
0775 * for (int i = 0; i < numBits; i++) {
0776 * accum <<= 1; // Shift left one bit to make room
0777 * accum |= readBit();
0778 * }
0779 * </pre>
0780 *
0781 * Note that the result of <code>readBits(32)</code> may thus not
0782 * be equal to that of <code>readInt()</code> if a reverse network
0783 * byte order is being used (i.e., <code>getByteOrder() ==
0784 * false</code>).
0785 *
0786 * <p> If the end of the stream is encountered before all the bits
0787 * have been read, an <code>EOFException</code> is thrown.
0788 *
0789 * @param numBits the number of bits to read, as an <code>int</code>
0790 * between 0 and 64, inclusive.
0791 * @return the bitstring, as a <code>long</code> with the last bit
0792 * read stored in the least significant bit.
0793 *
0794 * @exception IllegalArgumentException if <code>numBits</code>
0795 * is not between 0 and 64, inclusive.
0796 * @exception EOFException if the stream reaches the end before
0797 * reading all the bits.
0798 * @exception IOException if an I/O error occurs.
0799 */
0800 long readBits(int numBits) throws IOException;
0801
0802 /**
0803 * Returns the total length of the stream, if known. Otherwise,
0804 * <code>-1</code> is returned.
0805 *
0806 * @return a <code>long</code> containing the length of the
0807 * stream, if known, or else <code>-1</code>.
0808 *
0809 * @exception IOException if an I/O error occurs.
0810 */
0811 long length() throws IOException;
0812
0813 /**
0814 * Moves the stream position forward by a given number of bytes. It
0815 * is possible that this method will only be able to skip forward
0816 * by a smaller number of bytes than requested, for example if the
0817 * end of the stream is reached. In all cases, the actual number
0818 * of bytes skipped is returned. The bit offset is set to zero
0819 * prior to advancing the position.
0820 *
0821 * @param n an <code>int</code> containing the number of bytes to
0822 * be skipped.
0823 *
0824 * @return an <code>int</code> representing the number of bytes skipped.
0825 *
0826 * @exception IOException if an I/O error occurs.
0827 */
0828 int skipBytes(int n) throws IOException;
0829
0830 /**
0831 * Moves the stream position forward by a given number of bytes.
0832 * This method is identical to <code>skipBytes(int)</code> except
0833 * that it allows for a larger skip distance.
0834 *
0835 * @param n a <code>long</code> containing the number of bytes to
0836 * be skipped.
0837 *
0838 * @return a <code>long</code> representing the number of bytes
0839 * skipped.
0840 *
0841 * @exception IOException if an I/O error occurs.
0842 */
0843 long skipBytes(long n) throws IOException;
0844
0845 /**
0846 * Sets the current stream position to the desired location. The
0847 * next read will occur at this location. The bit offset is set
0848 * to 0.
0849 *
0850 * <p> An <code>IndexOutOfBoundsException</code> will be thrown if
0851 * <code>pos</code> is smaller than the flushed position (as
0852 * returned by <code>getflushedPosition</code>).
0853 *
0854 * <p> It is legal to seek past the end of the file; an
0855 * <code>EOFException</code> will be thrown only if a read is
0856 * performed.
0857 *
0858 * @param pos a <code>long</code> containing the desired file
0859 * pointer position.
0860 *
0861 * @exception IndexOutOfBoundsException if <code>pos</code> is smaller
0862 * than the flushed position.
0863 * @exception IOException if any other I/O error occurs.
0864 */
0865 void seek(long pos) throws IOException;
0866
0867 /**
0868 * Marks a position in the stream to be returned to by a
0869 * subsequent call to <code>reset</code>. Unlike a standard
0870 * <code>InputStream</code>, all <code>ImageInputStream</code>s
0871 * support marking. Additionally, calls to <code>mark</code> and
0872 * <code>reset</code> may be nested arbitrarily.
0873 *
0874 * <p> Unlike the <code>mark</code> methods declared by the
0875 * <code>Reader</code> and <code>InputStream</code> interfaces, no
0876 * <code>readLimit</code> parameter is used. An arbitrary amount
0877 * of data may be read following the call to <code>mark</code>.
0878 *
0879 * <p> The bit position used by the <code>readBits</code> method
0880 * is saved and restored by each pair of calls to
0881 * <code>mark</code> and <code>reset</code>.
0882 *
0883 * <p> Note that it is valid for an <code>ImageReader</code> to call
0884 * <code>flushBefore</code> as part of a read operation.
0885 * Therefore, if an application calls <code>mark</code> prior to
0886 * passing that stream to an <code>ImageReader</code>, the application
0887 * should not assume that the marked position will remain valid after
0888 * the read operation has completed.
0889 */
0890 void mark();
0891
0892 /**
0893 * Returns the stream pointer to its previous position, including
0894 * the bit offset, at the time of the most recent unmatched call
0895 * to <code>mark</code>.
0896 *
0897 * <p> Calls to <code>reset</code> without a corresponding call
0898 * to <code>mark</code> have no effect.
0899 *
0900 * <p> An <code>IOException</code> will be thrown if the previous
0901 * marked position lies in the discarded portion of the stream.
0902 *
0903 * @exception IOException if an I/O error occurs.
0904 */
0905 void reset() throws IOException;
0906
0907 /**
0908 * Discards the initial portion of the stream prior to the
0909 * indicated postion. Attempting to seek to an offset within the
0910 * flushed portion of the stream will result in an
0911 * <code>IndexOutOfBoundsException</code>.
0912 *
0913 * <p> Calling <code>flushBefore</code> may allow classes
0914 * implementing this interface to free up resources such as memory
0915 * or disk space that are being used to store data from the
0916 * stream.
0917 *
0918 * @param pos a <code>long</code> containing the length of the
0919 * stream prefix that may be flushed.
0920 *
0921 * @exception IndexOutOfBoundsException if <code>pos</code> lies
0922 * in the flushed portion of the stream or past the current stream
0923 * position.
0924 * @exception IOException if an I/O error occurs.
0925 */
0926 void flushBefore(long pos) throws IOException;
0927
0928 /**
0929 * Discards the initial position of the stream prior to the current
0930 * stream position. Equivalent to
0931 * <code>flushBefore(getStreamPosition())</code>.
0932 *
0933 * @exception IOException if an I/O error occurs.
0934 */
0935 void flush() throws IOException;
0936
0937 /**
0938 * Returns the earliest position in the stream to which seeking
0939 * may be performed. The returned value will be the maximum of
0940 * all values passed into previous calls to
0941 * <code>flushBefore</code>.
0942 *
0943 * @return the earliest legal position for seeking, as a
0944 * <code>long</code>.
0945 */
0946 long getFlushedPosition();
0947
0948 /**
0949 * Returns <code>true</code> if this <code>ImageInputStream</code>
0950 * caches data itself in order to allow seeking backwards.
0951 * Applications may consult this in order to decide how frequently,
0952 * or whether, to flush in order to conserve cache resources.
0953 *
0954 * @return <code>true</code> if this <code>ImageInputStream</code>
0955 * caches data.
0956 *
0957 * @see #isCachedMemory
0958 * @see #isCachedFile
0959 */
0960 boolean isCached();
0961
0962 /**
0963 * Returns <code>true</code> if this <code>ImageInputStream</code>
0964 * caches data itself in order to allow seeking backwards, and
0965 * the cache is kept in main memory. Applications may consult
0966 * this in order to decide how frequently, or whether, to flush
0967 * in order to conserve cache resources.
0968 *
0969 * @return <code>true</code> if this <code>ImageInputStream</code>
0970 * caches data in main memory.
0971 *
0972 * @see #isCached
0973 * @see #isCachedFile
0974 */
0975 boolean isCachedMemory();
0976
0977 /**
0978 * Returns <code>true</code> if this <code>ImageInputStream</code>
0979 * caches data itself in order to allow seeking backwards, and
0980 * the cache is kept in a temporary file. Applications may consult
0981 * this in order to decide how frequently, or whether, to flush
0982 * in order to conserve cache resources.
0983 *
0984 * @return <code>true</code> if this <code>ImageInputStream</code>
0985 * caches data in a temporary file.
0986 *
0987 * @see #isCached
0988 * @see #isCachedMemory
0989 */
0990 boolean isCachedFile();
0991
0992 /**
0993 * Closes the stream. Attempts to access a stream that has been
0994 * closed may result in <code>IOException</code>s or incorrect
0995 * behavior. Calling this method may allow classes implementing
0996 * this interface to release resources associated with the stream
0997 * such as memory, disk space, or file descriptors.
0998 *
0999 * @exception IOException if an I/O error occurs.
1000 */
1001 void close() throws IOException;
1002 }
|