Module com.aoapps.persistence
Package com.aoapps.persistence

Interface PersistentBuffer

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AbstractPersistentBuffer, LargeMappedPersistentBuffer, MappedPersistentBuffer, RandomAccessFileBuffer, TwoCopyBarrierBuffer
public interface PersistentBuffer extends Closeable
A persistent buffer retains its data between uses. They should not be used by multiple virtual machines or even multiple instances within the same virtual machine. They are meant for persistence only, not interprocess communication.

To ensure the data integrity of higher-level data structures, the barrier(boolean) method must be used. A barrier ensures that all writes before the barrier happen before all writes after the barrier. It also accepts a parameter indicating it should also force (fsync) all writes before the barrier to physical media. Write order between barrier(boolean) calls is not maintained.

Author:
AO Industries, Inc.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    barrier(boolean force)
    Ensures that all writes before this barrier occur before all writes after this barrier.
    long
    capacity()
    Gets the capacity of this buffer.
    void
    close()
    Closes this buffer.
    void
    ensureZeros(long position, long len)
    Ensures that all values from the position for the provided length are zeros.
    byte
    get(long position)
    Reads a byte at the provided position.
    void
    get(long position, byte[] buff, int off, int len)
    Reads to the provided byte[], starting at the provided position and for the designated number of bytes.
    boolean
    getBoolean(long position)
    Reads a boolean at the provided position, zero is considered false and any non-zero value is true.
    InputStream
    getInputStream(long position, long length)
    Gets an input stream that reads from this buffer.
    int
    getInt(long position)
    Reads an integer at the provided position.
    long
    getLong(long position)
    Reads a long at the provided position.
    OutputStream
    getOutputStream(long position, long length)
    Gets an output stream that writes to this buffer.
    ProtectionLevel
    getProtectionLevel()
    Gets the protection level currently enforced by the buffer.
    int
    getSome(long position, byte[] buff, int off, int len)
    Reads to the provided byte[], may read fewer than len bytes, but will always read at least one byte.
    boolean
    isClosed()
    Checks if this buffer is closed.
    void
    put(long position, byte value)
    Puts a single value in the buffer.
    void
    put(long position, byte[] buff, int off, int len)
    Writes the bytes to the provided position.
    void
    putInt(long position, int value)
    Writes an integer at the provided position.
    void
    putLong(long position, long value)
    Writes a long at the provided position.
    void
    setCapacity(long newCapacity)
    Sets the capacity of this buffer.

  • Method Details

    • isClosed

      boolean isClosed()
      Checks if this buffer is closed.

    • close

      void close() throws IOException
      Closes this buffer. It is OK to close an already closed buffer.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • capacity

      long capacity() throws IOException
      Gets the capacity of this buffer.
      Throws:
      IOException

    • setCapacity

      void setCapacity(long newCapacity) throws IOException
      Sets the capacity of this buffer. If the buffer is increased in size, the new space will be zero-filled. Setting the capacity may impose an automatic barrier(true), depending on implementation. This should be considered an expensive operation.
      Throws:
      IOException

    • get

      void get(long position, byte[] buff, int off, int len) throws IOException
      Reads to the provided byte[], starting at the provided position and for the designated number of bytes.
      Throws:
      BufferUnderflowException - on end of file
      IOException

    • getSome

      int getSome(long position, byte[] buff, int off, int len) throws IOException
      Reads to the provided byte[], may read fewer than len bytes, but will always read at least one byte. Blocks if no data is available.
      Throws:
      BufferUnderflowException - on end of file
      IOException

    • getBoolean

      boolean getBoolean(long position) throws IOException
      Reads a boolean at the provided position, zero is considered false and any non-zero value is true.
      Throws:
      IOException

    • get

      byte get(long position) throws IOException
      Reads a byte at the provided position.
      Throws:
      IOException

    • getInt

      int getInt(long position) throws IOException
      Reads an integer at the provided position.
      Throws:
      IOException

    • getLong

      long getLong(long position) throws IOException
      Reads a long at the provided position.
      Throws:
      IOException

    • ensureZeros

      void ensureZeros(long position, long len) throws IOException
      Ensures that all values from the position for the provided length are zeros. This may or may not modify the buffer in the process. The values will all be zero upon return. Some implementations may choose to overwrite zeros and return modified, others may choose to detect zeros and avoid modifications. Thus it is possible for existing zeros to still result in a modification.
      Throws:
      IOException

    • put

      void put(long position, byte value) throws IOException
      Puts a single value in the buffer.
      Throws:
      IOException

    • put

      void put(long position, byte[] buff, int off, int len) throws IOException
      Writes the bytes to the provided position. The buffer will not be expanded automatically.
      Throws:
      BufferOverflowException - on end of file
      IOException

    • putInt

      void putInt(long position, int value) throws IOException
      Writes an integer at the provided position. The buffer will not be expanded automatically.
      Throws:
      BufferOverflowException - on end of file
      IOException

    • putLong

      void putLong(long position, long value) throws IOException
      Writes a long at the provided position. The buffer will not be expanded automatically.
      Throws:
      BufferOverflowException - on end of file
      IOException

    • getProtectionLevel

      ProtectionLevel getProtectionLevel()
      Gets the protection level currently enforced by the buffer.
      See Also:

    • barrier

      void barrier(boolean force) throws IOException
      Ensures that all writes before this barrier occur before all writes after this barrier. If force is true, will also commit to physical media synchronously before returning. This request may be ignored or force downgraded to barrier-only depending on the current protection level.
      Throws:
      IOException
      See Also:

    • getInputStream

      InputStream getInputStream(long position, long length) throws IOException, BufferUnderflowException
      Gets an input stream that reads from this buffer. Bounds checking is performed.
      Throws:
      BufferUnderflowException - on end of file
      IOException

    • getOutputStream

      OutputStream getOutputStream(long position, long length) throws IOException, BufferOverflowException
      Gets an output stream that writes to this buffer. Bounds checking is performed.
      Throws:
      BufferUnderflowException - on end of file
      IOException
      BufferOverflowException