org.scijava.io
Interface DataHandle<L extends Location>

All Superinterfaces:

Closeable, Comparable<Prioritized>, Contextual, DataInput, DataOutput, HasPluginInfo, Prioritized, RichPlugin, SciJavaPlugin, Typed<L>, TypedPlugin<L>, WrapperPlugin<L>

All Known Implementing Classes:

AbstractDataHandle, FileHandle

public interface DataHandle<L extends Location>
extends WrapperPlugin<L>, DataInput, DataOutput, Closeable

A data handle is a plugin which provides access to bytes in a data stream (e.g., files or arrays), identified by a Location.

Author:

Curtis Rueden

See Also:

DataHandleInputStream, DataHandleOutputStream

Method Summary

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.
String	getEncoding() Gets the native encoding of the stream.
ByteOrder	getOrder() Returns the current order of the stream.
boolean	isLittleEndian() Gets the endianness of the stream.
long	length() Returns the length of the stream.
long	offset() Returns the current offset in the stream.
int	read() Reads the next byte of data from the stream.
int	read(byte[] b) Reads up to b.length bytes of data from the stream into an array of bytes.
int	read(byte[] b, int off, int len) Reads up to len bytes of data from the stream into an array of bytes.
int	read(ByteBuffer buf) Reads up to buf.remaining() bytes of data from the stream into a ByteBuffer.
int	read(ByteBuffer buf, int len) Reads up to len bytes of data from the stream into a ByteBuffer.
String	readCString() Reads a string of arbitrary length, terminated by a null char.
String	readString(int n) Reads a string of up to length n.
String	readString(String lastChars) Reads a string ending with one of the characters in the given string.
void	seek(long pos) Sets the stream pointer offset, measured from the beginning of the stream, at which the next read or write occurs.
void	setEncoding(String encoding) Sets the native encoding of the stream.
void	setOrder(boolean little) Sets the endianness of the stream.
void	setOrder(ByteOrder order) Sets the byte order of the stream.
long	skip(long n) Skips over and discards n bytes of data from the stream.
void	write(ByteBuffer buf) Writes up to buf.remaining() bytes of data from the given ByteBuffer to the stream.
void	write(ByteBuffer buf, int len) Writes up to len bytes of data from the given ByteBuffer to the stream.

Methods inherited from interface org.scijava.plugin.WrapperPlugin

get, set

Methods inherited from interface org.scijava.Contextual

context, getContext, setContext

Methods inherited from interface org.scijava.Prioritized

getPriority, setPriority

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Typed

getType, supports

Methods inherited from interface java.io.DataInput

readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes

Methods inherited from interface java.io.DataOutput

write, write, write, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF

Methods inherited from interface java.io.Closeable

close

Method Detail

offset

long offset()
            throws IOException

Returns the current offset in the stream.

Throws:

IOException

length

long length()
            throws IOException

Returns the length of the stream.

Throws:

IOException

getOrder

ByteOrder getOrder()

Returns the current order of the stream.

Returns:

See above.

isLittleEndian

boolean isLittleEndian()

Gets the endianness of the stream.

setOrder

void setOrder(ByteOrder order)

Sets the byte order of the stream.

Parameters:

order - Order to set.

setOrder

void setOrder(boolean little)

Sets the endianness of the stream.

getEncoding

String getEncoding()

Gets the native encoding of the stream.

setEncoding

void setEncoding(String encoding)

Sets the native encoding of the stream.

read

int read(ByteBuffer buf)
         throws IOException

Reads up to buf.remaining() bytes of data from the stream into a ByteBuffer.

Throws:

IOException

read

int read(ByteBuffer buf,
         int len)
         throws IOException

Reads up to len bytes of data from the stream into a ByteBuffer.

Returns:

the total number of bytes read into the buffer.

Throws:

IOException

seek

void seek(long pos)
          throws IOException

Sets the stream pointer offset, measured from the beginning of the stream, at which the next read or write occurs.

Throws:

IOException

write

void write(ByteBuffer buf)
           throws IOException

Writes up to buf.remaining() bytes of data from the given ByteBuffer to the stream.

Throws:

IOException

write

void write(ByteBuffer buf,
           int len)
           throws IOException

Writes up to len bytes of data from the given ByteBuffer to the stream.

Throws:

IOException

readCString

String readCString()
                   throws IOException

Reads a string of arbitrary length, terminated by a null char.

Throws:

IOException

readString

String readString(int n)
                  throws IOException

Reads a string of up to length n.

Throws:

IOException

readString

String readString(String lastChars)
                  throws IOException

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

Throws:

IOException

See Also:

findString(String...)

findString

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

findString

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

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

findString

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.

read

int read()
         throws IOException

Reads the next byte of data from the stream.

Returns:

the next byte of data, or -1 if the end of the stream is reached.

Throws:

IOException - - if an I/O error occurs.

read

int read(byte[] b)
         throws IOException

Reads up to b.length bytes of data from the stream into an array of bytes.

Returns:

the total number of bytes read into the buffer.

Throws:

IOException

read

int read(byte[] b,
         int off,
         int len)
         throws IOException

Reads up to len bytes of data from the stream into an array of bytes.

Returns:

the total number of bytes read into the buffer.

Throws:

IOException

skip

long skip(long n)
          throws IOException

Skips over and discards n bytes of data from the stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

Parameters:

n - - the number of bytes to be skipped.

Returns:

the actual number of bytes skipped.

Throws:

IOException - - if an I/O error occurs.