103 * @exception IOException if an I/O error occurs. |
103 * @exception IOException if an I/O error occurs. |
104 */ |
104 */ |
105 int read() throws IOException; |
105 int read() throws IOException; |
106 |
106 |
107 /** |
107 /** |
108 * Reads up to <code>b.length</code> bytes from the stream, and |
108 * Reads up to {@code b.length} bytes from the stream, and |
109 * stores them into <code>b</code> starting at index 0. The |
109 * stores them into {@code b} starting at index 0. The |
110 * number of bytes read is returned. If no bytes can be read |
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. |
111 * because the end of the stream has been reached, -1 is returned. |
112 * |
112 * |
113 * <p> The bit offset within the stream is reset to zero before |
113 * <p> The bit offset within the stream is reset to zero before |
114 * the read occurs. |
114 * the read occurs. |
115 * |
115 * |
116 * @param b an array of bytes to be written to. |
116 * @param b an array of bytes to be written to. |
117 * |
117 * |
118 * @return the number of bytes actually read, or <code>-1</code> |
118 * @return the number of bytes actually read, or {@code -1} |
119 * to indicate EOF. |
119 * to indicate EOF. |
120 * |
120 * |
121 * @exception NullPointerException if <code>b</code> is |
121 * @exception NullPointerException if {@code b} is |
122 * <code>null</code>. |
122 * {@code null}. |
123 * |
123 * |
124 * @exception IOException if an I/O error occurs. |
124 * @exception IOException if an I/O error occurs. |
125 */ |
125 */ |
126 int read(byte[] b) throws IOException; |
126 int read(byte[] b) throws IOException; |
127 |
127 |
128 /** |
128 /** |
129 * Reads up to <code>len</code> bytes from the stream, and stores |
129 * Reads up to {@code len} bytes from the stream, and stores |
130 * them into <code>b</code> starting at index <code>off</code>. |
130 * them into {@code b} starting at index {@code off}. |
131 * The number of bytes read is returned. If no bytes can be read |
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> |
132 * because the end of the stream has been reached, {@code -1} |
133 * is returned. |
133 * is returned. |
134 * |
134 * |
135 * <p> The bit offset within the stream is reset to zero before |
135 * <p> The bit offset within the stream is reset to zero before |
136 * the read occurs. |
136 * the read occurs. |
137 * |
137 * |
138 * @param b an array of bytes to be written to. |
138 * @param b an array of bytes to be written to. |
139 * @param off the starting position within <code>b</code> to write to. |
139 * @param off the starting position within {@code b} to write to. |
140 * @param len the maximum number of <code>byte</code>s to read. |
140 * @param len the maximum number of {@code byte}s to read. |
141 * |
141 * |
142 * @return the number of bytes actually read, or <code>-1</code> |
142 * @return the number of bytes actually read, or {@code -1} |
143 * to indicate EOF. |
143 * to indicate EOF. |
144 * |
144 * |
145 * @exception NullPointerException if <code>b</code> is |
145 * @exception NullPointerException if {@code b} is |
146 * <code>null</code>. |
146 * {@code null}. |
147 * @exception IndexOutOfBoundsException if <code>off</code> is |
147 * @exception IndexOutOfBoundsException if {@code off} is |
148 * negative, <code>len</code> is negative, or <code>off + |
148 * negative, {@code len} is negative, or {@code off + len} |
149 * len</code> is greater than <code>b.length</code>. |
149 * is greater than {@code b.length}. |
150 * @exception IOException if an I/O error occurs. |
150 * @exception IOException if an I/O error occurs. |
151 */ |
151 */ |
152 int read(byte[] b, int off, int len) throws IOException; |
152 int read(byte[] b, int off, int len) throws IOException; |
153 |
153 |
154 /** |
154 /** |
155 * Reads up to <code>len</code> bytes from the stream, and |
155 * Reads up to {@code len} bytes from the stream, and |
156 * modifies the supplied <code>IIOByteBuffer</code> to indicate |
156 * modifies the supplied {@code IIOByteBuffer} to indicate |
157 * the byte array, offset, and length where the data may be found. |
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 |
158 * The caller should not attempt to modify the data found in the |
159 * <code>IIOByteBuffer</code>. |
159 * {@code IIOByteBuffer}. |
160 * |
160 * |
161 * <p> The bit offset within the stream is reset to zero before |
161 * <p> The bit offset within the stream is reset to zero before |
162 * the read occurs. |
162 * the read occurs. |
163 * |
163 * |
164 * @param buf an IIOByteBuffer object to be modified. |
164 * @param buf an IIOByteBuffer object to be modified. |
165 * @param len the maximum number of <code>byte</code>s to read. |
165 * @param len the maximum number of {@code byte}s to read. |
166 * |
166 * |
167 * @exception IndexOutOfBoundsException if <code>len</code> is |
167 * @exception IndexOutOfBoundsException if {@code len} is |
168 * negative. |
168 * negative. |
169 * @exception NullPointerException if <code>buf</code> is |
169 * @exception NullPointerException if {@code buf} is |
170 * <code>null</code>. |
170 * {@code null}. |
171 * |
171 * |
172 * @exception IOException if an I/O error occurs. |
172 * @exception IOException if an I/O error occurs. |
173 */ |
173 */ |
174 void readBytes(IIOByteBuffer buf, int len) throws IOException; |
174 void readBytes(IIOByteBuffer buf, int len) throws IOException; |
175 |
175 |
176 /** |
176 /** |
177 * Reads a byte from the stream and returns a <code>boolean</code> |
177 * Reads a byte from the stream and returns a {@code boolean} |
178 * value of <code>true</code> if it is nonzero, <code>false</code> |
178 * value of {@code true} if it is nonzero, {@code false} |
179 * if it is zero. |
179 * if it is zero. |
180 * |
180 * |
181 * <p> The bit offset within the stream is reset to zero before |
181 * <p> The bit offset within the stream is reset to zero before |
182 * the read occurs. |
182 * the read occurs. |
183 * |
183 * |
381 /** |
381 /** |
382 * Reads the next line of text from the input stream. It reads |
382 * Reads the next line of text from the input stream. It reads |
383 * successive bytes, converting each byte separately into a |
383 * successive bytes, converting each byte separately into a |
384 * character, until it encounters a line terminator or end of |
384 * character, until it encounters a line terminator or end of |
385 * file; the characters read are then returned as a |
385 * file; the characters read are then returned as a |
386 * <code>String</code>. Note that because this method processes |
386 * {@code String}. Note that because this method processes |
387 * bytes, it does not support input of the full Unicode character |
387 * bytes, it does not support input of the full Unicode character |
388 * set. |
388 * set. |
389 * |
389 * |
390 * <p> If end of file is encountered before even one byte can be |
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 |
391 * read, then {@code null} is returned. Otherwise, each byte |
392 * that is read is converted to type <code>char</code> by |
392 * that is read is converted to type {@code char} by |
393 * zero-extension. If the character <code>'\n'</code> is |
393 * zero-extension. If the character {@code '\n'} is |
394 * encountered, it is discarded and reading ceases. If the |
394 * encountered, it is discarded and reading ceases. If the |
395 * character <code>'\r'</code> is encountered, it is discarded |
395 * character {@code '\r'} is encountered, it is discarded |
396 * and, if the following byte converts  to the character |
396 * and, if the following byte converts  to the character |
397 * <code>'\n'</code>, then that is discarded also; reading then |
397 * {@code '\n'}, then that is discarded also; reading then |
398 * ceases. If end of file is encountered before either of the |
398 * ceases. If end of file is encountered before either of the |
399 * characters <code>'\n'</code> and <code>'\r'</code> is |
399 * characters {@code '\n'} and {@code '\r'} is |
400 * encountered, reading ceases. Once reading has ceased, a |
400 * encountered, reading ceases. Once reading has ceased, a |
401 * <code>String</code> is returned that contains all the |
401 * {@code String} is returned that contains all the |
402 * characters read and not discarded, taken in order. Note that |
402 * characters read and not discarded, taken in order. Note that |
403 * every character in this string will have a value less than |
403 * every character in this string will have a value less than |
404 * <code>\u0100</code>, that is, <code>(char)256</code>. |
404 * <code>\u0100</code>, that is, {@code (char)256}. |
405 * |
405 * |
406 * <p> The bit offset within the stream is reset to zero before |
406 * <p> The bit offset within the stream is reset to zero before |
407 * the read occurs. |
407 * the read occurs. |
408 * |
408 * |
409 * @return a String containing a line of text from the stream. |
409 * @return a String containing a line of text from the stream. |
414 |
414 |
415 /** |
415 /** |
416 * Reads in a string that has been encoded using a |
416 * Reads in a string that has been encoded using a |
417 * <a href="../../../java/io/DataInput.html#modified-utf-8">modified |
417 * <a href="../../../java/io/DataInput.html#modified-utf-8">modified |
418 * UTF-8</a> |
418 * UTF-8</a> |
419 * format. The general contract of <code>readUTF</code> is that |
419 * format. The general contract of {@code readUTF} is that |
420 * it reads a representation of a Unicode character string encoded |
420 * it reads a representation of a Unicode character string encoded |
421 * in modified UTF-8 format; this string of characters is |
421 * in modified UTF-8 format; this string of characters is |
422 * then returned as a <code>String</code>. |
422 * then returned as a {@code String}. |
423 * |
423 * |
424 * <p> First, two bytes are read and used to construct an unsigned |
424 * <p> First, two bytes are read and used to construct an unsigned |
425 * 16-bit integer in the manner of the |
425 * 16-bit integer in the manner of the |
426 * <code>readUnsignedShort</code> method, using network byte order |
426 * {@code readUnsignedShort} method, using network byte order |
427 * (regardless of the current byte order setting). This integer |
427 * (regardless of the current byte order setting). This integer |
428 * value is called the <i>UTF length</i> and specifies the number |
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 |
429 * of additional bytes to be read. These bytes are then converted |
430 * to characters by considering them in groups. The length of each |
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 |
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 |
432 * group. The byte following a group, if any, is the first byte of |
433 * the next group. |
433 * the next group. |
434 * |
434 * |
435 * <p> If the first byte of a group matches the bit pattern |
435 * <p> If the first byte of a group matches the bit pattern |
436 * <code>0xxxxxxx</code> (where <code>x</code> means "may be |
436 * {@code 0xxxxxxx} (where {@code x} means "may be |
437 * <code>0</code> or <code>1</code>"), then the group consists of |
437 * {@code 0} or {@code 1}"), then the group consists of |
438 * just that byte. The byte is zero-extended to form a character. |
438 * just that byte. The byte is zero-extended to form a character. |
439 * |
439 * |
440 * <p> If the first byte of a group matches the bit pattern |
440 * <p> If the first byte of a group matches the bit pattern |
441 * <code>110xxxxx</code>, then the group consists of that byte |
441 * {@code 110xxxxx}, then the group consists of that byte |
442 * <code>a</code> and a second byte <code>b</code>. If there is no |
442 * {@code a} and a second byte {@code b}. If there is no |
443 * byte <code>b</code> (because byte <code>a</code> was the last |
443 * byte {@code b} (because byte {@code a} was the last |
444 * of the bytes to be read), or if byte <code>b</code> does not |
444 * of the bytes to be read), or if byte {@code b} does not |
445 * match the bit pattern <code>10xxxxxx</code>, then a |
445 * match the bit pattern {@code 10xxxxxx}, then a |
446 * <code>UTFDataFormatException</code> is thrown. Otherwise, the |
446 * {@code UTFDataFormatException} is thrown. Otherwise, the |
447 * group is converted to the character: |
447 * group is converted to the character: |
448 * |
448 * |
449 * <pre><code> |
449 * <pre><code> |
450 * (char)(((a& 0x1F) << 6) | (b & 0x3F)) |
450 * (char)(((a& 0x1F) << 6) | (b & 0x3F)) |
451 * </code></pre> |
451 * </code></pre> |
452 * |
452 * |
453 * If the first byte of a group matches the bit pattern |
453 * If the first byte of a group matches the bit pattern |
454 * <code>1110xxxx</code>, then the group consists of that byte |
454 * {@code 1110xxxx}, then the group consists of that byte |
455 * <code>a</code> and two more bytes <code>b</code> and |
455 * {@code a} and two more bytes {@code b} and |
456 * <code>c</code>. If there is no byte <code>c</code> (because |
456 * {@code c}. If there is no byte {@code c} (because |
457 * byte <code>a</code> was one of the last two of the bytes to be |
457 * byte {@code a} was one of the last two of the bytes to be |
458 * read), or either byte <code>b</code> or byte <code>c</code> |
458 * read), or either byte {@code b} or byte {@code c} |
459 * does not match the bit pattern <code>10xxxxxx</code>, then a |
459 * does not match the bit pattern {@code 10xxxxxx}, then a |
460 * <code>UTFDataFormatException</code> is thrown. Otherwise, the |
460 * {@code UTFDataFormatException} is thrown. Otherwise, the |
461 * group is converted to the character: |
461 * group is converted to the character: |
462 * |
462 * |
463 * <pre><code> |
463 * <pre><code> |
464 * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F)) |
464 * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F)) |
465 * </code></pre> |
465 * </code></pre> |
466 * |
466 * |
467 * If the first byte of a group matches the pattern |
467 * If the first byte of a group matches the pattern |
468 * <code>1111xxxx</code> or the pattern <code>10xxxxxx</code>, |
468 * {@code 1111xxxx} or the pattern {@code 10xxxxxx}, |
469 * then a <code>UTFDataFormatException</code> is thrown. |
469 * then a {@code UTFDataFormatException} is thrown. |
470 * |
470 * |
471 * <p> If end of file is encountered at any time during this |
471 * <p> If end of file is encountered at any time during this |
472 * entire process, then an <code>java.io.EOFException</code> is thrown. |
472 * entire process, then an {@code java.io.EOFException} is thrown. |
473 * |
473 * |
474 * <p> After every group has been converted to a character by this |
474 * <p> After every group has been converted to a character by this |
475 * process, the characters are gathered, in the same order in |
475 * process, the characters are gathered, in the same order in |
476 * which their corresponding groups were read from the input |
476 * which their corresponding groups were read from the input |
477 * stream, to form a <code>String</code>, which is returned. |
477 * stream, to form a {@code String}, which is returned. |
478 * |
478 * |
479 * <p> The current byte order setting is ignored. |
479 * <p> The current byte order setting is ignored. |
480 * |
480 * |
481 * <p> The bit offset within the stream is reset to zero before |
481 * <p> The bit offset within the stream is reset to zero before |
482 * the read occurs. |
482 * the read occurs. |
495 * @exception IOException if an I/O error occurs. |
495 * @exception IOException if an I/O error occurs. |
496 */ |
496 */ |
497 String readUTF() throws IOException; |
497 String readUTF() throws IOException; |
498 |
498 |
499 /** |
499 /** |
500 * Reads <code>len</code> bytes from the stream, and stores them |
500 * Reads {@code len} bytes from the stream, and stores them |
501 * into <code>b</code> starting at index <code>off</code>. |
501 * into {@code b} starting at index {@code off}. |
502 * If the end of the stream is reached, an <code>java.io.EOFException</code> |
502 * If the end of the stream is reached, an {@code java.io.EOFException} |
503 * will be thrown. |
503 * will be thrown. |
504 * |
504 * |
505 * <p> The bit offset within the stream is reset to zero before |
505 * <p> The bit offset within the stream is reset to zero before |
506 * the read occurs. |
506 * the read occurs. |
507 * |
507 * |
508 * @param b an array of bytes to be written to. |
508 * @param b an array of bytes to be written to. |
509 * @param off the starting position within <code>b</code> to write to. |
509 * @param off the starting position within {@code b} to write to. |
510 * @param len the maximum number of <code>byte</code>s to read. |
510 * @param len the maximum number of {@code byte}s to read. |
511 * |
511 * |
512 * @exception IndexOutOfBoundsException if <code>off</code> is |
512 * @exception IndexOutOfBoundsException if {@code off} is |
513 * negative, <code>len</code> is negative, or <code>off + |
513 * negative, {@code len} is negative, or {@code off + len} |
514 * len</code> is greater than <code>b.length</code>. |
514 * is greater than {@code b.length}. |
515 * @exception NullPointerException if <code>b</code> is |
515 * @exception NullPointerException if {@code b} is |
516 * <code>null</code>. |
516 * {@code null}. |
517 * @exception java.io.EOFException if the stream reaches the end before |
517 * @exception java.io.EOFException if the stream reaches the end before |
518 * reading all the bytes. |
518 * reading all the bytes. |
519 * @exception IOException if an I/O error occurs. |
519 * @exception IOException if an I/O error occurs. |
520 */ |
520 */ |
521 void readFully(byte[] b, int off, int len) throws IOException; |
521 void readFully(byte[] b, int off, int len) throws IOException; |
522 |
522 |
523 /** |
523 /** |
524 * Reads <code>b.length</code> bytes from the stream, and stores them |
524 * Reads {@code b.length} bytes from the stream, and stores them |
525 * into <code>b</code> starting at index <code>0</code>. |
525 * into {@code b} starting at index {@code 0}. |
526 * If the end of the stream is reached, an <code>java.io.EOFException</code> |
526 * If the end of the stream is reached, an {@code java.io.EOFException} |
527 * will be thrown. |
527 * will be thrown. |
528 * |
528 * |
529 * <p> The bit offset within the stream is reset to zero before |
529 * <p> The bit offset within the stream is reset to zero before |
530 * the read occurs. |
530 * the read occurs. |
531 * |
531 * |
532 * @param b an array of <code>byte</code>s. |
532 * @param b an array of {@code byte}s. |
533 * |
533 * |
534 * @exception NullPointerException if <code>b</code> is |
534 * @exception NullPointerException if {@code b} is |
535 * <code>null</code>. |
535 * {@code null}. |
536 * @exception java.io.EOFException if the stream reaches the end before |
536 * @exception java.io.EOFException if the stream reaches the end before |
537 * reading all the bytes. |
537 * reading all the bytes. |
538 * @exception IOException if an I/O error occurs. |
538 * @exception IOException if an I/O error occurs. |
539 */ |
539 */ |
540 void readFully(byte[] b) throws IOException; |
540 void readFully(byte[] b) throws IOException; |
541 |
541 |
542 /** |
542 /** |
543 * Reads <code>len</code> shorts (signed 16-bit integers) from the |
543 * Reads {@code len} shorts (signed 16-bit integers) from the |
544 * stream according to the current byte order, and |
544 * stream according to the current byte order, and |
545 * stores them into <code>s</code> starting at index |
545 * stores them into {@code s} starting at index |
546 * <code>off</code>. If the end of the stream is reached, an |
546 * {@code off}. If the end of the stream is reached, an |
547 * <code>java.io.EOFException</code> will be thrown. |
547 * {@code java.io.EOFException} will be thrown. |
548 * |
548 * |
549 * <p> The bit offset within the stream is reset to zero before |
549 * <p> The bit offset within the stream is reset to zero before |
550 * the read occurs. |
550 * the read occurs. |
551 * |
551 * |
552 * @param s an array of shorts to be written to. |
552 * @param s an array of shorts to be written to. |
553 * @param off the starting position within <code>s</code> to write to. |
553 * @param off the starting position within {@code s} to write to. |
554 * @param len the maximum number of <code>short</code>s to read. |
554 * @param len the maximum number of {@code short}s to read. |
555 * |
555 * |
556 * @exception IndexOutOfBoundsException if <code>off</code> is |
556 * @exception IndexOutOfBoundsException if {@code off} is |
557 * negative, <code>len</code> is negative, or <code>off + |
557 * negative, {@code len} is negative, or {@code off + len} |
558 * len</code> is greater than <code>s.length</code>. |
558 * is greater than {@code s.length}. |
559 * @exception NullPointerException if <code>s</code> is |
559 * @exception NullPointerException if {@code s} is |
560 * <code>null</code>. |
560 * {@code null}. |
561 * @exception java.io.EOFException if the stream reaches the end before |
561 * @exception java.io.EOFException if the stream reaches the end before |
562 * reading all the bytes. |
562 * reading all the bytes. |
563 * @exception IOException if an I/O error occurs. |
563 * @exception IOException if an I/O error occurs. |
564 */ |
564 */ |
565 void readFully(short[] s, int off, int len) throws IOException; |
565 void readFully(short[] s, int off, int len) throws IOException; |
566 |
566 |
567 /** |
567 /** |
568 * Reads <code>len</code> chars (unsigned 16-bit integers) from the |
568 * Reads {@code len} chars (unsigned 16-bit integers) from the |
569 * stream according to the current byte order, and |
569 * stream according to the current byte order, and |
570 * stores them into <code>c</code> starting at index |
570 * stores them into {@code c} starting at index |
571 * <code>off</code>. If the end of the stream is reached, an |
571 * {@code off}. If the end of the stream is reached, an |
572 * <code>java.io.EOFException</code> will be thrown. |
572 * {@code java.io.EOFException} will be thrown. |
573 * |
573 * |
574 * <p> The bit offset within the stream is reset to zero before |
574 * <p> The bit offset within the stream is reset to zero before |
575 * the read occurs. |
575 * the read occurs. |
576 * |
576 * |
577 * @param c an array of chars to be written to. |
577 * @param c an array of chars to be written to. |
578 * @param off the starting position within <code>c</code> to write to. |
578 * @param off the starting position within {@code c} to write to. |
579 * @param len the maximum number of <code>char</code>s to read. |
579 * @param len the maximum number of {@code char}s to read. |
580 * |
580 * |
581 * @exception IndexOutOfBoundsException if <code>off</code> is |
581 * @exception IndexOutOfBoundsException if {@code off} is |
582 * negative, <code>len</code> is negative, or <code>off + |
582 * negative, {@code len} is negative, or {@code off + len} |
583 * len</code> is greater than <code>c.length</code>. |
583 * is greater than {@code c.length}. |
584 * @exception NullPointerException if <code>c</code> is |
584 * @exception NullPointerException if {@code c} is |
585 * <code>null</code>. |
585 * {@code null}. |
586 * @exception java.io.EOFException if the stream reaches the end before |
586 * @exception java.io.EOFException if the stream reaches the end before |
587 * reading all the bytes. |
587 * reading all the bytes. |
588 * @exception IOException if an I/O error occurs. |
588 * @exception IOException if an I/O error occurs. |
589 */ |
589 */ |
590 void readFully(char[] c, int off, int len) throws IOException; |
590 void readFully(char[] c, int off, int len) throws IOException; |
591 |
591 |
592 /** |
592 /** |
593 * Reads <code>len</code> ints (signed 32-bit integers) from the |
593 * Reads {@code len} ints (signed 32-bit integers) from the |
594 * stream according to the current byte order, and |
594 * stream according to the current byte order, and |
595 * stores them into <code>i</code> starting at index |
595 * stores them into {@code i} starting at index |
596 * <code>off</code>. If the end of the stream is reached, an |
596 * {@code off}. If the end of the stream is reached, an |
597 * <code>java.io.EOFException</code> will be thrown. |
597 * {@code java.io.EOFException} will be thrown. |
598 * |
598 * |
599 * <p> The bit offset within the stream is reset to zero before |
599 * <p> The bit offset within the stream is reset to zero before |
600 * the read occurs. |
600 * the read occurs. |
601 * |
601 * |
602 * @param i an array of ints to be written to. |
602 * @param i an array of ints to be written to. |
603 * @param off the starting position within <code>i</code> to write to. |
603 * @param off the starting position within {@code i} to write to. |
604 * @param len the maximum number of <code>int</code>s to read. |
604 * @param len the maximum number of {@code int}s to read. |
605 * |
605 * |
606 * @exception IndexOutOfBoundsException if <code>off</code> is |
606 * @exception IndexOutOfBoundsException if {@code off} is |
607 * negative, <code>len</code> is negative, or <code>off + |
607 * negative, {@code len} is negative, or {@code off + len} |
608 * len</code> is greater than <code>i.length</code>. |
608 * is greater than {@code i.length}. |
609 * @exception NullPointerException if <code>i</code> is |
609 * @exception NullPointerException if {@code i} is |
610 * <code>null</code>. |
610 * {@code null}. |
611 * @exception java.io.EOFException if the stream reaches the end before |
611 * @exception java.io.EOFException if the stream reaches the end before |
612 * reading all the bytes. |
612 * reading all the bytes. |
613 * @exception IOException if an I/O error occurs. |
613 * @exception IOException if an I/O error occurs. |
614 */ |
614 */ |
615 void readFully(int[] i, int off, int len) throws IOException; |
615 void readFully(int[] i, int off, int len) throws IOException; |
616 |
616 |
617 /** |
617 /** |
618 * Reads <code>len</code> longs (signed 64-bit integers) from the |
618 * Reads {@code len} longs (signed 64-bit integers) from the |
619 * stream according to the current byte order, and |
619 * stream according to the current byte order, and |
620 * stores them into <code>l</code> starting at index |
620 * stores them into {@code l} starting at index |
621 * <code>off</code>. If the end of the stream is reached, an |
621 * {@code off}. If the end of the stream is reached, an |
622 * <code>java.io.EOFException</code> will be thrown. |
622 * {@code java.io.EOFException} will be thrown. |
623 * |
623 * |
624 * <p> The bit offset within the stream is reset to zero before |
624 * <p> The bit offset within the stream is reset to zero before |
625 * the read occurs. |
625 * the read occurs. |
626 * |
626 * |
627 * @param l an array of longs to be written to. |
627 * @param l an array of longs to be written to. |
628 * @param off the starting position within <code>l</code> to write to. |
628 * @param off the starting position within {@code l} to write to. |
629 * @param len the maximum number of <code>long</code>s to read. |
629 * @param len the maximum number of {@code long}s to read. |
630 * |
630 * |
631 * @exception IndexOutOfBoundsException if <code>off</code> is |
631 * @exception IndexOutOfBoundsException if {@code off} is |
632 * negative, <code>len</code> is negative, or <code>off + |
632 * negative, {@code len} is negative, or {@code off + len} |
633 * len</code> is greater than <code>l.length</code>. |
633 * is greater than {@code l.length}. |
634 * @exception NullPointerException if <code>l</code> is |
634 * @exception NullPointerException if {@code l} is |
635 * <code>null</code>. |
635 * {@code null}. |
636 * @exception java.io.EOFException if the stream reaches the end before |
636 * @exception java.io.EOFException if the stream reaches the end before |
637 * reading all the bytes. |
637 * reading all the bytes. |
638 * @exception IOException if an I/O error occurs. |
638 * @exception IOException if an I/O error occurs. |
639 */ |
639 */ |
640 void readFully(long[] l, int off, int len) throws IOException; |
640 void readFully(long[] l, int off, int len) throws IOException; |
641 |
641 |
642 /** |
642 /** |
643 * Reads <code>len</code> floats (32-bit IEEE single-precision |
643 * Reads {@code len} floats (32-bit IEEE single-precision |
644 * floats) from the stream according to the current byte order, |
644 * floats) from the stream according to the current byte order, |
645 * and stores them into <code>f</code> starting at |
645 * and stores them into {@code f} starting at |
646 * index <code>off</code>. If the end of the stream is reached, |
646 * index {@code off}. If the end of the stream is reached, |
647 * an <code>java.io.EOFException</code> will be thrown. |
647 * an {@code java.io.EOFException} will be thrown. |
648 * |
648 * |
649 * <p> The bit offset within the stream is reset to zero before |
649 * <p> The bit offset within the stream is reset to zero before |
650 * the read occurs. |
650 * the read occurs. |
651 * |
651 * |
652 * @param f an array of floats to be written to. |
652 * @param f an array of floats to be written to. |
653 * @param off the starting position within <code>f</code> to write to. |
653 * @param off the starting position within {@code f} to write to. |
654 * @param len the maximum number of <code>float</code>s to read. |
654 * @param len the maximum number of {@code float}s to read. |
655 * |
655 * |
656 * @exception IndexOutOfBoundsException if <code>off</code> is |
656 * @exception IndexOutOfBoundsException if {@code off} is |
657 * negative, <code>len</code> is negative, or <code>off + |
657 * negative, {@code len} is negative, or {@code off + len} |
658 * len</code> is greater than <code>f.length</code>. |
658 * is greater than {@code f.length}. |
659 * @exception NullPointerException if <code>f</code> is |
659 * @exception NullPointerException if {@code f} is |
660 * <code>null</code>. |
660 * {@code null}. |
661 * @exception java.io.EOFException if the stream reaches the end before |
661 * @exception java.io.EOFException if the stream reaches the end before |
662 * reading all the bytes. |
662 * reading all the bytes. |
663 * @exception IOException if an I/O error occurs. |
663 * @exception IOException if an I/O error occurs. |
664 */ |
664 */ |
665 void readFully(float[] f, int off, int len) throws IOException; |
665 void readFully(float[] f, int off, int len) throws IOException; |
666 |
666 |
667 /** |
667 /** |
668 * Reads <code>len</code> doubles (64-bit IEEE double-precision |
668 * Reads {@code len} doubles (64-bit IEEE double-precision |
669 * floats) from the stream according to the current byte order, |
669 * floats) from the stream according to the current byte order, |
670 * and stores them into <code>d</code> starting at |
670 * and stores them into {@code d} starting at |
671 * index <code>off</code>. If the end of the stream is reached, |
671 * index {@code off}. If the end of the stream is reached, |
672 * an <code>java.io.EOFException</code> will be thrown. |
672 * an {@code java.io.EOFException} will be thrown. |
673 * |
673 * |
674 * <p> The bit offset within the stream is reset to zero before |
674 * <p> The bit offset within the stream is reset to zero before |
675 * the read occurs. |
675 * the read occurs. |
676 * |
676 * |
677 * @param d an array of doubles to be written to. |
677 * @param d an array of doubles to be written to. |
678 * @param off the starting position within <code>d</code> to write to. |
678 * @param off the starting position within {@code d} to write to. |
679 * @param len the maximum number of <code>double</code>s to read. |
679 * @param len the maximum number of {@code double}s to read. |
680 * |
680 * |
681 * @exception IndexOutOfBoundsException if <code>off</code> is |
681 * @exception IndexOutOfBoundsException if {@code off} is |
682 * negative, <code>len</code> is negative, or <code>off + |
682 * negative, {@code len} is negative, or {@code off + len} |
683 * len</code> is greater than <code>d.length</code>. |
683 * is greater than {@code d.length}. |
684 * @exception NullPointerException if <code>d</code> is |
684 * @exception NullPointerException if {@code d} is |
685 * <code>null</code>. |
685 * {@code null}. |
686 * @exception java.io.EOFException if the stream reaches the end before |
686 * @exception java.io.EOFException if the stream reaches the end before |
687 * reading all the bytes. |
687 * reading all the bytes. |
688 * @exception IOException if an I/O error occurs. |
688 * @exception IOException if an I/O error occurs. |
689 */ |
689 */ |
690 void readFully(double[] d, int off, int len) throws IOException; |
690 void readFully(double[] d, int off, int len) throws IOException; |
721 int getBitOffset() throws IOException; |
721 int getBitOffset() throws IOException; |
722 |
722 |
723 /** |
723 /** |
724 * Sets the bit offset to an integer between 0 and 7, inclusive. |
724 * Sets the bit offset to an integer between 0 and 7, inclusive. |
725 * The byte offset within the stream, as returned by |
725 * The byte offset within the stream, as returned by |
726 * <code>getStreamPosition</code>, is left unchanged. |
726 * {@code getStreamPosition}, is left unchanged. |
727 * A value of 0 indicates the |
727 * A value of 0 indicates the |
728 * most-significant bit, and a value of 7 indicates the least |
728 * most-significant bit, and a value of 7 indicates the least |
729 * significant bit, of the byte being read. |
729 * significant bit, of the byte being read. |
730 * |
730 * |
731 * @param bitOffset the desired offset, as an <code>int</code> |
731 * @param bitOffset the desired offset, as an {@code int} |
732 * between 0 and 7, inclusive. |
732 * between 0 and 7, inclusive. |
733 * |
733 * |
734 * @exception IllegalArgumentException if <code>bitOffset</code> |
734 * @exception IllegalArgumentException if {@code bitOffset} |
735 * is not between 0 and 7, inclusive. |
735 * is not between 0 and 7, inclusive. |
736 * @exception IOException if an I/O error occurs. |
736 * @exception IOException if an I/O error occurs. |
737 * |
737 * |
738 * @see #getBitOffset |
738 * @see #getBitOffset |
739 */ |
739 */ |
740 void setBitOffset(int bitOffset) throws IOException; |
740 void setBitOffset(int bitOffset) throws IOException; |
741 |
741 |
742 /** |
742 /** |
743 * Reads a single bit from the stream and returns it as an |
743 * Reads a single bit from the stream and returns it as an |
744 * <code>int</code> with the value <code>0</code> or |
744 * {@code int} with the value {@code 0} or |
745 * <code>1</code>. The bit offset is advanced by one and reduced |
745 * {@code 1}. The bit offset is advanced by one and reduced |
746 * modulo 8. |
746 * modulo 8. |
747 * |
747 * |
748 * @return an <code>int</code> containing the value <code>0</code> |
748 * @return an {@code int} containing the value {@code 0} |
749 * or <code>1</code>. |
749 * or {@code 1}. |
750 * |
750 * |
751 * @exception java.io.EOFException if the stream reaches the end before |
751 * @exception java.io.EOFException if the stream reaches the end before |
752 * reading all the bits. |
752 * reading all the bits. |
753 * @exception IOException if an I/O error occurs. |
753 * @exception IOException if an I/O error occurs. |
754 */ |
754 */ |
755 int readBit() throws IOException; |
755 int readBit() throws IOException; |
756 |
756 |
757 /** |
757 /** |
758 * Reads a bitstring from the stream and returns it as a |
758 * Reads a bitstring from the stream and returns it as a |
759 * <code>long</code>, with the first bit read becoming the most |
759 * {@code long}, with the first bit read becoming the most |
760 * significant bit of the output. The read starts within the byte |
760 * significant bit of the output. The read starts within the byte |
761 * indicated by <code>getStreamPosition</code>, at the bit given |
761 * indicated by {@code getStreamPosition}, at the bit given |
762 * by <code>getBitOffset</code>. The bit offset is advanced by |
762 * by {@code getBitOffset}. The bit offset is advanced by |
763 * <code>numBits</code> and reduced modulo 8. |
763 * {@code numBits} and reduced modulo 8. |
764 * |
764 * |
765 * <p> The byte order of the stream has no effect on this |
765 * <p> The byte order of the stream has no effect on this |
766 * method. The return value of this method is constructed as |
766 * method. The return value of this method is constructed as |
767 * though the bits were read one at a time, and shifted into |
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 |
768 * the right side of the return value, as shown by the following |
843 /** |
842 /** |
844 * Sets the current stream position to the desired location. The |
843 * Sets the current stream position to the desired location. The |
845 * next read will occur at this location. The bit offset is set |
844 * next read will occur at this location. The bit offset is set |
846 * to 0. |
845 * to 0. |
847 * |
846 * |
848 * <p> An <code>IndexOutOfBoundsException</code> will be thrown if |
847 * <p> An {@code IndexOutOfBoundsException} will be thrown if |
849 * <code>pos</code> is smaller than the flushed position (as |
848 * {@code pos} is smaller than the flushed position (as |
850 * returned by <code>getflushedPosition</code>). |
849 * returned by {@code getflushedPosition}). |
851 * |
850 * |
852 * <p> It is legal to seek past the end of the file; an |
851 * <p> It is legal to seek past the end of the file; an |
853 * <code>java.io.EOFException</code> will be thrown only if a read is |
852 * {@code java.io.EOFException} will be thrown only if a read is |
854 * performed. |
853 * performed. |
855 * |
854 * |
856 * @param pos a <code>long</code> containing the desired file |
855 * @param pos a {@code long} containing the desired file |
857 * pointer position. |
856 * pointer position. |
858 * |
857 * |
859 * @exception IndexOutOfBoundsException if <code>pos</code> is smaller |
858 * @exception IndexOutOfBoundsException if {@code pos} is smaller |
860 * than the flushed position. |
859 * than the flushed position. |
861 * @exception IOException if any other I/O error occurs. |
860 * @exception IOException if any other I/O error occurs. |
862 */ |
861 */ |
863 void seek(long pos) throws IOException; |
862 void seek(long pos) throws IOException; |
864 |
863 |
865 /** |
864 /** |
866 * Marks a position in the stream to be returned to by a |
865 * Marks a position in the stream to be returned to by a |
867 * subsequent call to <code>reset</code>. Unlike a standard |
866 * subsequent call to {@code reset}. Unlike a standard |
868 * <code>InputStream</code>, all <code>ImageInputStream</code>s |
867 * {@code InputStream}, all {@code ImageInputStream}s |
869 * support marking. Additionally, calls to <code>mark</code> and |
868 * support marking. Additionally, calls to {@code mark} and |
870 * <code>reset</code> may be nested arbitrarily. |
869 * {@code reset} may be nested arbitrarily. |
871 * |
870 * |
872 * <p> Unlike the <code>mark</code> methods declared by the |
871 * <p> Unlike the {@code mark} methods declared by the |
873 * <code>Reader</code> and <code>InputStream</code> interfaces, no |
872 * {@code Reader} and {@code InputStream} interfaces, no |
874 * <code>readLimit</code> parameter is used. An arbitrary amount |
873 * {@code readLimit} parameter is used. An arbitrary amount |
875 * of data may be read following the call to <code>mark</code>. |
874 * of data may be read following the call to {@code mark}. |
876 * |
875 * |
877 * <p> The bit position used by the <code>readBits</code> method |
876 * <p> The bit position used by the {@code readBits} method |
878 * is saved and restored by each pair of calls to |
877 * is saved and restored by each pair of calls to |
879 * <code>mark</code> and <code>reset</code>. |
878 * {@code mark} and {@code reset}. |
880 * |
879 * |
881 * <p> Note that it is valid for an <code>ImageReader</code> to call |
880 * <p> Note that it is valid for an {@code ImageReader} to call |
882 * <code>flushBefore</code> as part of a read operation. |
881 * {@code flushBefore} as part of a read operation. |
883 * Therefore, if an application calls <code>mark</code> prior to |
882 * Therefore, if an application calls {@code mark} prior to |
884 * passing that stream to an <code>ImageReader</code>, the application |
883 * passing that stream to an {@code ImageReader}, the application |
885 * should not assume that the marked position will remain valid after |
884 * should not assume that the marked position will remain valid after |
886 * the read operation has completed. |
885 * the read operation has completed. |
887 */ |
886 */ |
888 void mark(); |
887 void mark(); |
889 |
888 |
890 /** |
889 /** |
891 * Returns the stream pointer to its previous position, including |
890 * Returns the stream pointer to its previous position, including |
892 * the bit offset, at the time of the most recent unmatched call |
891 * the bit offset, at the time of the most recent unmatched call |
893 * to <code>mark</code>. |
892 * to {@code mark}. |
894 * |
893 * |
895 * <p> Calls to <code>reset</code> without a corresponding call |
894 * <p> Calls to {@code reset} without a corresponding call |
896 * to <code>mark</code> have no effect. |
895 * to {@code mark} have no effect. |
897 * |
896 * |
898 * <p> An <code>IOException</code> will be thrown if the previous |
897 * <p> An {@code IOException} will be thrown if the previous |
899 * marked position lies in the discarded portion of the stream. |
898 * marked position lies in the discarded portion of the stream. |
900 * |
899 * |
901 * @exception IOException if an I/O error occurs. |
900 * @exception IOException if an I/O error occurs. |
902 */ |
901 */ |
903 void reset() throws IOException; |
902 void reset() throws IOException; |
904 |
903 |
905 /** |
904 /** |
906 * Discards the initial portion of the stream prior to the |
905 * Discards the initial portion of the stream prior to the |
907 * indicated position. Attempting to seek to an offset within the |
906 * indicated position. Attempting to seek to an offset within the |
908 * flushed portion of the stream will result in an |
907 * flushed portion of the stream will result in an |
909 * <code>IndexOutOfBoundsException</code>. |
908 * {@code IndexOutOfBoundsException}. |
910 * |
909 * |
911 * <p> Calling <code>flushBefore</code> may allow classes |
910 * <p> Calling {@code flushBefore} may allow classes |
912 * implementing this interface to free up resources such as memory |
911 * implementing this interface to free up resources such as memory |
913 * or disk space that are being used to store data from the |
912 * or disk space that are being used to store data from the |
914 * stream. |
913 * stream. |
915 * |
914 * |
916 * @param pos a <code>long</code> containing the length of the |
915 * @param pos a {@code long} containing the length of the |
917 * stream prefix that may be flushed. |
916 * stream prefix that may be flushed. |
918 * |
917 * |
919 * @exception IndexOutOfBoundsException if <code>pos</code> lies |
918 * @exception IndexOutOfBoundsException if {@code pos} lies |
920 * in the flushed portion of the stream or past the current stream |
919 * in the flushed portion of the stream or past the current stream |
921 * position. |
920 * position. |
922 * @exception IOException if an I/O error occurs. |
921 * @exception IOException if an I/O error occurs. |
923 */ |
922 */ |
924 void flushBefore(long pos) throws IOException; |
923 void flushBefore(long pos) throws IOException; |
925 |
924 |
926 /** |
925 /** |
927 * Discards the initial position of the stream prior to the current |
926 * Discards the initial position of the stream prior to the current |
928 * stream position. Equivalent to |
927 * stream position. Equivalent to |
929 * <code>flushBefore(getStreamPosition())</code>. |
928 * {@code flushBefore(getStreamPosition())}. |
930 * |
929 * |
931 * @exception IOException if an I/O error occurs. |
930 * @exception IOException if an I/O error occurs. |
932 */ |
931 */ |
933 void flush() throws IOException; |
932 void flush() throws IOException; |
934 |
933 |
935 /** |
934 /** |
936 * Returns the earliest position in the stream to which seeking |
935 * Returns the earliest position in the stream to which seeking |
937 * may be performed. The returned value will be the maximum of |
936 * may be performed. The returned value will be the maximum of |
938 * all values passed into previous calls to |
937 * all values passed into previous calls to |
939 * <code>flushBefore</code>. |
938 * {@code flushBefore}. |
940 * |
939 * |
941 * @return the earliest legal position for seeking, as a |
940 * @return the earliest legal position for seeking, as a |
942 * <code>long</code>. |
941 * {@code long}. |
943 */ |
942 */ |
944 long getFlushedPosition(); |
943 long getFlushedPosition(); |
945 |
944 |
946 /** |
945 /** |
947 * Returns <code>true</code> if this <code>ImageInputStream</code> |
946 * Returns {@code true} if this {@code ImageInputStream} |
948 * caches data itself in order to allow seeking backwards. |
947 * caches data itself in order to allow seeking backwards. |
949 * Applications may consult this in order to decide how frequently, |
948 * Applications may consult this in order to decide how frequently, |
950 * or whether, to flush in order to conserve cache resources. |
949 * or whether, to flush in order to conserve cache resources. |
951 * |
950 * |
952 * @return <code>true</code> if this <code>ImageInputStream</code> |
951 * @return {@code true} if this {@code ImageInputStream} |
953 * caches data. |
952 * caches data. |
954 * |
953 * |
955 * @see #isCachedMemory |
954 * @see #isCachedMemory |
956 * @see #isCachedFile |
955 * @see #isCachedFile |
957 */ |
956 */ |
958 boolean isCached(); |
957 boolean isCached(); |
959 |
958 |
960 /** |
959 /** |
961 * Returns <code>true</code> if this <code>ImageInputStream</code> |
960 * Returns {@code true} if this {@code ImageInputStream} |
962 * caches data itself in order to allow seeking backwards, and |
961 * caches data itself in order to allow seeking backwards, and |
963 * the cache is kept in main memory. Applications may consult |
962 * the cache is kept in main memory. Applications may consult |
964 * this in order to decide how frequently, or whether, to flush |
963 * this in order to decide how frequently, or whether, to flush |
965 * in order to conserve cache resources. |
964 * in order to conserve cache resources. |
966 * |
965 * |
967 * @return <code>true</code> if this <code>ImageInputStream</code> |
966 * @return {@code true} if this {@code ImageInputStream} |
968 * caches data in main memory. |
967 * caches data in main memory. |
969 * |
968 * |
970 * @see #isCached |
969 * @see #isCached |
971 * @see #isCachedFile |
970 * @see #isCachedFile |
972 */ |
971 */ |
973 boolean isCachedMemory(); |
972 boolean isCachedMemory(); |
974 |
973 |
975 /** |
974 /** |
976 * Returns <code>true</code> if this <code>ImageInputStream</code> |
975 * Returns {@code true} if this {@code ImageInputStream} |
977 * caches data itself in order to allow seeking backwards, and |
976 * caches data itself in order to allow seeking backwards, and |
978 * the cache is kept in a temporary file. Applications may consult |
977 * the cache is kept in a temporary file. Applications may consult |
979 * this in order to decide how frequently, or whether, to flush |
978 * this in order to decide how frequently, or whether, to flush |
980 * in order to conserve cache resources. |
979 * in order to conserve cache resources. |
981 * |
980 * |
982 * @return <code>true</code> if this <code>ImageInputStream</code> |
981 * @return {@code true} if this {@code ImageInputStream} |
983 * caches data in a temporary file. |
982 * caches data in a temporary file. |
984 * |
983 * |
985 * @see #isCached |
984 * @see #isCached |
986 * @see #isCachedMemory |
985 * @see #isCachedMemory |
987 */ |
986 */ |
988 boolean isCachedFile(); |
987 boolean isCachedFile(); |
989 |
988 |
990 /** |
989 /** |
991 * Closes the stream. Attempts to access a stream that has been |
990 * Closes the stream. Attempts to access a stream that has been |
992 * closed may result in <code>IOException</code>s or incorrect |
991 * closed may result in {@code IOException}s or incorrect |
993 * behavior. Calling this method may allow classes implementing |
992 * behavior. Calling this method may allow classes implementing |
994 * this interface to release resources associated with the stream |
993 * this interface to release resources associated with the stream |
995 * such as memory, disk space, or file descriptors. |
994 * such as memory, disk space, or file descriptors. |
996 * |
995 * |
997 * @exception IOException if an I/O error occurs. |
996 * @exception IOException if an I/O error occurs. |