com.bigdata.journal

Interface IBufferStrategy

All Superinterfaces:

IAddressManager, ICounterSetAccess, IMRMW, IMROW, IRawStore, IStreamStore

All Known Subinterfaces:

IDiskBasedStrategy, IHABufferStrategy, IRWStrategy

All Known Implementing Classes:

AbstractBufferStrategy, BasicBufferStrategy, DirectBufferStrategy, DiskBackedBufferStrategy, DiskOnlyStrategy, MappedBufferStrategy, MemStrategy, RWStrategy, TransientBufferStrategy, WORMStrategy

public interface IBufferStrategy
extends IRawStore, IMRMW

Interface for implementations of a buffer strategy as identified by a BufferMode. This interface is designed to encapsulate the specifics of reading and writing slots and performing operations to make an atomic commit.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields inherited from interface com.bigdata.rawstore.IAddressManager

NULL

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() A method that requires the implementation to discard its buffered write set (if any).
void	closeForWrites() Seals the store against further writes and discards any write caches since they will no longer be used.
void	commit() A method that removes assumptions of how a specific strategy commits data.
IAddressManager	getAddressManager()
BufferMode	getBufferMode() The buffer mode supported by the implementation
CounterSet	getCounters() Return the performance counter hierarchy.
long	getExtent() The current size of the journal in bytes.
int	getHeaderSize() The size of the journal header, including MAGIC, version, and both root blocks.
long	getInitialExtent() The initial extent.
long	getMaximumExtent() The maximum extent allowable before a buffer overflow operation will be rejected.
int	getMaxRecordSize()
long	getMetaBitsAddr() The RWStrategy requires meta allocation info in the root block, this method is the hook to enable access.
long	getMetaStartAddr() The RWStrategy requires meta allocation info in the root block, this method is the hook to enable access.
long	getNextOffset() The next offset at which a data item would be written on the store as an offset into the user extent.
int	getOffsetBits()
long	getUserExtent() The size of the user data extent in bytes.
boolean	isDirty() Return true if the store has been modified since the last commit() or abort().
ByteBuffer	readRootBlock(boolean rootBlock0) Read the specified root block from the backing file.
boolean	requiresCommit(IRootBlockView block) A method that removes assumptions of how a specific strategy determines whether a transaction commit is required.
long	transferTo(RandomAccessFile out) A block operation that transfers the serialized records (aka the written on portion of the user extent) en mass from the buffer onto an output file.
void	truncate(long extent) Either truncates or extends the journal.
boolean	useChecksums() Return true if the store uses per-record checksums.
void	writeRootBlock(IRootBlockView rootBlock, ForceEnum forceOnCommitEnum) Write the root block onto stable storage (ie, flush it through to disk).

Methods inherited from interface com.bigdata.rawstore.IRawStore

close, delete, deleteResources, destroy, force, getFile, getResourceMetadata, getUUID, isFullyBuffered, isOpen, isReadOnly, isStable, read, size, write

Methods inherited from interface com.bigdata.rawstore.IAddressManager

getByteCount, getOffset, getPhysicalAddress, toAddr, toString

Methods inherited from interface com.bigdata.rawstore.IStreamStore

getInputStream, getOutputStream

Method Detail

getNextOffset

long getNextOffset()

The next offset at which a data item would be written on the store as an offset into the user extent.

getBufferMode

BufferMode getBufferMode()

The buffer mode supported by the implementation

Returns:

The implemented buffer mode.

getInitialExtent

long getInitialExtent()

The initial extent.

getMaximumExtent

long getMaximumExtent()

The maximum extent allowable before a buffer overflow operation will be rejected.

Note: The semantics here differ from those defined by Options.MAXIMUM_EXTENT. The latter specifies the threshold at which a journal will overflow (onto another journal) while this specifies the maximum size to which a buffer is allowed to grow.

Note: This is normally zero (0L), which basically means that the maximum extent is ignored by the IBufferStrategy but respected by the AbstractJournal, resulting in a soft limit on journal overflow.

Returns:

The maximum extent permitted for the buffer -or- 0L iff no limit is imposed.

getExtent

long getExtent()

The current size of the journal in bytes. When the journal is backed by a disk file this is the actual size on disk of that file. The initial value for this property is set by Options.INITIAL_EXTENT.

getUserExtent

long getUserExtent()

The size of the user data extent in bytes.

Note: The size of the user extent is always generally smaller than the value reported by getExtent() since the latter also reports the space allocated to the journal header and root blocks.

getHeaderSize

int getHeaderSize()

The size of the journal header, including MAGIC, version, and both root blocks. This is used as an offset when computing the address of a record in an underlying file and is ignored by buffer modes that are not backed by a file (e.g., transient) or that are memory mapped (since the map is setup to skip over the header)

truncate

void truncate(long extent)

Either truncates or extends the journal.

Note: Implementations of this method MUST be synchronized so that the operation is atomic with respect to concurrent writers.

Parameters:

extent - The new extent of the journal. This value represent the total extent of the journal, including any root blocks together with the user extent.

Throws:

IllegalArgumentException - The user extent MAY NOT be increased beyond the maximum offset for which the journal was provisioned by Options.OFFSET_BITS.

writeRootBlock

void writeRootBlock(IRootBlockView rootBlock,
                  ForceEnum forceOnCommitEnum)

Write the root block onto stable storage (ie, flush it through to disk).

Parameters:

rootBlock - The root block. Which root block is indicated by IRootBlockView.isRootBlock0().

forceOnCommit - Governs whether or not the journal is forced to stable storage and whether or not the file metadata for the journal is forced to stable storage. See Options.FORCE_ON_COMMIT.

readRootBlock

ByteBuffer readRootBlock(boolean rootBlock0)

Read the specified root block from the backing file.

transferTo

long transferTo(RandomAccessFile out)
                throws IOException

A block operation that transfers the serialized records (aka the written on portion of the user extent) en mass from the buffer onto an output file. The buffered records are written "in order" starting at the current position on the output file. The file is grown if necessary. The file position is advanced to the last byte written on the file.

Note: Implementations of this method MUST be synchronized so that the operation is atomic with respect to concurrent writers.

Parameters:

out - The file to which the buffer contents will be transferred.

Returns:

The #of bytes written.

Throws:

IOException

closeForWrites

void closeForWrites()

Seals the store against further writes and discards any write caches since they will no longer be used. Buffered writes are NOT forced to the disk so the caller SHOULD be able to guarantee that concurrent writers are NOT running. The method should be implemented such that concurrent readers are NOT disturbed.

Throws:

IllegalStateException - if the store is closed.

IllegalStateException - if the store is read-only.

getCounters

CounterSet getCounters()

Return the performance counter hierarchy.

Specified by:

getCounters in interface ICounterSetAccess

getAddressManager

IAddressManager getAddressManager()

requiresCommit

boolean requiresCommit(IRootBlockView block)

A method that removes assumptions of how a specific strategy determines whether a transaction commit is required.

Parameters:

block - The root block held by the client, can be checked against the state of the Buffer Strategy

Returns:

whether any modification has occurred.

commit

void commit()

A method that removes assumptions of how a specific strategy commits data. For most strategies the action is void since the client WORM DISK strategy writes data as allocated. For the Read Write Strategy more data must be managed as part of the protocol outside of the RootBlock, and this is the method that triggers that management. The caller MUST provide appropriate synchronization.

abort

void abort()

A method that requires the implementation to discard its buffered write set (if any). The caller is responsible for any necessary synchronization as part of the abort protocol.

isDirty

boolean isDirty()

Return true if the store has been modified since the last commit() or abort().

Returns:

true if store has been modified since last commit() or abort().

getMetaStartAddr

long getMetaStartAddr()

The RWStrategy requires meta allocation info in the root block, this method is the hook to enable access. The metaStartAddr is the address in the file where the allocation blocks are stored.

Returns:

the metaStartAddr for the root block if any

getMetaBitsAddr

long getMetaBitsAddr()

The RWStrategy requires meta allocation info in the root block, this method is the hook to enable access. The metaBitsAddr is the address in the file where the metaBits that control the allocation of the allocation blocks themselves is stored.

Returns:

the metaBitsAddr for the root block if any

getOffsetBits

int getOffsetBits()

Returns:

the number of bits available in the address to define offset

getMaxRecordSize

int getMaxRecordSize()

Returns:

the maximum record size supported by this strategy

useChecksums

boolean useChecksums()

Return true if the store uses per-record checksums. When true, an additional 4 bytes are written after the record on the disk. Those bytes contain the checksum of the record.