org.scijava.io

Interface DataHandle<L extends Location>

All Superinterfaces:

AutoCloseable, Closeable, Comparable<Prioritized>, Contextual, DataInput, DataOutput, HasPluginInfo, Identifiable, Locatable, Logged, Prioritized, RichPlugin, SciJavaPlugin, Typed<L>, TypedPlugin<L>, Versioned, 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

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BLOCK_SIZE Default block size to use when searching through the stream.
static int	MAX_SEARCH_SIZE Default bound on bytes to search when searching through the stream.

Method Summary

Modifier and Type	Method and Description
default 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.
default String	findString(boolean saveString, String... terminators) Reads or skips a string ending with one of the given terminating substrings.
default String	findString(int blockSize, String... terminators) Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
default 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.
default 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.
default 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.
default int	read(ByteBuffer buf) Reads up to buf.remaining() bytes of data from the stream into a ByteBuffer.
default int	read(ByteBuffer buf, int len) Reads up to len bytes of data from the stream into a ByteBuffer.
default String	readCString() Reads a string of arbitrary length, terminated by a null char.
default String	readString(int n) Reads a string of up to length n.
default 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.
default void	setOrder(boolean little) Sets the endianness of the stream.
void	setOrder(ByteOrder order) Sets the byte order of the stream.
default long	skip(long n) Skips over and discards n bytes of data from the stream.
default void	write(ByteBuffer buf) Writes up to buf.remaining() bytes of data from the given ByteBuffer to the stream.
default 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.plugin.RichPlugin

getIdentifier, log

Methods inherited from interface org.scijava.Contextual

context, getContext, setContext

Methods inherited from interface org.scijava.Prioritized

compareTo, getPriority, setPriority

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Locatable

getLocation

Methods inherited from interface org.scijava.Versioned

getVersion

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

Field Detail

DEFAULT_BLOCK_SIZE

static final int DEFAULT_BLOCK_SIZE

Default block size to use when searching through the stream.

See Also:

Constant Field Values

MAX_SEARCH_SIZE

static final int MAX_SEARCH_SIZE

Default bound on bytes to search when searching through the stream.

See Also:

Constant Field Values

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

default 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

default 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

default int read(ByteBuffer buf)
          throws IOException

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

Throws:

IOException

read

default 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

default void write(ByteBuffer buf)
            throws IOException

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

Throws:

IOException

write

default 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

default String readCString()
                    throws IOException

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

Throws:

IOException

readString

default String readString(int n)
                   throws IOException

Reads a string of up to length n.

Throws:

IOException

readString

default 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

default 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

default 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

default 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

default 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

default 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

default 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.