Module org.cojen.tupl
Package org.cojen.tupl

Interface ValueAccessor

All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
Cursor
public interface ValueAccessor extends Closeable
Accesses database values without requiring that they be fully loaded or stored in a single operation. This interface permits values to be larger than what can fit in main memory. When using a cursor to access values, autoload should be disabled to prevent values from being fully loaded automatically

When making transactional changes through this interface, undo actions may require that copies be made of the original value. Partial truncation of a large value isn't optimized to reduce copying, but full truncation is. When possible, full truncation will reference the original value instead of creating a copy.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the accessor, but doesn't flush any OutputStream instances.
    InputStream
    newValueInputStream(long pos)
    Returns a new buffered InputStream instance, which reads from the value.
    InputStream
    newValueInputStream(long pos, int bufferSize)
    Returns a new buffered InputStream instance, which reads from the value.
    OutputStream
    newValueOutputStream(long pos)
    Returns a new buffered OutputStream instance, which writes to the value.
    OutputStream
    newValueOutputStream(long pos, int bufferSize)
    Returns a new buffered OutputStream instance, which writes to the value.
    void
    valueClear(long pos, long length)
    Writes over a range of the value with zeros, starting from any position.
    long
    valueLength()
    Returns the total length of the accessed value.
    void
    valueLength(long length)
    Extends or truncates the accessed value.
    int
    valueRead(long pos, byte[] buf, int off, int len)
    Read from the value, starting from any position.
    void
    valueWrite(long pos, byte[] buf, int off, int len)
    Write into the value, starting from any position.

  • Method Details

    • valueLength

      long valueLength() throws IOException
      Returns the total length of the accessed value.
      Returns:
      value length or -1 if it doesn't exist
      Throws:
      IllegalStateException - if closed
      IOException

    • valueLength

      void valueLength(long length) throws IOException
      Extends or truncates the accessed value. When extended, the new portion of the value is filled with zeros.
      Parameters:
      length - new value length; a negative length deletes the value
      Throws:
      IllegalArgumentException - if length is too large
      IllegalStateException - if closed
      IllegalUpgradeException - if not locked for writing
      IOException

    • valueRead

      int valueRead(long pos, byte[] buf, int off, int len) throws IOException
      Read from the value, starting from any position. The full requested amount of bytes are read, unless the end is reached. A return value of -1 indicates that the value doesn't exist at all, even when the requested amount is zero.
      Parameters:
      pos - start position to read from
      buf - buffer to read into
      off - buffer start offset
      len - requested amount to read
      Returns:
      actual amount read, which is less than requested only if the end was reached, or -1 if the value doesn't exist
      Throws:
      IllegalArgumentException - if the position is negative
      IndexOutOfBoundsException
      IllegalStateException - if closed
      IOException

    • valueWrite

      void valueWrite(long pos, byte[] buf, int off, int len) throws IOException
      Write into the value, starting from any position. Value is extended with zeros when writing past the end, even if the written amount is zero.
      Parameters:
      pos - start position to write to
      buf - buffer to write from
      off - buffer start offset
      len - amount to write
      Throws:
      IllegalArgumentException - if the position is negative
      IndexOutOfBoundsException
      IllegalStateException - if closed
      IllegalUpgradeException - if not locked for writing
      IOException

    • valueClear

      void valueClear(long pos, long length) throws IOException
      Writes over a range of the value with zeros, starting from any position. The length of the value is never changed by this method, even when clearing past the end.
      Parameters:
      pos - start position to clear from
      length - amount to clear
      Throws:
      IllegalArgumentException - if the position or length is negative
      IllegalStateException - if closed
      IllegalUpgradeException - if not locked for writing
      IOException

    • newValueInputStream

      InputStream newValueInputStream(long pos) throws IOException
      Returns a new buffered InputStream instance, which reads from the value. When the InputStream is closed, it closes the accessor too. The InputStream is bound to the accessor, and so only one thread can access either at a time.

      Reading past the end of the stream returns -1 (EOF), as per the InputStream contract. Reading from a value which doesn't exist causes a NoSuchValueException to be thrown.

      Parameters:
      pos - start position to read from
      Returns:
      buffered unsynchronized InputStream
      Throws:
      IllegalArgumentException - if the position is negative
      IllegalStateException - if closed
      IOException

    • newValueInputStream

      InputStream newValueInputStream(long pos, int bufferSize) throws IOException
      Returns a new buffered InputStream instance, which reads from the value. When the InputStream is closed, it closes the accessor too. The InputStream is bound to the accessor, and so only one thread can access either at a time.

      Reading past the end of the stream returns -1 (EOF), as per the InputStream contract. Reading from a value which doesn't exist causes a NoSuchValueException to be thrown.

      Parameters:
      pos - start position to read from
      bufferSize - requested buffer size; actual size may differ
      Returns:
      buffered unsynchronized InputStream
      Throws:
      IllegalArgumentException - if the position is negative
      IllegalStateException - if closed
      IOException

    • newValueOutputStream

      OutputStream newValueOutputStream(long pos) throws IOException
      Returns a new buffered OutputStream instance, which writes to the value. When the OutputStream is closed, it closes the accessor too. The OutputStream is bound to the accessor, and so only one thread can access either at a time.
      Parameters:
      pos - start position to write to
      Returns:
      buffered unsynchronized OutputStream
      Throws:
      IllegalArgumentException - if the position is negative
      IllegalStateException - if closed
      IOException

    • newValueOutputStream

      OutputStream newValueOutputStream(long pos, int bufferSize) throws IOException
      Returns a new buffered OutputStream instance, which writes to the value. When the OutputStream is closed, it closes the accessor too. The OutputStream is bound to the accessor, and so only one thread can access either at a time.
      Parameters:
      pos - start position to write to
      bufferSize - requested buffer size; actual size may differ
      Returns:
      buffered unsynchronized OutputStream
      Throws:
      IllegalArgumentException - if the position is negative
      IllegalStateException - if closed
      IOException

    • close

      void close() throws IOException
      Closes the accessor, but doesn't flush any OutputStream instances.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException