com.aoindustries.util.persistent

Interface PersistentBuffer

All Known Implementing Classes:

AbstractPersistentBuffer, LargeMappedPersistentBuffer, MappedPersistentBuffer, RandomAccessFileBuffer, TwoCopyBarrierBuffer

public interface PersistentBuffer

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 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 calls is not maintained.

Author:

AO Industries, Inc.

Method Summary

Modifier and Type	Method and 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.

close

void close()
    throws IOException

Closes this buffer. It is OK to close an already closed buffer.

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(boolean)

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()

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

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:

BufferOverflowException

IOException