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

      All Methods Instance Methods Abstract Methods 
      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 Detail

      • isClosed

        boolean isClosed()
        Checks if this buffer is closed.

      • 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

      • 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:
        getProtectionLevel()