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