Package loci.common

Class RandomAccessInputStream

java.lang.Object
java.io.InputStream
loci.common.RandomAccessInputStream
All Implemented Interfaces:
com.esotericsoftware.kryo.KryoSerializable, java.io.Closeable, java.io.DataInput, java.lang.AutoCloseable
public class RandomAccessInputStream
extends java.io.InputStream
implements java.io.DataInput, java.io.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 int DEFAULT_BLOCK_SIZE
    Block size to use when searching through the stream.
    protected java.lang.String encoding  
    protected java.lang.String file
    The file name.
    protected long length  
    protected long markedPos  
    protected static int MAX_OVERHEAD
    Maximum size of the buffer used by the DataInputStream.
    protected static int MAX_SEARCH_SIZE
    Maximum number of bytes to search when searching through the stream.
    protected IRandomAccess raf  

  • Constructor Summary

    Constructors 
    Constructor Description
    RandomAccessInputStream​(byte[] array)
    Constructs a random access stream around the given byte array.
    RandomAccessInputStream​(java.lang.String file)
    Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
    RandomAccessInputStream​(java.lang.String file, int bufferSize)
    Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
    RandomAccessInputStream​(IRandomAccess handle)
    Constructs a random access stream around the given handle.
    RandomAccessInputStream​(IRandomAccess handle, java.lang.String file)
    Constructs a random access stream around the given handle, and with the associated file path.

  • Method Summary

    Modifier and Type Method Description
    int available()  
    void close()
    Closes the streams.
    java.lang.String findString​(boolean saveString, int blockSize, java.lang.String... terminators)
    Reads or skips a string ending with one of the given terminating substrings, using the specified block size for buffering.
    java.lang.String findString​(boolean saveString, java.lang.String... terminators)
    Reads or skips a string ending with one of the given terminating substrings.
    java.lang.String findString​(int blockSize, java.lang.String... terminators)
    Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
    java.lang.String findString​(java.lang.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​(java.nio.ByteBuffer buf)
    Read bytes from the stream into the given buffer.
    int read​(java.nio.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.
    java.lang.String readByteToString​(int n)
    Reads a byte array of the given length byte by byte.
    char readChar()
    Read an input char.
    java.lang.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.
    java.lang.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.
    java.lang.String readString​(int n)
    Read a string of up to length n.
    java.lang.String readString​(java.lang.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.
    java.lang.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​(java.lang.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.io.InputStream

    nullInputStream, readAllBytes, readNBytes, readNBytes, skip, skipNBytes, transferTo

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • RandomAccessInputStream

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

    • RandomAccessInputStream

      public RandomAccessInputStream​(java.lang.String file, int bufferSize) throws java.io.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:
      java.io.IOException - if the name is invalid

    • RandomAccessInputStream

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

    • RandomAccessInputStream

      public RandomAccessInputStream​(IRandomAccess handle, java.lang.String file) throws java.io.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:
      java.io.IOException - if the handle is invalid

    • RandomAccessInputStream

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

  • Method Details

    • setEncoding

      public void setEncoding​(java.lang.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 java.io.IOException
      Seeks to the given offset within the stream.
      Parameters:
      pos - the new byte offset
      Throws:
      java.io.IOException - if the seek fails

    • length

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

    • setLength

      public void setLength​(long newLength) throws java.io.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:
      java.io.IOException - if the original stream length cannot be retrieved

    • getFilePointer

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

    • close

      public void close() throws java.io.IOException
      Closes the streams.
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
      Overrides:
      close in class java.io.InputStream
      Throws:
      java.io.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 java.lang.String readString​(java.lang.String lastChars) throws java.io.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:
      java.io.IOException - If the maximum search length (512 MB) is exceeded.
      See Also:
      findString(String...)

    • findString

      public java.lang.String findString​(java.lang.String... terminators) throws java.io.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:
      java.io.IOException - If the maximum search length (512 MB) is exceeded.

    • findString

      public java.lang.String findString​(boolean saveString, java.lang.String... terminators) throws java.io.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:
      java.io.IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

    • findString

      public java.lang.String findString​(int blockSize, java.lang.String... terminators) throws java.io.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:
      java.io.IOException - If the maximum search length (512 MB) is exceeded.

    • findString

      public java.lang.String findString​(boolean saveString, int blockSize, java.lang.String... terminators) throws java.io.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:
      java.io.IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

    • skipBits

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

    • readBits

      public int readBits​(int bitsToRead) throws java.io.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:
      java.lang.IllegalArgumentException - if bits is negative
      java.io.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 java.io.IOException
      Read an input byte and return true if the byte is nonzero.
      Specified by:
      readBoolean in interface java.io.DataInput
      Throws:
      java.io.IOException

    • readByte

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

    • readChar

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

    • readDouble

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

    • readFloat

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

    • readInt

      public int readInt() throws java.io.IOException
      Read four input bytes and return an int value.
      Specified by:
      readInt in interface java.io.DataInput
      Throws:
      java.io.IOException

    • readUnsignedInt

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

    • readLine

      public java.lang.String readLine() throws java.io.IOException
      Read the next line of text from the input stream.
      Specified by:
      readLine in interface java.io.DataInput
      Throws:
      java.io.IOException

    • readCString

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

    • readByteToString

      public java.lang.String readByteToString​(int n) throws java.io.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:
      java.io.IOException - Thrown if an error occurred while reading the data.
      See Also:
      setEncoding(String)

    • readString

      public java.lang.String readString​(int n) throws java.io.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:
      java.io.IOException - if an error occurred during reading
      See Also:
      setEncoding(String)

    • readLong

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

    • readShort

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

    • readUnsignedByte

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

    • readUnsignedShort

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

    • readUTF

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

    • skipBytes

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

    • skipBytes

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

    • read

      public int read​(byte[] array) throws java.io.IOException
      Read bytes from the stream into the given array.
      Overrides:
      read in class java.io.InputStream
      Throws:
      java.io.IOException

    • read

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

    • read

      public int read​(java.nio.ByteBuffer buf) throws java.io.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:
      java.io.IOException - if an error occurred during reading

    • read

      public int read​(java.nio.ByteBuffer buf, int offset, int n) throws java.io.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:
      java.io.IOException - if an error occurred during reading

    • readFully

      public void readFully​(byte[] array) throws java.io.IOException
      Read bytes from the stream into the given array.
      Specified by:
      readFully in interface java.io.DataInput
      Throws:
      java.io.IOException

    • readFully

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

    • read

      public int read() throws java.io.IOException
      Specified by:
      read in class java.io.InputStream
      Throws:
      java.io.IOException

    • available

      public int available() throws java.io.IOException
      Overrides:
      available in class java.io.InputStream
      Throws:
      java.io.IOException

    • mark

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

    • markSupported

      public boolean markSupported()
      Overrides:
      markSupported in class java.io.InputStream

    • reset

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