Package loci.common

Class RandomAccessInputStream

java.lang.Object
java.io.InputStream
loci.common.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
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final int
    Block size to use when searching through the stream.
    protected String
     
    protected String
    The file name.
    protected long
     
    protected long
     
    protected static final int
    Maximum size of the buffer used by the DataInputStream.
    protected static final int
    Maximum number of bytes to search when searching through the stream.
    protected IRandomAccess
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a random access stream around the given byte array.
    Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
    RandomAccessInputStream(String file, int bufferSize)
    Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
    Constructs a random access stream around the given handle.
    Constructs a random access stream around the given handle, and with the associated file path.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
     
    void
    Closes the streams.
    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.
    findString(boolean saveString, String... terminators)
    Reads or skips a string ending with one of the given terminating substrings.
    findString(int blockSize, String... terminators)
    Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
    findString(String... terminators)
    Reads a string ending with one of the given terminating substrings.
    long
     
    boolean
    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
    Gets the endianness of the stream.
    long
     
    void
    mark(int readLimit)
     
    boolean
     
    void
    order(boolean little)
    Sets the endianness of the stream.
    int
     
    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 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
    Read an input byte and return true if the byte is nonzero.
    byte
    Read one byte and return it.
    Reads a byte array of the given length byte by byte.
    char
    Read an input char.
    Read a string of arbitrary length, terminated by a null char.
    double
    Read eight bytes and return a double value.
    float
    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
    Read four input bytes and return an int value.
    Read the next line of text from the input stream.
    long
    Read eight input bytes and return a long value.
    short
    Read two input bytes and return a short value.
    readString(int n)
    Read a string of up to length n.
    readString(String lastChars)
    Reads a string ending with one of the characters in the given string.
    int
    Read an input byte and zero extend it appropriately.
    long
    Read four input bytes and return an unsigned value.
    int
    Read two bytes and return an int in the range 0 through 65535.
    Read a string that has been encoded using a modified UTF-8 format.
    void
     
    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)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • MAX_OVERHEAD

      protected static final int MAX_OVERHEAD
      Maximum size of the buffer used by the DataInputStream.
      See Also:
    • DEFAULT_BLOCK_SIZE

      protected static final int DEFAULT_BLOCK_SIZE
      Block size to use when searching through the stream.
      See Also:
    • MAX_SEARCH_SIZE

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

      protected IRandomAccess raf
    • file

      protected String file
      The file name.
    • length

      protected long length
    • markedPos

      protected long markedPos
    • encoding

      protected String encoding
  • Constructor Details

    • 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 Details

    • 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:
    • 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
    • close

      public void close() throws IOException
      Closes the streams.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class InputStream
      Throws:
      IOException
    • 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

      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.
    • readBoolean

      public boolean readBoolean() throws IOException
      Read an input byte and return true if the byte is nonzero.
      Specified by:
      readBoolean in interface DataInput
      Throws:
      IOException
    • readByte

      public byte readByte() throws IOException
      Read one byte and return it.
      Specified by:
      readByte in interface DataInput
      Throws:
      IOException
    • readChar

      public char readChar() throws IOException
      Read an input char.
      Specified by:
      readChar in interface DataInput
      Throws:
      IOException
    • readDouble

      public double readDouble() throws IOException
      Read eight bytes and return a double value.
      Specified by:
      readDouble in interface DataInput
      Throws:
      IOException
    • readFloat

      public float readFloat() throws IOException
      Read four bytes and return a float value.
      Specified by:
      readFloat in interface DataInput
      Throws:
      IOException
    • readInt

      public int readInt() throws IOException
      Read four input bytes and return an int value.
      Specified by:
      readInt in interface DataInput
      Throws:
      IOException
    • 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
    • readLine

      public String readLine() throws IOException
      Read the next line of text from the input stream.
      Specified by:
      readLine in interface DataInput
      Throws:
      IOException
    • 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:
    • 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:
    • readLong

      public long readLong() throws IOException
      Read eight input bytes and return a long value.
      Specified by:
      readLong in interface DataInput
      Throws:
      IOException
    • readShort

      public short readShort() throws IOException
      Read two input bytes and return a short value.
      Specified by:
      readShort in interface DataInput
      Throws:
      IOException
    • readUnsignedByte

      public int readUnsignedByte() throws IOException
      Read an input byte and zero extend it appropriately.
      Specified by:
      readUnsignedByte in interface DataInput
      Throws:
      IOException
    • readUnsignedShort

      public int readUnsignedShort() throws IOException
      Read two bytes and return an int in the range 0 through 65535.
      Specified by:
      readUnsignedShort in interface DataInput
      Throws:
      IOException
    • readUTF

      public String readUTF() throws IOException
      Read a string that has been encoded using a modified UTF-8 format.
      Specified by:
      readUTF in interface DataInput
      Throws:
      IOException
    • skipBytes

      public int skipBytes(int n) throws IOException
      Skip n bytes within the stream.
      Specified by:
      skipBytes in interface DataInput
      Throws:
      IOException
    • skipBytes

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

      public int read(byte[] array) throws IOException
      Read bytes from the stream into the given array.
      Overrides:
      read in class InputStream
      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) throws IOException
      Read bytes from the stream into the given array.
      Specified by:
      readFully in interface DataInput
      Throws:
      IOException
    • 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
    • read

      public int read() throws IOException
      Specified by:
      read in class InputStream
      Throws:
      IOException
    • available

      public int available() throws IOException
      Overrides:
      available in class InputStream
      Throws:
      IOException
    • mark

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

      public boolean markSupported()
      Overrides:
      markSupported in class InputStream
    • reset

      public void reset() throws IOException
      Overrides:
      reset in class InputStream
      Throws:
      IOException
    • 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