Package loci.common

Class RandomAccessInputStream

  • All Implemented Interfaces:
    com.esotericsoftware.kryo.KryoSerializable, Closeable, DataInput, AutoCloseable
    public class RandomAccessInputStream
extends InputStream
implements DataInput, Closeable, com.esotericsoftware.kryo.KryoSerializable
    Top-level class for reading from various data sources.
    Author:
    Melissa Linkert melissa at glencoesoftware.com, Curtis Rueden ctrueden at wisc.edu

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int available()  
      void close()
      Closes the streams.
      String findString​(boolean saveString, int blockSize, String... terminators)
      Reads or skips a string ending with one of the given terminating substrings, using the specified block size for buffering.
      String findString​(boolean saveString, String... terminators)
      Reads or skips a string ending with one of the given terminating substrings.
      String findString​(int blockSize, String... terminators)
      Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
      String findString​(String... terminators)
      Reads a string ending with one of the given terminating substrings.
      long getFilePointer()  
      boolean isBitOnByteBoundary()
      Checks if the current position is on a byte boundary, that is the next bit in the byte array is the first bit in a byte.
      boolean isLittleEndian()
      Gets the endianness of the stream.
      long length()  
      void mark​(int readLimit)  
      boolean markSupported()  
      void order​(boolean little)
      Sets the endianness of the stream.
      int read()  
      int read​(byte[] array)
      Read bytes from the stream into the given array.
      int read​(byte[] array, int offset, int n)
      Read n bytes from the stream into the given array at the specified offset.
      void read​(com.esotericsoftware.kryo.Kryo kryo, com.esotericsoftware.kryo.io.Input in)  
      int read​(ByteBuffer buf)
      Read bytes from the stream into the given buffer.
      int read​(ByteBuffer buf, int offset, int n)
      Read n bytes from the stream into the given buffer at the specified offset.
      int readBits​(int bitsToRead)
      Returns an int value representing the value of the bits read from the byte array, from the current position.
      boolean readBoolean()
      Read an input byte and return true if the byte is nonzero.
      byte readByte()
      Read one byte and return it.
      String readByteToString​(int n)
      Reads a byte array of the given length byte by byte.
      char readChar()
      Read an input char.
      String readCString()
      Read a string of arbitrary length, terminated by a null char.
      double readDouble()
      Read eight bytes and return a double value.
      float readFloat()
      Read four bytes and return a float value.
      void readFully​(byte[] array)
      Read bytes from the stream into the given array.
      void readFully​(byte[] array, int offset, int n)
      Read n bytes from the stream into the given array at the specified offset.
      int readInt()
      Read four input bytes and return an int value.
      String readLine()
      Read the next line of text from the input stream.
      long readLong()
      Read eight input bytes and return a long value.
      short readShort()
      Read two input bytes and return a short value.
      String readString​(int n)
      Read a string of up to length n.
      String readString​(String lastChars)
      Reads a string ending with one of the characters in the given string.
      int readUnsignedByte()
      Read an input byte and zero extend it appropriately.
      long readUnsignedInt()
      Read four input bytes and return an unsigned value.
      int readUnsignedShort()
      Read two bytes and return an int in the range 0 through 65535.
      String readUTF()
      Read a string that has been encoded using a modified UTF-8 format.
      void reset()  
      void seek​(long pos)
      Seeks to the given offset within the stream.
      void setEncoding​(String encoding)
      Sets the native encoding of the stream.
      void setLength​(long newLength)
      Sets the length of the stream.
      void skipBits​(long bits)
      Skips a number of bits in the BitBuffer.
      int skipBytes​(int n)
      Skip n bytes within the stream.
      long skipBytes​(long n)
      Skip n bytes within the stream.
      void write​(com.esotericsoftware.kryo.Kryo kryo, com.esotericsoftware.kryo.io.Output out)  

    • Field Detail

      • MAX_OVERHEAD

        protected static final int MAX_OVERHEAD
        Maximum size of the buffer used by the DataInputStream.
        See Also:
        Constant Field Values

      • DEFAULT_BLOCK_SIZE

        protected static final int DEFAULT_BLOCK_SIZE
        Block size to use when searching through the stream.
        See Also:
        Constant Field Values

      • MAX_SEARCH_SIZE

        protected static final int MAX_SEARCH_SIZE
        Maximum number of bytes to search when searching through the stream.
        See Also:
        Constant Field Values

      • file

        protected String file
        The file name.

      • length

        protected long length

      • markedPos

        protected long markedPos

      • encoding

        protected String encoding

    • Constructor Detail

      • RandomAccessInputStream

        public RandomAccessInputStream​(String file)
                        throws IOException
        Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
        Parameters:
        file - a name that can be passed to Location.getHandle(String)
        Throws:
        IOException - if the name is invalid

      • RandomAccessInputStream

        public RandomAccessInputStream​(String file,
                               int bufferSize)
                        throws IOException
        Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
        Parameters:
        file - a name that can be passed to Location.getHandle(String)
        bufferSize - the size of the caching buffer in bytes
        Throws:
        IOException - if the name is invalid

      • RandomAccessInputStream

        public RandomAccessInputStream​(IRandomAccess handle)
                        throws IOException
        Constructs a random access stream around the given handle.
        Parameters:
        handle - the IRandomAccess to be wrapped
        Throws:
        IOException - if the handle is invalid

      • RandomAccessInputStream

        public RandomAccessInputStream​(IRandomAccess handle,
                               String file)
                        throws IOException
        Constructs a random access stream around the given handle, and with the associated file path.
        Parameters:
        handle - the IRandomAccess to be wrapped
        file - the name associated with the handle. Can be null.
        Throws:
        IOException - if the handle is invalid

      • RandomAccessInputStream

        public RandomAccessInputStream​(byte[] array)
                        throws IOException
        Constructs a random access stream around the given byte array.
        Parameters:
        array - the byte array to be wrapped via ByteArrayHandle
        Throws:
        IOException - if the ByteArrayHandle cannot be created

    • Method Detail

      • setEncoding

        public void setEncoding​(String encoding)
        Sets the native encoding of the stream.
        Parameters:
        encoding - the name of a standard charset to use when working with strings
        See Also:
        Constants.ENCODING, Charset

      • seek

        public void seek​(long pos)
          throws IOException
        Seeks to the given offset within the stream.
        Parameters:
        pos - the new byte offset
        Throws:
        IOException - if the seek fails

      • length

        public long length()
            throws IOException
        Returns:
        the number of bytes in the file.
        Throws:
        IOException - if the length cannot be retrieved

      • setLength

        public void setLength​(long newLength)
               throws IOException
        Sets the length of the stream. The new length must be less than the real length of the stream. This allows us to work with a truncated view of a file, without modifying the file itself. Passing in a negative value will reset the length to the stream's real length.
        Parameters:
        newLength - the new stream length as defined above
        Throws:
        IOException - if the original stream length cannot be retrieved

      • getFilePointer

        public long getFilePointer()
                    throws IOException
        Returns:
        the current (absolute) file pointer.
        Throws:
        IOException - if the current pointer cannot be retrieved

      • order

        public void order​(boolean little)
        Sets the endianness of the stream.
        Parameters:
        little - true if the stream ordering should be little-endian

      • isLittleEndian

        public boolean isLittleEndian()
        Gets the endianness of the stream.
        Returns:
        true if the stream ordering is little-endian

      • readString

        public String readString​(String lastChars)
                  throws IOException
        Reads a string ending with one of the characters in the given string.
        Parameters:
        lastChars - each character is a possible terminator
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found.
        Throws:
        IOException - If the maximum search length (512 MB) is exceeded.
        See Also:
        findString(String...)

      • findString

        public String findString​(String... terminators)
                  throws IOException
        Reads a string ending with one of the given terminating substrings.
        Parameters:
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found.
        Throws:
        IOException - If the maximum search length (512 MB) is exceeded.

      • findString

        public String findString​(boolean saveString,
                         String... terminators)
                  throws IOException
        Reads or skips a string ending with one of the given terminating substrings.
        Parameters:
        saveString - Whether to collect the string from the current file pointer to the terminating bytes, and return it. If false, returns null.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found, or null if saveString flag is unset.
        Throws:
        IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

      • findString

        public String findString​(int blockSize,
                         String... terminators)
                  throws IOException
        Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
        Parameters:
        blockSize - The block size to use when reading bytes in chunks.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found.
        Throws:
        IOException - If the maximum search length (512 MB) is exceeded.

      • findString

        public String findString​(boolean saveString,
                         int blockSize,
                         String... terminators)
                  throws IOException
        Reads or skips a string ending with one of the given terminating substrings, using the specified block size for buffering.
        Parameters:
        saveString - Whether to collect the string from the current file pointer to the terminating bytes, and return it. If false, returns null.
        blockSize - The block size to use when reading bytes in chunks.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found, or null if saveString flag is unset.
        Throws:
        IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

      • skipBits

        public void skipBits​(long bits)
              throws IOException
        Skips a number of bits in the BitBuffer.
        Parameters:
        bits - Number of bits to skip
        Throws:
        IllegalArgumentException - if bits is negative
        IOException - if an error occurs while skipping

      • readBits

        public int readBits​(int bitsToRead)
             throws IOException
        Returns an int value representing the value of the bits read from the byte array, from the current position. Bits are extracted from the "left side" or high side of the byte.

        The current position is modified by this call.

        Bits are pushed into the int from the right, endianness is not considered by the method on its own. So, if 5 bits were read from the buffer "10101", the int would be the integer representation of 000...0010101 on the target machine.

        In general, this also means the result will be positive unless a full 32 bits are read.

        Requesting more than 32 bits is allowed, but only up to 32 bits worth of data will be returned (the last 32 bits read).

        Parameters:
        bitsToRead - the number of bits to read from the bit buffer
        Returns:
        the value of the bits read
        Throws:
        IllegalArgumentException - if bits is negative
        IOException - if an error occurs while skipping

      • isBitOnByteBoundary

        public boolean isBitOnByteBoundary()
        Checks if the current position is on a byte boundary, that is the next bit in the byte array is the first bit in a byte.
        Returns:
        true if bit is on byte boundary, false otherwise.

      • readUnsignedInt

        public long readUnsignedInt()
                     throws IOException
        Read four input bytes and return an unsigned value.
        Returns:
        the next 4 bytes in the stream as a long
        Throws:
        IOException - if there is an error during reading

      • readCString

        public String readCString()
                   throws IOException
        Read a string of arbitrary length, terminated by a null char.
        Returns:
        the shortest null-terminated string from the current pointer
        Throws:
        IOException - if there is an error during reading

      • readByteToString

        public String readByteToString​(int n)
                        throws IOException
        Reads a byte array of the given length byte by byte. Returns a string using the set encoding.
        Parameters:
        n - The length of the array.
        Returns:
        See above
        Throws:
        IOException - Thrown if an error occurred while reading the data.
        See Also:
        setEncoding(String)

      • readString

        public String readString​(int n)
                  throws IOException
        Read a string of up to length n.
        Parameters:
        n - the number of bytes to read
        Returns:
        a string representing the read bytes, using the default encoding
        Throws:
        IOException - if an error occurred during reading
        See Also:
        setEncoding(String)

      • skipBytes

        public long skipBytes​(long n)
               throws IOException
        Skip n bytes within the stream.
        Throws:
        IOException

      • read

        public int read​(byte[] array,
                int offset,
                int n)
         throws IOException
        Read n bytes from the stream into the given array at the specified offset.
        Overrides:
        read in class InputStream
        Throws:
        IOException

      • read

        public int read​(ByteBuffer buf)
         throws IOException
        Read bytes from the stream into the given buffer.
        Parameters:
        buf - the ByteBuffer to fill. buf.capacity() determines the number of bytes to read
        Returns:
        the number of bytes read
        Throws:
        IOException - if an error occurred during reading

      • read

        public int read​(ByteBuffer buf,
                int offset,
                int n)
         throws IOException
        Read n bytes from the stream into the given buffer at the specified offset.
        Parameters:
        buf - the ByteBuffer to fill
        offset - the offset to the first byte in the buffer
        n - the number of bytes to read
        Returns:
        the number of bytes actually read
        Throws:
        IOException - if an error occurred during reading

      • readFully

        public void readFully​(byte[] array,
                      int offset,
                      int n)
               throws IOException
        Read n bytes from the stream into the given array at the specified offset.
        Specified by:
        readFully in interface DataInput
        Throws:
        IOException

      • mark

        public void mark​(int readLimit)
        Overrides:
        mark in class InputStream

      • read

        public void read​(com.esotericsoftware.kryo.Kryo kryo,
                 com.esotericsoftware.kryo.io.Input in)
        Specified by:
        read in interface com.esotericsoftware.kryo.KryoSerializable

      • write

        public void write​(com.esotericsoftware.kryo.Kryo kryo,
                  com.esotericsoftware.kryo.io.Output out)
        Specified by:
        write in interface com.esotericsoftware.kryo.KryoSerializable