-
- 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 alsoforce
(fsync) all writes before the barrier to physical media. Write order betweenbarrier(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 providedbyte[]
, 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 consideredfalse
and any non-zero value istrue
.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 providedbyte[]
, may read fewer thanlen
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.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- 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 automaticbarrier(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 providedbyte[]
, starting at the provided position and for the designated number of bytes.- Throws:
BufferUnderflowException
- on end of fileIOException
-
getSome
int getSome(long position, byte[] buff, int off, int len) throws IOException
Reads to the providedbyte[]
, may read fewer thanlen
bytes, but will always read at least one byte. Blocks if no data is available.- Throws:
BufferUnderflowException
- on end of fileIOException
-
getBoolean
boolean getBoolean(long position) throws IOException
Reads a boolean at the provided position, zero is consideredfalse
and any non-zero value istrue
.- 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 fileIOException
-
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 fileIOException
-
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 fileIOException
-
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. Ifforce
istrue
, 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
- on end of fileIOException
-
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 fileIOException
BufferOverflowException
-
-