RandomAccessInputStream (OME Common Java 6.0.0 API)

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 and Description
`protected static int`	`DEFAULT_BLOCK_SIZE` Block size to use when searching through the stream.
`protected String`	`encoding`
`protected 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 and Description
`RandomAccessInputStream(byte[] array)` Constructs a random access stream around the given byte array.
`RandomAccessInputStream(IRandomAccess handle)` Constructs a random access stream around the given handle.
`RandomAccessInputStream(IRandomAccess handle, String file)` Constructs a random access stream around the given handle, and with the associated file path.
`RandomAccessInputStream(String file)` Constructs a hybrid RandomAccessFile/DataInputStream around the given file.
`RandomAccessInputStream(String file, int bufferSize)` Constructs a hybrid RandomAccessFile/DataInputStream around the given file.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`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.
`void`	`read(com.esotericsoftware.kryo.Kryo kryo, com.esotericsoftware.kryo.io.Input in)`
`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)`

Methods inherited from class java.io.InputStream
skip

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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
  - raf
```
protected IRandomAccess raf
```
  - 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
  - close
```
public void close()
           throws IOException
```
    Closes the streams.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    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(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.
  - 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:
    
    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)
  - 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

Class RandomAccessInputStream

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.io.InputStream

Methods inherited from class java.lang.Object

Field Detail

MAX_OVERHEAD

DEFAULT_BLOCK_SIZE

MAX_SEARCH_SIZE

raf

file

length

markedPos

encoding

Constructor Detail

RandomAccessInputStream

RandomAccessInputStream

RandomAccessInputStream

RandomAccessInputStream

RandomAccessInputStream

Method Detail

setEncoding

seek

length

setLength

getFilePointer

close

order

isLittleEndian

readString

findString

findString

findString

findString

skipBits

readBits

isBitOnByteBoundary

readBoolean

readByte

readChar

readDouble

readFloat

readInt

readUnsignedInt

readLine

readCString

readByteToString

readString

readLong

readShort

readUnsignedByte

readUnsignedShort

readUTF

skipBytes

skipBytes

read

read

read

read

readFully

readFully

read

available

mark

markSupported

reset

read

write