DataHandle (SciJava Javadocs 0-SNAPSHOT API)

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 Subinterfaces:

ResettableStreamHandle<L>, SeekableStreamHandle<L>, StreamHandle<L>

All Known Implementing Classes:

AbstractDataHandle, AbstractHigherOrderHandle, AbstractSeekableStreamHandle, AbstractStreamHandle, BytesHandle, DummyHandle, FileHandle, HTTPHandle, MultiWriteHandle, ReadBufferDataHandle, WriteBufferDataHandle
```
public interface DataHandle<L extends Location>
extends WrapperPlugin<L>, DataInput, DataOutput, Closeable
```
A data handle is a plugin which provides both streaming and random access to bytes at a Location (e.g., files or arrays).

Author:

Curtis Rueden

See Also:

DataHandleInputStream, DataHandleOutputStream

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class DataHandle.ByteOrder

Nested Classes
Modifier and Type	Interface and Description
`static class`	`DataHandle.ByteOrder`

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

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default long`	`available(long count)` Gets the number of bytes which can be read from, or written to, the data handle, bounded by the specified number of bytes.
`default String`	`checksum()` Gets a "fast" checksum which succinctly represents the contents of the data stream.
`byte[]`	`conversionBuffer()`
`default void`	`ensureReadable(long count)` Ensures that the handle has sufficient bytes available to read.
`default boolean`	`ensureWritable(long count)` Ensures that the handle has the correct length to be written to, and extends it as required.
`boolean`	`exists()` Tests whether this handle's location actually exists at the source.
`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.
`DataHandle.ByteOrder`	`getOrder()` Returns the byte order of the stream.
`default boolean`	`isBigEndian()` Returns true iff the stream's order is `DataHandle.ByteOrder.BIG_ENDIAN`.
`default boolean`	`isLittleEndian()` Returns true iff the stream's order is `DataHandle.ByteOrder.LITTLE_ENDIAN`.
`boolean`	`isReadable()` Gets whether reading from this handle is supported.
`boolean`	`isWritable()` Gets whether writing to this handle is supported.
`default Date`	`lastModified()` Gets the last modified timestamp of the location.
`long`	`length()` Returns the length of the data in bytes.
`long`	`offset()` Returns the current offset in the stream.
`default 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 boolean`	`readBoolean()`
`default char`	`readChar()`
`default String`	`readCString()` Reads a string of arbitrary length, terminated by a null char.
`default double`	`readDouble()`
`default float`	`readFloat()`
`default void`	`readFully(byte[] b)`
`default void`	`readFully(byte[] b, int off, int len)`
`default int`	`readInt()`
`default String`	`readLine()`
`default long`	`readLong()`
`default short`	`readShort()`
`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.
`default int`	`readUnsignedByte()`
`default int`	`readUnsignedShort()`
`default String`	`readUTF()`
`void`	`seek(long pos)` Sets the stream 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`	`setLength(long length)` Sets the new length of the handle.
`default void`	`setLittleEndian(boolean little)` Sets the endianness of the stream.
`void`	`setOrder(DataHandle.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 int`	`skipBytes(int n)`
`default void`	`write(byte[] b)`
`default void`	`writeBoolean(boolean v)`
`default void`	`writeByte(int v)`
`default void`	`writeBytes(String s)`
`default void`	`writeChar(int v)`
`default void`	`writeChars(String s)`
`default void`	`writeDouble(double v)`
`default void`	`writeFloat(float v)`
`default void`	`writeInt(int v)`
`default void`	`writeLine(String string)` Writes the provided string, followed by a newline character.
`default void`	`writeLong(long v)`
`default void`	`writeShort(int v)`
`default void`	`writeUTF(String str)`

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
readByte

Methods inherited from interface java.io.DataOutput
write, write

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
  - isReadable
```
boolean isReadable()
```
    Gets whether reading from this handle is supported.
  - isWritable
```
boolean isWritable()
```
    Gets whether writing to this handle is supported.
  - exists
```
boolean exists()
        throws IOException
```
    Tests whether this handle's location actually exists at the source.
    
    Returns:
    
    True if the location exists; false if not.
    
    Throws:
    
    IOException - If something goes wrong with the existence check.
  - lastModified
```
default Date lastModified()
                   throws IOException
```
    Gets the last modified timestamp of the location.
    
    Returns:
    
    The last modified timestamp, or null if the handle does not support this feature or if the location does not exist.
    
    Throws:
    
    IOException - If something goes wrong with the last modified check.
  - checksum
```
default String checksum()
                 throws IOException
```
    Gets a "fast" checksum which succinctly represents the contents of the data stream. The term "fast" here refers to the idea that the checksum be retrievable quickly, without actually performing a thorough computation across the entire data stream. Typically, such a thing is feasible because the checksum was calculated a priori; e.g., artifacts deployed to remote Maven repositories are always deployed with corresponding checksum files.
    No guarantee is made about the exact nature of the checksum (e.g., SHA-1 or MD5), only that the value is deterministic for this particular location with its current contents. In other words: if a checksum differs from a previous inquiry, you can be sure the contents have changed; conversely, if the checksum is still the same, the contents are highly likely to be unchanged.
    
    Returns:
    
    The checksum, or null if the handle does not support this feature.
    
    Throws:
    
    IOException - If something goes wrong when accessing the checksum.
  - offset
```
long offset()
     throws IOException
```
    Returns the current offset in the stream.
    
    Throws:
    
    IOException
  - seek
```
void seek(long pos)
   throws IOException
```
    Sets the stream offset, measured from the beginning of the stream, at which the next read or write occurs.
    
    Throws:
    
    IOException
  - length
```
long length()
     throws IOException
```
    Returns the length of the data in bytes.
    
    Returns:
    
    The length, or -1 if the length is unknown.
    
    Throws:
    
    IOException
  - setLength
```
void setLength(long length)
        throws IOException
```
    Sets the new length of the handle.
    
    Parameters:
    
    length - New length.
    
    Throws:
    
    IOException - If there is an error changing the handle's length.
  - available
```
default long available(long count)
                throws IOException
```
    Gets the number of bytes which can be read from, or written to, the data handle, bounded by the specified number of bytes.
    In the case of reading, attempting to read the returned number of bytes is guaranteed not to throw EOFException. However, be aware that the following methods might still process fewer bytes than indicated by this method:
    In the case of writing, attempting to write the returned number of bytes is guaranteed not to expand the length of the handle; i.e., the write will only overwrite bytes already within the handle's bounds.
    Parameters:
    
    count - Desired number of bytes to read/write.
    
    Returns:
    
    The actual number of bytes which could be read/written, which might be less than the requested value.
    
    Throws:
    
    IOException - If something goes wrong with the check.
  - ensureReadable
```
default void ensureReadable(long count)
                     throws IOException
```
    Ensures that the handle has sufficient bytes available to read.
    
    Parameters:
    
    count - Number of bytes to read.
    
    Throws:
    
    EOFException - If there are insufficient bytes available.
    
    IOException - If the handle is write-only, or something goes wrong with the check.
    
    See Also:
    
    available(long)
  - ensureWritable
```
default boolean ensureWritable(long count)
                        throws IOException
```
    Ensures that the handle has the correct length to be written to, and extends it as required.
    
    Parameters:
    
    count - Number of bytes to write.
    
    Returns:
    
    true if the handle's length was sufficient, or false if the handle's length required an extension.
    
    Throws:
    
    IOException - If the handle is read-only, or something goes wrong with the check, or there is an error changing the handle's length.
  - getOrder
```
DataHandle.ByteOrder getOrder()
```
    Returns the byte order of the stream.
  - setOrder
```
void setOrder(DataHandle.ByteOrder order)
```
    Sets the byte order of the stream.
    
    Parameters:
    
    order - Order to set.
  - isBigEndian
```
default boolean isBigEndian()
```
    Returns true iff the stream's order is DataHandle.ByteOrder.BIG_ENDIAN.
    
    See Also:
    
    getOrder()
  - isLittleEndian
```
default boolean isLittleEndian()
```
    Returns true iff the stream's order is DataHandle.ByteOrder.LITTLE_ENDIAN.
    
    See Also:
    
    getOrder()
  - setLittleEndian
```
default void setLittleEndian(boolean little)
```
    Sets the endianness of the stream.
    
    Parameters:
    
    little - If true, sets the order to DataHandle.ByteOrder.LITTLE_ENDIAN; otherwise, sets the order to DataHandle.ByteOrder.BIG_ENDIAN.
    
    See Also:
    
    setOrder(ByteOrder)
  - getEncoding
```
String getEncoding()
```
    Gets the native encoding of the stream.
  - setEncoding
```
void setEncoding(String encoding)
```
    Sets the native encoding of the stream.
  - conversionBuffer
```
byte[] conversionBuffer()
```
    Returns:
    
    a 8 byte long buffer array used for type conversions
  - 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 offset 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 offset 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.
  - writeLine
```
default void writeLine(String string)
                throws IOException
```
    Writes the provided string, followed by a newline character.
    
    Parameters:
    
    string - The string to write.
    
    Throws:
    
    IOException - If an I/O error occurs.
  - read
```
default 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.
  - readFully
```
default void readFully(byte[] b)
                throws IOException
```
    Specified by:
    
    readFully in interface DataInput
    
    Throws:
    
    IOException
  - readFully
```
default void readFully(byte[] b,
                       int off,
                       int len)
                throws IOException
```
    Specified by:
    
    readFully in interface DataInput
    
    Throws:
    
    IOException
  - skipBytes
```
default int skipBytes(int n)
               throws IOException
```
    Specified by:
    
    skipBytes in interface DataInput
    
    Throws:
    
    IOException
  - readBoolean
```
default boolean readBoolean()
                     throws IOException
```
    Specified by:
    
    readBoolean in interface DataInput
    
    Throws:
    
    IOException
  - readUnsignedByte
```
default int readUnsignedByte()
                      throws IOException
```
    Specified by:
    
    readUnsignedByte in interface DataInput
    
    Throws:
    
    IOException
  - readShort
```
default short readShort()
                 throws IOException
```
    Specified by:
    
    readShort in interface DataInput
    
    Throws:
    
    IOException
  - readUnsignedShort
```
default int readUnsignedShort()
                       throws IOException
```
    Specified by:
    
    readUnsignedShort in interface DataInput
    
    Throws:
    
    IOException
  - readChar
```
default char readChar()
               throws IOException
```
    Specified by:
    
    readChar in interface DataInput
    
    Throws:
    
    IOException
  - readInt
```
default int readInt()
             throws IOException
```
    Specified by:
    
    readInt in interface DataInput
    
    Throws:
    
    IOException
  - readLong
```
default long readLong()
               throws IOException
```
    Specified by:
    
    readLong in interface DataInput
    
    Throws:
    
    IOException
  - readFloat
```
default float readFloat()
                 throws IOException
```
    Specified by:
    
    readFloat in interface DataInput
    
    Throws:
    
    IOException
  - readDouble
```
default double readDouble()
                   throws IOException
```
    Specified by:
    
    readDouble in interface DataInput
    
    Throws:
    
    IOException
  - readLine
```
default String readLine()
                 throws IOException
```
    Specified by:
    
    readLine in interface DataInput
    
    Throws:
    
    IOException
  - readUTF
```
default String readUTF()
                throws IOException
```
    Specified by:
    
    readUTF in interface DataInput
    
    Throws:
    
    IOException
  - write
```
default void write(byte[] b)
            throws IOException
```
    Specified by:
    
    write in interface DataOutput
    
    Throws:
    
    IOException
  - writeBoolean
```
default void writeBoolean(boolean v)
                   throws IOException
```
    Specified by:
    
    writeBoolean in interface DataOutput
    
    Throws:
    
    IOException
  - writeByte
```
default void writeByte(int v)
                throws IOException
```
    Specified by:
    
    writeByte in interface DataOutput
    
    Throws:
    
    IOException
  - writeShort
```
default void writeShort(int v)
                 throws IOException
```
    Specified by:
    
    writeShort in interface DataOutput
    
    Throws:
    
    IOException
  - writeChar
```
default void writeChar(int v)
                throws IOException
```
    Specified by:
    
    writeChar in interface DataOutput
    
    Throws:
    
    IOException
  - writeInt
```
default void writeInt(int v)
               throws IOException
```
    Specified by:
    
    writeInt in interface DataOutput
    
    Throws:
    
    IOException
  - writeLong
```
default void writeLong(long v)
                throws IOException
```
    Specified by:
    
    writeLong in interface DataOutput
    
    Throws:
    
    IOException
  - writeFloat
```
default void writeFloat(float v)
                 throws IOException
```
    Specified by:
    
    writeFloat in interface DataOutput
    
    Throws:
    
    IOException
  - writeDouble
```
default void writeDouble(double v)
                  throws IOException
```
    Specified by:
    
    writeDouble in interface DataOutput
    
    Throws:
    
    IOException
  - writeBytes
```
default void writeBytes(String s)
                 throws IOException
```
    Specified by:
    
    writeBytes in interface DataOutput
    
    Throws:
    
    IOException
  - writeChars
```
default void writeChars(String s)
                 throws IOException
```
    Specified by:
    
    writeChars in interface DataOutput
    
    Throws:
    
    IOException
  - writeUTF
```
default void writeUTF(String str)
               throws IOException
```
    Specified by:
    
    writeUTF in interface DataOutput
    
    Throws:
    
    IOException

Interface DataHandle<L extends Location>

Nested Class Summary

Field Summary

Method Summary

Methods inherited from interface org.scijava.plugin.WrapperPlugin

Methods inherited from interface org.scijava.plugin.RichPlugin

Methods inherited from interface org.scijava.Contextual

Methods inherited from interface org.scijava.Prioritized

Methods inherited from interface org.scijava.plugin.HasPluginInfo

Methods inherited from interface org.scijava.Locatable

Methods inherited from interface org.scijava.Versioned

Methods inherited from interface org.scijava.Typed

Methods inherited from interface java.io.DataInput

Methods inherited from interface java.io.DataOutput

Methods inherited from interface java.io.Closeable

Field Detail

DEFAULT_BLOCK_SIZE

MAX_SEARCH_SIZE

Method Detail

isReadable

isWritable

exists

lastModified

checksum

offset

seek

length

setLength

available

ensureReadable

ensureWritable

getOrder

setOrder

isBigEndian

isLittleEndian

setLittleEndian

getEncoding

setEncoding

conversionBuffer

readCString

readString

readString

findString

findString

findString

findString

writeLine

read

read

read

skip

readFully

readFully

skipBytes

readBoolean

readUnsignedByte

readShort

readUnsignedShort

readChar

readInt

readLong

readFloat

readDouble

readLine

readUTF

write

writeBoolean

writeByte

writeShort

writeChar

writeInt

writeLong

writeFloat

writeDouble

writeBytes

writeChars

writeUTF