1 /*

     2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.imageio.stream;

    27 

    28 import java.io.Closeable;

    29 import java.io.DataInput;

    30 import java.io.IOException;

    31 import java.nio.ByteOrder;

    32 

    33 /**

    34  * A seekable input stream interface for use by

    35  * <code>ImageReader</code>s.  Various input sources, such as

    36  * <code>InputStream</code>s and <code>File</code>s,

    37  * as well as future fast I/O sources may be "wrapped" by a suitable

    38  * implementation of this interface for use by the Image I/O API.

    39  *

    40  * @see ImageInputStreamImpl

    41  * @see FileImageInputStream

    42  * @see FileCacheImageInputStream

    43  * @see MemoryCacheImageInputStream

    44  *

    45  */

    46 public interface ImageInputStream extends DataInput, Closeable {

    47 

    48     /**

    49      * Sets the desired byte order for future reads of data values

    50      * from this stream.  For example, the sequence of bytes '0x01

    51      * 0x02 0x03 0x04' if read as a 4-byte integer would have the

    52      * value '0x01020304' using network byte order and the value

    53      * '0x04030201' under the reverse byte order.

    54      *

    55      * <p> The enumeration class <code>java.nio.ByteOrder</code> is

    56      * used to specify the byte order.  A value of

    57      * <code>ByteOrder.BIG_ENDIAN</code> specifies so-called

    58      * big-endian or network byte order, in which the high-order byte

    59      * comes first.  Motorola and Sparc processors store data in this

    60      * format, while Intel processors store data in the reverse

    61      * <code>ByteOrder.LITTLE_ENDIAN</code> order.

    62      *

    63      * <p> The byte order has no effect on the results returned from

    64      * the <code>readBits</code> method (or the value written by

    65      * <code>ImageOutputStream.writeBits</code>).

    66      *

    67      * @param byteOrder one of <code>ByteOrder.BIG_ENDIAN</code> or

    68      * <code>java.nio.ByteOrder.LITTLE_ENDIAN</code>, indicating whether

    69      * network byte order or its reverse will be used for future

    70      * reads.

    71      *

    72      * @see java.nio.ByteOrder

    73      * @see #getByteOrder

    74      * @see #readBits(int)

    75      */

    76     void setByteOrder(ByteOrder byteOrder);

    77 

    78     /**

    79      * Returns the byte order with which data values will be read from

    80      * this stream as an instance of the

    81      * <code>java.nio.ByteOrder</code> enumeration.

    82      *

    83      * @return one of <code>ByteOrder.BIG_ENDIAN</code> or

    84      * <code>ByteOrder.LITTLE_ENDIAN</code>, indicating which byte

    85      * order is being used.

    86      *

    87      * @see java.nio.ByteOrder

    88      * @see #setByteOrder

    89      */

    90     ByteOrder getByteOrder();

    91 

    92     /**

    93      * Reads a single byte from the stream and returns it as an

    94      * integer between 0 and 255.  If the end of the stream is

    95      * reached, -1 is returned.

    96      *

    97      * <p> The bit offset within the stream is reset to zero before

    98      * the read occurs.

    99      *

   100      * @return a byte value from the stream, as an int, or -1 to

   101      * indicate EOF.

   102      *

   103      * @exception IOException if an I/O error occurs.

   104      */

   105     int read() throws IOException;

   106 

   107     /**

   108      * Reads up to <code>b.length</code> bytes from the stream, and

   109      * stores them into <code>b</code> starting at index 0.  The

   110      * number of bytes read is returned.  If no bytes can be read

   111      * because the end of the stream has been reached, -1 is returned.

   112      *

   113      * <p> The bit offset within the stream is reset to zero before

   114      * the read occurs.

   115      *

   116      * @param b an array of bytes to be written to.

   117      *

   118      * @return the number of bytes actually read, or <code>-1</code>

   119      * to indicate EOF.

   120      *

   121      * @exception NullPointerException if <code>b</code> is

   122      * <code>null</code>.

   123      *

   124      * @exception IOException if an I/O error occurs.

   125      */

   126     int read(byte[] b) throws IOException;

   127 

   128     /**

   129      * Reads up to <code>len</code> bytes from the stream, and stores

   130      * them into <code>b</code> starting at index <code>off</code>.

   131      * The number of bytes read is returned.  If no bytes can be read

   132      * because the end of the stream has been reached, <code>-1</code>

   133      * is returned.

   134      *

   135      * <p> The bit offset within the stream is reset to zero before

   136      * the read occurs.

   137      *

   138      * @param b an array of bytes to be written to.

   139      * @param off the starting position within <code>b</code> to write to.

   140      * @param len the maximum number of <code>byte</code>s to read.

   141      *

   142      * @return the number of bytes actually read, or <code>-1</code>

   143      * to indicate EOF.

   144      *

   145      * @exception NullPointerException if <code>b</code> is

   146      * <code>null</code>.

   147      * @exception IndexOutOfBoundsException if <code>off</code> is

   148      * negative, <code>len</code> is negative, or <code>off +

   149      * len</code> is greater than <code>b.length</code>.

   150      * @exception IOException if an I/O error occurs.

   151      */

   152     int read(byte[] b, int off, int len) throws IOException;

   153 

   154     /**

   155      * Reads up to <code>len</code> bytes from the stream, and

   156      * modifies the supplied <code>IIOByteBuffer</code> to indicate

   157      * the byte array, offset, and length where the data may be found.

   158      * The caller should not attempt to modify the data found in the

   159      * <code>IIOByteBuffer</code>.

   160      *

   161      * <p> The bit offset within the stream is reset to zero before

   162      * the read occurs.

   163      *

   164      * @param buf an IIOByteBuffer object to be modified.

   165      * @param len the maximum number of <code>byte</code>s to read.

   166      *

   167      * @exception IndexOutOfBoundsException if <code>len</code> is

   168      * negative.

   169      * @exception NullPointerException if <code>buf</code> is

   170      * <code>null</code>.

   171      *

   172      * @exception IOException if an I/O error occurs.

   173      */

   174     void readBytes(IIOByteBuffer buf, int len) throws IOException;

   175 

   176     /**

   177      * Reads a byte from the stream and returns a <code>boolean</code>

   178      * value of <code>true</code> if it is nonzero, <code>false</code>

   179      * if it is zero.

   180      *

   181      * <p> The bit offset within the stream is reset to zero before

   182      * the read occurs.

   183      *

   184      * @return a boolean value from the stream.

   185      *

   186      * @exception java.io.EOFException if the end of the stream is reached.

   187      * @exception IOException if an I/O error occurs.

   188      */

   189     boolean readBoolean() throws IOException;

   190 

   191     /**

   192      * Reads a byte from the stream and returns it as a

   193      * <code>byte</code> value.  Byte values between <code>0x00</code>

   194      * and <code>0x7f</code> represent integer values between

   195      * <code>0</code> and <code>127</code>.  Values between

   196      * <code>0x80</code> and <code>0xff</code> represent negative

   197      * values from <code>-128</code> to <code>/1</code>.

   198      *

   199      * <p> The bit offset within the stream is reset to zero before

   200      * the read occurs.

   201      *

   202      * @return a signed byte value from the stream.

   203      *

   204      * @exception java.io.EOFException if the end of the stream is reached.

   205      * @exception IOException if an I/O error occurs.

   206      */

   207     byte readByte() throws IOException;

   208 

   209     /**

   210      * Reads a byte from the stream, and (conceptually) converts it to

   211      * an int, masks it with <code>0xff</code> in order to strip off

   212      * any sign-extension bits, and returns it as a <code>byte</code>

   213      * value.

   214      *

   215      * <p> Thus, byte values between <code>0x00</code> and

   216      * <code>0x7f</code> are simply returned as integer values between

   217      * <code>0</code> and <code>127</code>.  Values between

   218      * <code>0x80</code> and <code>0xff</code>, which normally

   219      * represent negative <code>byte</code>values, will be mapped into

   220      * positive integers between <code>128</code> and

   221      * <code>255</code>.

   222      *

   223      * <p> The bit offset within the stream is reset to zero before

   224      * the read occurs.

   225      *

   226      * @return an unsigned byte value from the stream.

   227      *

   228      * @exception java.io.EOFException if the end of the stream is reached.

   229      * @exception IOException if an I/O error occurs.

   230      */

   231     int readUnsignedByte() throws IOException;

   232 

   233     /**

   234      * Reads two bytes from the stream, and (conceptually)

   235      * concatenates them according to the current byte order, and

   236      * returns the result as a <code>short</code> value.

   237      *

   238      * <p> The bit offset within the stream is reset to zero before

   239      * the read occurs.

   240      *

   241      * @return a signed short value from the stream.

   242      *

   243      * @exception java.io.EOFException if the stream reaches the end before

   244      * reading all the bytes.

   245      * @exception IOException if an I/O error occurs.

   246      *

   247      * @see #getByteOrder

   248      */

   249     short readShort() throws IOException;

   250 

   251     /**

   252      * Reads two bytes from the stream, and (conceptually)

   253      * concatenates them according to the current byte order, converts

   254      * the resulting value to an <code>int</code>, masks it with

   255      * <code>0xffff</code> in order to strip off any sign-extension

   256      * buts, and returns the result as an unsigned <code>int</code>

   257      * value.

   258      *

   259      * <p> The bit offset within the stream is reset to zero before

   260      * the read occurs.

   261      *

   262      * @return an unsigned short value from the stream, as an int.

   263      *

   264      * @exception java.io.EOFException if the stream reaches the end before

   265      * reading all the bytes.

   266      * @exception IOException if an I/O error occurs.

   267      *

   268      * @see #getByteOrder

   269      */

   270     int readUnsignedShort() throws IOException;

   271 

   272     /**

   273      * Equivalent to <code>readUnsignedShort</code>, except that the

   274      * result is returned using the <code>char</code> datatype.

   275      *

   276      * <p> The bit offset within the stream is reset to zero before

   277      * the read occurs.

   278      *

   279      * @return an unsigned char value from the stream.

   280      *

   281      * @exception java.io.EOFException if the stream reaches the end before

   282      * reading all the bytes.

   283      * @exception IOException if an I/O error occurs.

   284      *

   285      * @see #readUnsignedShort

   286      */

   287     char readChar() throws IOException;

   288 

   289     /**

   290      * Reads 4 bytes from the stream, and (conceptually) concatenates

   291      * them according to the current byte order and returns the result

   292      * as an <code>int</code>.

   293      *

   294      * <p> The bit offset within the stream is ignored and treated as

   295      * though it were zero.

   296      *

   297      * @return a signed int value from the stream.

   298      *

   299      * @exception java.io.EOFException if the stream reaches the end before

   300      * reading all the bytes.

   301      * @exception IOException if an I/O error occurs.

   302      *

   303      * @see #getByteOrder

   304      */

   305     int readInt() throws IOException;

   306 

   307     /**

   308      * Reads 4 bytes from the stream, and (conceptually) concatenates

   309      * them according to the current byte order, converts the result

   310      * to a long, masks it with <code>0xffffffffL</code> in order to

   311      * strip off any sign-extension bits, and returns the result as an

   312      * unsigned <code>long</code> value.

   313      *

   314      * <p> The bit offset within the stream is reset to zero before

   315      * the read occurs.

   316      *

   317      * @return an unsigned int value from the stream, as a long.

   318      *

   319      * @exception java.io.EOFException if the stream reaches the end before

   320      * reading all the bytes.

   321      * @exception IOException if an I/O error occurs.

   322      *

   323      * @see #getByteOrder

   324      */

   325     long readUnsignedInt() throws IOException;

   326 

   327     /**

   328      * Reads 8 bytes from the stream, and (conceptually) concatenates

   329      * them according to the current byte order and returns the result

   330      * as a <code>long</code>.

   331      *

   332      * <p> The bit offset within the stream is reset to zero before

   333      * the read occurs.

   334      *

   335      * @return a signed long value from the stream.

   336      *

   337      * @exception java.io.EOFException if the stream reaches the end before

   338      * reading all the bytes.

   339      * @exception IOException if an I/O error occurs.

   340      *

   341      * @see #getByteOrder

   342      */

   343     long readLong() throws IOException;

   344 

   345     /**

   346      * Reads 4 bytes from the stream, and (conceptually) concatenates

   347      * them according to the current byte order and returns the result

   348      * as a <code>float</code>.

   349      *

   350      * <p> The bit offset within the stream is reset to zero before

   351      * the read occurs.

   352      *

   353      * @return a float value from the stream.

   354      *

   355      * @exception java.io.EOFException if the stream reaches the end before

   356      * reading all the bytes.

   357      * @exception IOException if an I/O error occurs.

   358      *

   359      * @see #getByteOrder

   360      */

   361     float readFloat() throws IOException;

   362 

   363     /**

   364      * Reads 8 bytes from the stream, and (conceptually) concatenates

   365      * them according to the current byte order and returns the result

   366      * as a <code>double</code>.

   367      *

   368      * <p> The bit offset within the stream is reset to zero before

   369      * the read occurs.

   370      *

   371      * @return a double value from the stream.

   372      *

   373      * @exception java.io.EOFException if the stream reaches the end before

   374      * reading all the bytes.

   375      * @exception IOException if an I/O error occurs.

   376      *

   377      * @see #getByteOrder

   378      */

   379     double readDouble() throws IOException;

   380 

   381     /**

   382      * Reads the next line of text from the input stream.  It reads

   383      * successive bytes, converting each byte separately into a

   384      * character, until it encounters a line terminator or end of

   385      * file; the characters read are then returned as a

   386      * <code>String</code>. Note that because this method processes

   387      * bytes, it does not support input of the full Unicode character

   388      * set.

   389      *

   390      * <p> If end of file is encountered before even one byte can be

   391      * read, then <code>null</code> is returned. Otherwise, each byte

   392      * that is read is converted to type <code>char</code> by

   393      * zero-extension. If the character <code>'\n'</code> is

   394      * encountered, it is discarded and reading ceases. If the

   395      * character <code>'\r'</code> is encountered, it is discarded

   396      * and, if the following byte converts  to the character

   397      * <code>'\n'</code>, then that is discarded also; reading then

   398      * ceases. If end of file is encountered before either of the

   399      * characters <code>'\n'</code> and <code>'\r'</code> is

   400      * encountered, reading ceases. Once reading has ceased, a

   401      * <code>String</code> is returned that contains all the

   402      * characters read and not discarded, taken in order.  Note that

   403      * every character in this string will have a value less than

   404      * <code>&#92;u0100</code>, that is, <code>(char)256</code>.

   405      *

   406      * <p> The bit offset within the stream is reset to zero before

   407      * the read occurs.

   408      *

   409      * @return a String containing a line of text from the stream.

   410      *

   411      * @exception IOException if an I/O error occurs.

   412      */

   413     String readLine() throws IOException;

   414 

   415     /**

   416      * Reads in a string that has been encoded using a

   417      * <a href="../../../java/io/DataInput.html#modified-utf-8">modified

   418      * UTF-8</a>

   419      * format.  The general contract of <code>readUTF</code> is that

   420      * it reads a representation of a Unicode character string encoded

   421      * in modified UTF-8 format; this string of characters is

   422      * then returned as a <code>String</code>.

   423      *

   424      * <p> First, two bytes are read and used to construct an unsigned

   425      * 16-bit integer in the manner of the

   426      * <code>readUnsignedShort</code> method, using network byte order

   427      * (regardless of the current byte order setting). This integer

   428      * value is called the <i>UTF length</i> and specifies the number

   429      * of additional bytes to be read. These bytes are then converted

   430      * to characters by considering them in groups. The length of each

   431      * group is computed from the value of the first byte of the

   432      * group. The byte following a group, if any, is the first byte of

   433      * the next group.

   434      *

   435      * <p> If the first byte of a group matches the bit pattern

   436      * <code>0xxxxxxx</code> (where <code>x</code> means "may be

   437      * <code>0</code> or <code>1</code>"), then the group consists of

   438      * just that byte. The byte is zero-extended to form a character.

   439      *

   440      * <p> If the first byte of a group matches the bit pattern

   441      * <code>110xxxxx</code>, then the group consists of that byte

   442      * <code>a</code> and a second byte <code>b</code>. If there is no

   443      * byte <code>b</code> (because byte <code>a</code> was the last

   444      * of the bytes to be read), or if byte <code>b</code> does not

   445      * match the bit pattern <code>10xxxxxx</code>, then a

   446      * <code>UTFDataFormatException</code> is thrown. Otherwise, the

   447      * group is converted to the character:

   448      *

   449      * <pre><code>

   450      * (char)(((a& 0x1F) << 6) | (b & 0x3F))

   451      * </code></pre>

   452      *

   453      * If the first byte of a group matches the bit pattern

   454      * <code>1110xxxx</code>, then the group consists of that byte

   455      * <code>a</code> and two more bytes <code>b</code> and

   456      * <code>c</code>.  If there is no byte <code>c</code> (because

   457      * byte <code>a</code> was one of the last two of the bytes to be

   458      * read), or either byte <code>b</code> or byte <code>c</code>

   459      * does not match the bit pattern <code>10xxxxxx</code>, then a

   460      * <code>UTFDataFormatException</code> is thrown. Otherwise, the

   461      * group is converted to the character:

   462      *

   463      * <pre><code>

   464      * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))

   465      * </code></pre>

   466      *

   467      * If the first byte of a group matches the pattern

   468      * <code>1111xxxx</code> or the pattern <code>10xxxxxx</code>,

   469      * then a <code>UTFDataFormatException</code> is thrown.

   470      *

   471      * <p> If end of file is encountered at any time during this

   472      * entire process, then an <code>java.io.EOFException</code> is thrown.

   473      *

   474      * <p> After every group has been converted to a character by this

   475      * process, the characters are gathered, in the same order in

   476      * which their corresponding groups were read from the input

   477      * stream, to form a <code>String</code>, which is returned.

   478      *

   479      * <p> The current byte order setting is ignored.

   480      *

   481      * <p> The bit offset within the stream is reset to zero before

   482      * the read occurs.

   483      *

   484      * <p><strong>Note:</strong> This method should not be used in

   485      * the  implementation of image formats that use standard UTF-8,

   486      * because  the modified UTF-8 used here is incompatible with

   487      * standard UTF-8.

   488      *

   489      * @return a String read from the stream.

   490      *

   491      * @exception  java.io.EOFException  if this stream reaches the end

   492      * before reading all the bytes.

   493      * @exception  java.io.UTFDataFormatException if the bytes do not represent

   494      * a valid modified UTF-8 encoding of a string.

   495      * @exception IOException if an I/O error occurs.

   496      */

   497     String readUTF() throws IOException;

   498 

   499     /**

   500      * Reads <code>len</code> bytes from the stream, and stores them

   501      * into <code>b</code> starting at index <code>off</code>.

   502      * If the end of the stream is reached, an <code>java.io.EOFException</code>

   503      * will be thrown.

   504      *

   505      * <p> The bit offset within the stream is reset to zero before

   506      * the read occurs.

   507      *

   508      * @param b an array of bytes to be written to.

   509      * @param off the starting position within <code>b</code> to write to.

   510      * @param len the maximum number of <code>byte</code>s to read.

   511      *

   512      * @exception IndexOutOfBoundsException if <code>off</code> is

   513      * negative, <code>len</code> is negative, or <code>off +

   514      * len</code> is greater than <code>b.length</code>.

   515      * @exception NullPointerException if <code>b</code> is

   516      * <code>null</code>.

   517      * @exception java.io.EOFException if the stream reaches the end before

   518      * reading all the bytes.

   519      * @exception IOException if an I/O error occurs.

   520      */

   521     void readFully(byte[] b, int off, int len) throws IOException;

   522 

   523     /**

   524      * Reads <code>b.length</code> bytes from the stream, and stores them

   525      * into <code>b</code> starting at index <code>0</code>.

   526      * If the end of the stream is reached, an <code>java.io.EOFException</code>

   527      * will be thrown.

   528      *

   529      * <p> The bit offset within the stream is reset to zero before

   530      * the read occurs.

   531      *

   532      * @param b an array of <code>byte</code>s.

   533      *

   534      * @exception NullPointerException if <code>b</code> is

   535      * <code>null</code>.

   536      * @exception java.io.EOFException if the stream reaches the end before

   537      * reading all the bytes.

   538      * @exception IOException if an I/O error occurs.

   539      */

   540     void readFully(byte[] b) throws IOException;

   541 

   542     /**

   543      * Reads <code>len</code> shorts (signed 16-bit integers) from the

   544      * stream according to the current byte order, and

   545      * stores them into <code>s</code> starting at index

   546      * <code>off</code>.  If the end of the stream is reached, an

   547      * <code>java.io.EOFException</code> will be thrown.

   548      *

   549      * <p> The bit offset within the stream is reset to zero before

   550      * the read occurs.

   551      *

   552      * @param s an array of shorts to be written to.

   553      * @param off the starting position within <code>s</code> to write to.

   554      * @param len the maximum number of <code>short</code>s to read.

   555      *

   556      * @exception IndexOutOfBoundsException if <code>off</code> is

   557      * negative, <code>len</code> is negative, or <code>off +

   558      * len</code> is greater than <code>s.length</code>.

   559      * @exception NullPointerException if <code>s</code> is

   560      * <code>null</code>.

   561      * @exception java.io.EOFException if the stream reaches the end before

   562      * reading all the bytes.

   563      * @exception IOException if an I/O error occurs.

   564      */

   565     void readFully(short[] s, int off, int len) throws IOException;

   566 

   567     /**

   568      * Reads <code>len</code> chars (unsigned 16-bit integers) from the

   569      * stream according to the current byte order, and

   570      * stores them into <code>c</code> starting at index

   571      * <code>off</code>.  If the end of the stream is reached, an

   572      * <code>java.io.EOFException</code> will be thrown.

   573      *

   574      * <p> The bit offset within the stream is reset to zero before

   575      * the read occurs.

   576      *

   577      * @param c an array of chars to be written to.

   578      * @param off the starting position within <code>c</code> to write to.

   579      * @param len the maximum number of <code>char</code>s to read.

   580      *

   581      * @exception IndexOutOfBoundsException if <code>off</code> is

   582      * negative, <code>len</code> is negative, or <code>off +

   583      * len</code> is greater than <code>c.length</code>.

   584      * @exception NullPointerException if <code>c</code> is

   585      * <code>null</code>.

   586      * @exception java.io.EOFException if the stream reaches the end before

   587      * reading all the bytes.

   588      * @exception IOException if an I/O error occurs.

   589      */

   590     void readFully(char[] c, int off, int len) throws IOException;

   591 

   592     /**

   593      * Reads <code>len</code> ints (signed 32-bit integers) from the

   594      * stream according to the current byte order, and

   595      * stores them into <code>i</code> starting at index

   596      * <code>off</code>.  If the end of the stream is reached, an

   597      * <code>java.io.EOFException</code> will be thrown.

   598      *

   599      * <p> The bit offset within the stream is reset to zero before

   600      * the read occurs.

   601      *

   602      * @param i an array of ints to be written to.

   603      * @param off the starting position within <code>i</code> to write to.

   604      * @param len the maximum number of <code>int</code>s to read.

   605      *

   606      * @exception IndexOutOfBoundsException if <code>off</code> is

   607      * negative, <code>len</code> is negative, or <code>off +

   608      * len</code> is greater than <code>i.length</code>.

   609      * @exception NullPointerException if <code>i</code> is

   610      * <code>null</code>.

   611      * @exception java.io.EOFException if the stream reaches the end before

   612      * reading all the bytes.

   613      * @exception IOException if an I/O error occurs.

   614      */

   615     void readFully(int[] i, int off, int len) throws IOException;

   616 

   617     /**

   618      * Reads <code>len</code> longs (signed 64-bit integers) from the

   619      * stream according to the current byte order, and

   620      * stores them into <code>l</code> starting at index

   621      * <code>off</code>.  If the end of the stream is reached, an

   622      * <code>java.io.EOFException</code> will be thrown.

   623      *

   624      * <p> The bit offset within the stream is reset to zero before

   625      * the read occurs.

   626      *

   627      * @param l an array of longs to be written to.

   628      * @param off the starting position within <code>l</code> to write to.

   629      * @param len the maximum number of <code>long</code>s to read.

   630      *

   631      * @exception IndexOutOfBoundsException if <code>off</code> is

   632      * negative, <code>len</code> is negative, or <code>off +

   633      * len</code> is greater than <code>l.length</code>.

   634      * @exception NullPointerException if <code>l</code> is

   635      * <code>null</code>.

   636      * @exception java.io.EOFException if the stream reaches the end before

   637      * reading all the bytes.

   638      * @exception IOException if an I/O error occurs.

   639      */

   640     void readFully(long[] l, int off, int len) throws IOException;

   641 

   642     /**

   643      * Reads <code>len</code> floats (32-bit IEEE single-precision

   644      * floats) from the stream according to the current byte order,

   645      * and stores them into <code>f</code> starting at

   646      * index <code>off</code>.  If the end of the stream is reached,

   647      * an <code>java.io.EOFException</code> will be thrown.

   648      *

   649      * <p> The bit offset within the stream is reset to zero before

   650      * the read occurs.

   651      *

   652      * @param f an array of floats to be written to.

   653      * @param off the starting position within <code>f</code> to write to.

   654      * @param len the maximum number of <code>float</code>s to read.

   655      *

   656      * @exception IndexOutOfBoundsException if <code>off</code> is

   657      * negative, <code>len</code> is negative, or <code>off +

   658      * len</code> is greater than <code>f.length</code>.

   659      * @exception NullPointerException if <code>f</code> is

   660      * <code>null</code>.

   661      * @exception java.io.EOFException if the stream reaches the end before

   662      * reading all the bytes.

   663      * @exception IOException if an I/O error occurs.

   664      */

   665     void readFully(float[] f, int off, int len) throws IOException;

   666 

   667     /**

   668      * Reads <code>len</code> doubles (64-bit IEEE double-precision

   669      * floats) from the stream according to the current byte order,

   670      * and stores them into <code>d</code> starting at

   671      * index <code>off</code>.  If the end of the stream is reached,

   672      * an <code>java.io.EOFException</code> will be thrown.

   673      *

   674      * <p> The bit offset within the stream is reset to zero before

   675      * the read occurs.

   676      *

   677      * @param d an array of doubles to be written to.

   678      * @param off the starting position within <code>d</code> to write to.

   679      * @param len the maximum number of <code>double</code>s to read.

   680      *

   681      * @exception IndexOutOfBoundsException if <code>off</code> is

   682      * negative, <code>len</code> is negative, or <code>off +

   683      * len</code> is greater than <code>d.length</code>.

   684      * @exception NullPointerException if <code>d</code> is

   685      * <code>null</code>.

   686      * @exception java.io.EOFException if the stream reaches the end before

   687      * reading all the bytes.

   688      * @exception IOException if an I/O error occurs.

   689      */

   690     void readFully(double[] d, int off, int len) throws IOException;

   691 

   692     /**

   693      * Returns the current byte position of the stream.  The next read

   694      * will take place starting at this offset.

   695      *

   696      * @return a long containing the position of the stream.

   697      *

   698      * @exception IOException if an I/O error occurs.

   699      */

   700     long getStreamPosition() throws IOException;

   701 

   702     /**

   703      * Returns the current bit offset, as an integer between 0 and 7,

   704      * inclusive.  The bit offset is updated implicitly by calls to

   705      * the <code>readBits</code> method.  A value of 0 indicates the

   706      * most-significant bit, and a value of 7 indicates the least

   707      * significant bit, of the byte being read.

   708      *

   709      * <p> The bit offset is set to 0 when a stream is first

   710      * opened, and is reset to 0 by calls to <code>seek</code>,

   711      * <code>skipBytes</code>, or any <code>read</code> or

   712      * <code>readFully</code> method.

   713      *

   714      * @return an <code>int</code> containing the bit offset between

   715      * 0 and 7, inclusive.

   716      *

   717      * @exception IOException if an I/O error occurs.

   718      *

   719      * @see #setBitOffset

   720      */

   721     int getBitOffset() throws IOException;

   722 

   723     /**

   724      * Sets the bit offset to an integer between 0 and 7, inclusive.

   725      * The byte offset within the stream, as returned by

   726      * <code>getStreamPosition</code>, is left unchanged.

   727      * A value of 0 indicates the

   728      * most-significant bit, and a value of 7 indicates the least

   729      * significant bit, of the byte being read.

   730      *

   731      * @param bitOffset the desired offset, as an <code>int</code>

   732      * between 0 and 7, inclusive.

   733      *

   734      * @exception IllegalArgumentException if <code>bitOffset</code>

   735      * is not between 0 and 7, inclusive.

   736      * @exception IOException if an I/O error occurs.

   737      *

   738      * @see #getBitOffset

   739      */

   740     void setBitOffset(int bitOffset) throws IOException;

   741 

   742     /**

   743      * Reads a single bit from the stream and returns it as an

   744      * <code>int</code> with the value <code>0</code> or

   745      * <code>1</code>.  The bit offset is advanced by one and reduced

   746      * modulo 8.

   747      *

   748      * @return an <code>int</code> containing the value <code>0</code>

   749      * or <code>1</code>.

   750      *

   751      * @exception java.io.EOFException if the stream reaches the end before

   752      * reading all the bits.

   753      * @exception IOException if an I/O error occurs.

   754      */

   755     int readBit() throws IOException;

   756 

   757     /**

   758      * Reads a bitstring from the stream and returns it as a

   759      * <code>long</code>, with the first bit read becoming the most

   760      * significant bit of the output.  The read starts within the byte

   761      * indicated by <code>getStreamPosition</code>, at the bit given

   762      * by <code>getBitOffset</code>.  The bit offset is advanced by

   763      * <code>numBits</code> and reduced modulo 8.

   764      *

   765      * <p> The byte order of the stream has no effect on this

   766      * method.  The return value of this method is constructed as

   767      * though the bits were read one at a time, and shifted into

   768      * the right side of the return value, as shown by the following

   769      * pseudo-code:

   770      *

   771      * <pre>{@code

   772      * long accum = 0L;

   773      * for (int i = 0; i < numBits; i++) {

   774      *   accum <<= 1; // Shift left one bit to make room

   775      *   accum |= readBit();

   776      * }

   777      * }</pre>

   778      *

   779      * Note that the result of <code>readBits(32)</code> may thus not

   780      * be equal to that of <code>readInt()</code> if a reverse network

   781      * byte order is being used (i.e., <code>getByteOrder() ==

   782      * false</code>).

   783      *

   784      * <p> If the end of the stream is encountered before all the bits

   785      * have been read, an <code>java.io.EOFException</code> is thrown.

   786      *

   787      * @param numBits the number of bits to read, as an <code>int</code>

   788      * between 0 and 64, inclusive.

   789      * @return the bitstring, as a <code>long</code> with the last bit

   790      * read stored in the least significant bit.

   791      *

   792      * @exception IllegalArgumentException if <code>numBits</code>

   793      * is not between 0 and 64, inclusive.

   794      * @exception java.io.EOFException if the stream reaches the end before

   795      * reading all the bits.

   796      * @exception IOException if an I/O error occurs.

   797      */

   798     long readBits(int numBits) throws IOException;

   799 

   800     /**

   801      * Returns the total length of the stream, if known.  Otherwise,

   802      * <code>-1</code> is returned.

   803      *

   804      * @return a <code>long</code> containing the length of the

   805      * stream, if known, or else <code>-1</code>.

   806      *

   807      * @exception IOException if an I/O error occurs.

   808      */

   809     long length() throws IOException;

   810 

   811     /**

   812      * Moves the stream position forward by a given number of bytes.  It

   813      * is possible that this method will only be able to skip forward

   814      * by a smaller number of bytes than requested, for example if the

   815      * end of the stream is reached.  In all cases, the actual number

   816      * of bytes skipped is returned.  The bit offset is set to zero

   817      * prior to advancing the position.

   818      *

   819      * @param n an <code>int</code> containing the number of bytes to

   820      * be skipped.

   821      *

   822      * @return an <code>int</code> representing the number of bytes skipped.

   823      *

   824      * @exception IOException if an I/O error occurs.

   825      */

   826     int skipBytes(int n) throws IOException;

   827 

   828     /**

   829      * Moves the stream position forward by a given number of bytes.

   830      * This method is identical to <code>skipBytes(int)</code> except

   831      * that it allows for a larger skip distance.

   832      *

   833      * @param n a <code>long</code> containing the number of bytes to

   834      * be skipped.

   835      *

   836      * @return a <code>long</code> representing the number of bytes

   837      * skipped.

   838      *

   839      * @exception IOException if an I/O error occurs.

   840      */

   841     long skipBytes(long n) throws IOException;

   842 

   843     /**

   844      * Sets the current stream position to the desired location.  The

   845      * next read will occur at this location.  The bit offset is set

   846      * to 0.

   847      *

   848      * <p> An <code>IndexOutOfBoundsException</code> will be thrown if

   849      * <code>pos</code> is smaller than the flushed position (as

   850      * returned by <code>getflushedPosition</code>).

   851      *

   852      * <p> It is legal to seek past the end of the file; an

   853      * <code>java.io.EOFException</code> will be thrown only if a read is

   854      * performed.

   855      *

   856      * @param pos a <code>long</code> containing the desired file

   857      * pointer position.

   858      *

   859      * @exception IndexOutOfBoundsException if <code>pos</code> is smaller

   860      * than the flushed position.

   861      * @exception IOException if any other I/O error occurs.

   862      */

   863     void seek(long pos) throws IOException;

   864 

   865     /**

   866      * Marks a position in the stream to be returned to by a

   867      * subsequent call to <code>reset</code>.  Unlike a standard

   868      * <code>InputStream</code>, all <code>ImageInputStream</code>s

   869      * support marking.  Additionally, calls to <code>mark</code> and

   870      * <code>reset</code> may be nested arbitrarily.

   871      *

   872      * <p> Unlike the <code>mark</code> methods declared by the

   873      * <code>Reader</code> and <code>InputStream</code> interfaces, no

   874      * <code>readLimit</code> parameter is used.  An arbitrary amount

   875      * of data may be read following the call to <code>mark</code>.

   876      *

   877      * <p> The bit position used by the <code>readBits</code> method

   878      * is saved and restored by each pair of calls to

   879      * <code>mark</code> and <code>reset</code>.

   880      *

   881      * <p> Note that it is valid for an <code>ImageReader</code> to call

   882      * <code>flushBefore</code> as part of a read operation.

   883      * Therefore, if an application calls <code>mark</code> prior to

   884      * passing that stream to an <code>ImageReader</code>, the application

   885      * should not assume that the marked position will remain valid after

   886      * the read operation has completed.

   887      */

   888     void mark();

   889 

   890     /**

   891      * Returns the stream pointer to its previous position, including

   892      * the bit offset, at the time of the most recent unmatched call

   893      * to <code>mark</code>.

   894      *

   895      * <p> Calls to <code>reset</code> without a corresponding call

   896      * to <code>mark</code> have no effect.

   897      *

   898      * <p> An <code>IOException</code> will be thrown if the previous

   899      * marked position lies in the discarded portion of the stream.

   900      *

   901      * @exception IOException if an I/O error occurs.

   902      */

   903     void reset() throws IOException;

   904 

   905     /**

   906      * Discards the initial portion of the stream prior to the

   907      * indicated position.  Attempting to seek to an offset within the

   908      * flushed portion of the stream will result in an

   909      * <code>IndexOutOfBoundsException</code>.

   910      *

   911      * <p> Calling <code>flushBefore</code> may allow classes

   912      * implementing this interface to free up resources such as memory

   913      * or disk space that are being used to store data from the

   914      * stream.

   915      *

   916      * @param pos a <code>long</code> containing the length of the

   917      * stream prefix that may be flushed.

   918      *

   919      * @exception IndexOutOfBoundsException if <code>pos</code> lies

   920      * in the flushed portion of the stream or past the current stream

   921      * position.

   922      * @exception IOException if an I/O error occurs.

   923      */

   924     void flushBefore(long pos) throws IOException;

   925 

   926     /**

   927      * Discards the initial position of the stream prior to the current

   928      * stream position.  Equivalent to

   929      * <code>flushBefore(getStreamPosition())</code>.

   930      *

   931      * @exception IOException if an I/O error occurs.

   932      */

   933     void flush() throws IOException;

   934 

   935     /**

   936      * Returns the earliest position in the stream to which seeking

   937      * may be performed.  The returned value will be the maximum of

   938      * all values passed into previous calls to

   939      * <code>flushBefore</code>.

   940      *

   941      * @return the earliest legal position for seeking, as a

   942      * <code>long</code>.

   943      */

   944     long getFlushedPosition();

   945 

   946     /**

   947      * Returns <code>true</code> if this <code>ImageInputStream</code>

   948      * caches data itself in order to allow seeking backwards.

   949      * Applications may consult this in order to decide how frequently,

   950      * or whether, to flush in order to conserve cache resources.

   951      *

   952      * @return <code>true</code> if this <code>ImageInputStream</code>

   953      * caches data.

   954      *

   955      * @see #isCachedMemory

   956      * @see #isCachedFile

   957      */

   958     boolean isCached();

   959 

   960     /**

   961      * Returns <code>true</code> if this <code>ImageInputStream</code>

   962      * caches data itself in order to allow seeking backwards, and

   963      * the cache is kept in main memory.  Applications may consult

   964      * this in order to decide how frequently, or whether, to flush

   965      * in order to conserve cache resources.

   966      *

   967      * @return <code>true</code> if this <code>ImageInputStream</code>

   968      * caches data in main memory.

   969      *

   970      * @see #isCached

   971      * @see #isCachedFile

   972      */

   973     boolean isCachedMemory();

   974 

   975     /**

   976      * Returns <code>true</code> if this <code>ImageInputStream</code>

   977      * caches data itself in order to allow seeking backwards, and

   978      * the cache is kept in a temporary file.  Applications may consult

   979      * this in order to decide how frequently, or whether, to flush

   980      * in order to conserve cache resources.

   981      *

   982      * @return <code>true</code> if this <code>ImageInputStream</code>

   983      * caches data in a temporary file.

   984      *

   985      * @see #isCached

   986      * @see #isCachedMemory

   987      */

   988     boolean isCachedFile();

   989 

   990     /**

   991      * Closes the stream.  Attempts to access a stream that has been

   992      * closed may result in <code>IOException</code>s or incorrect

   993      * behavior.  Calling this method may allow classes implementing

   994      * this interface to release resources associated with the stream

   995      * such as memory, disk space, or file descriptors.

   996      *

   997      * @exception IOException if an I/O error occurs.

   998      */

   999     void close() throws IOException;

  1000 }