Package loci.common

Class NIOInputStream

java.lang.Object

java.io.InputStream

loci.common.NIOInputStream

All Implemented Interfaces:

Closeable, DataInput, AutoCloseable

public class NIOInputStream
extends InputStream
implements DataInput

NIOInputStream provides methods for "intelligent" reading of files and byte arrays.

Field Summary

Fields

Modifier and Type	Field	Description
protected Channel	channel	The file channel backed by the random access file.
protected static int	DEFAULT_BLOCK_SIZE	Block size to use when searching through the stream.
protected File	file	The file.
protected String	filename	The file name.
protected boolean	isLittleEndian	Endianness of the stream.
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
NIOInputStream(byte[] array)	Constructs a random access stream around the given byte array.
NIOInputStream(String filename)	Constructs an NIOInputStream around the given file.
NIOInputStream(IRandomAccess handle)	Constructs a random access stream around the given handle.

Method Summary

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()
DataInputStream	getInputStream()
boolean	isLittleEndian()
long	length()	Gets the number of bytes in the file.
void	mark(int readLimit)
boolean	markSupported()
void	order(boolean isLittleEndian)	Sets the endianness of the stream.
int	read()	Alias for readByte().
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.
boolean	readBoolean()	Read an input byte and return true if the byte is nonzero.
byte	readByte()	Read one byte and return it.
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 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.
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	setExtend(int extend)	Sets the number of bytes by which to extend the stream.
int	skipBytes(int n)	Skip n bytes within the stream.

Methods inherited from class java.io.InputStream

nullInputStream, readAllBytes, readNBytes, readNBytes, skip, transferTo

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BLOCK_SIZE

protected static final int DEFAULT_BLOCK_SIZE

Block size to use when searching through the stream. This value should not exceed MAX_OVERHEAD!

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

filename

protected String filename

The file name.

file

protected File file

The file.

channel

protected Channel channel

The file channel backed by the random access file.

isLittleEndian

protected boolean isLittleEndian

Endianness of the stream.

Constructor Detail

NIOInputStream

public NIOInputStream(String filename)
               throws IOException

Constructs an NIOInputStream around the given file.

Parameters:

filename - the path to a readable file on disk

Throws:

IOException - if the path is invalid or unreadable

NIOInputStream

public NIOInputStream(IRandomAccess handle)

Constructs a random access stream around the given handle.

Parameters:

handle - the IRandomAccess to wrap in a stream

NIOInputStream

public NIOInputStream(byte[] array)

Constructs a random access stream around the given byte array.

Parameters:

array - the byte array to wrap in a stream

Method Detail

getInputStream

public DataInputStream getInputStream()

Returns:

the underlying InputStream.

setExtend

public void setExtend(int extend)

Sets the number of bytes by which to extend the stream. This only applies to InputStream API methods.

Parameters:

extend - the number of bytes by which to extend the stream

seek

public void seek(long pos)
          throws IOException

Seeks to the given offset within the stream.

Parameters:

pos - the offset to which to seek

Throws:

IOException - if the seek is not successful

read

public int read()
         throws IOException

Alias for readByte().

Specified by:

read in class InputStream

Throws:

IOException

length

public long length()
            throws IOException

Gets the number of bytes in the file.

Returns:

the length of the stream in bytes

Throws:

IOException - if the length cannot be retrieved

getFilePointer

public long getFilePointer()

Returns:

the current (absolute) file pointer.

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 isLittleEndian)

Sets the endianness of the stream.

Parameters:

isLittleEndian - true if the stream order is little-endian

isLittleEndian

public boolean isLittleEndian()

Returns:

the endianness of the stream.

readString

public String readString(String lastChars)
                  throws IOException

Reads a string ending with one of the characters in the given string.

Parameters:

lastChars - string containing possible final characters for the returned string

Returns:

the smallest string that ends in one of the characters in lastChars

Throws:

IOException - If the maximum 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.

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.

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

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 smallest string such that the last character is a null byte

Throws:

IOException - if a null-terminated string is not found

See Also:

findString(String...)

readString

public String readString(int n)
                  throws IOException

Read a string of length n.

Parameters:

n - the number of bytes to read

Returns:

a string representing the next n bytes in the stream

Throws:

IOException - if there is an error during reading

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

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

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

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