com.bigdata.journal
Class AbstractBufferStrategy

java.lang.Object
  com.bigdata.rawstore.AbstractRawStore
      com.bigdata.rawstore.AbstractRawWormStore
          com.bigdata.journal.AbstractBufferStrategy

All Implemented Interfaces:

IBufferStrategy, IAddressManager, IMRMW, IMROW, IRawStore, IStoreSerializer, IWORM

Direct Known Subclasses:

BasicBufferStrategy, BufferedDiskStrategy, DiskOnlyStrategy

public abstract class AbstractBufferStrategy
extends AbstractRawWormStore
implements IBufferStrategy

Abstract base class for IBufferStrategy implementation.

Version:

$Id: AbstractBufferStrategy.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Field Summary

protected BufferMode	bufferMode The buffer strategy implemented by this class.
protected static String	ERR_ADDRESS_IS_NULL Text of the error message used when a ZERO (0L) is passed as an address to IRawStore.read(long) or similar methods.
protected static String	ERR_ADDRESS_NOT_WRITTEN Text of the error message used when an address is given has never been written.
protected static String	ERR_BAD_RECORD_SIZE Error message used when the record size is invalid (e.g., negative).
protected static String	ERR_BUFFER_EMPTY Text of the error message used when a ByteBuffer with zero bytes Buffer.remaining() is passed to IRawStore.write(ByteBuffer).
protected static String	ERR_BUFFER_NULL Text of the error message used when a null reference is provided for a ByteBuffer.
protected static String	ERR_INT32 Text of the error message used when a write operation would exceed the #of bytes that can be addressed by a ByteBuffer backed by an array or native memory (both are limited to int32 bytes since they are addressed by a Java int).
protected static String	ERR_NOT_OPEN Error message used when the store is closed.
protected static String	ERR_READ_ONLY Error message used when the writes are not allowed.
protected static String	ERR_RECORD_LENGTH_ZERO Text of the error message used when an address provided to IRawStore.read(long) or a similar method encodes a record length of zero (0).
protected static String	ERR_TRUNCATE Text of the error message used when IBufferStrategy.truncate(long) would truncate data that has already been written.
protected long	initialExtent
protected static org.apache.log4j.Logger	log Log for btree operations.
protected long	maximumExtent
protected long	nextOffset The next offset at which a data item would be written on the store as an offset into the user extent (offset zero(0) addresses the first byte after the root blocks).
protected static boolean	WARN

Fields inherited from class com.bigdata.rawstore.AbstractRawWormStore

am

Fields inherited from class com.bigdata.rawstore.AbstractRawStore

serializer

Fields inherited from interface com.bigdata.rawstore.IAddressManager

NULL

Method Summary

protected void	assertOpen()
void	close() Manages the open flag state.
void	closeForWrites() Sets the readOnly flag.
void	destroy() Closes the store immediately, deletes its persistent resources, and clears any records for the store from the IGlobalLRU.
BufferMode	getBufferMode() The buffer mode supported by the implementation
long	getInitialExtent() The initial extent.
long	getMaximumExtent() The maximum extent allowable before a buffer overflow operation will be rejected.
long	getNextOffset() The next offset at which a data item would be written on the store as an offset into the user extent.
IResourceMetadata	getResourceMetadata() Not supported - this is available on the AbstractJournal.
UUID	getUUID() Not supported - this is available on the AbstractJournal.
boolean	isOpen() true iff the store is open.
boolean	isReadOnly() true iff the store does not allow writes.
boolean	overflow(long needed) Invoked if the store would exceed its current extent by IRawStore.write(ByteBuffer).
long	size() The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).
protected static long	transferFromDiskTo(IDiskBasedStrategy src, RandomAccessFile out) Helper method used by DiskBackedBufferStrategy and DiskOnlyStrategy to implement IBufferStrategy.transferTo(RandomAccessFile) using a FileChannel to FileChannel transfer.

Methods inherited from class com.bigdata.rawstore.AbstractRawWormStore

getAddressManager, getByteCount, getOffset, getOffsetBits, packAddr, toAddr, toString, unpackAddr

Methods inherited from class com.bigdata.rawstore.AbstractRawStore

deserialize, deserialize, deserialize, serialize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.bigdata.journal.IBufferStrategy

getCounters, getExtent, getHeaderSize, getUserExtent, readRootBlock, transferTo, truncate, writeRootBlock

Methods inherited from interface com.bigdata.rawstore.IRawStore

deleteResources, force, getFile, isFullyBuffered, isStable, read, write

Methods inherited from interface com.bigdata.rawstore.IAddressManager

getByteCount, getOffset, packAddr, toAddr, toString, unpackAddr

Methods inherited from interface com.bigdata.rawstore.IStoreSerializer

deserialize, deserialize, deserialize, serialize

Field Detail

log

protected static final org.apache.log4j.Logger log

Log for btree operations.

WARN

protected static final boolean WARN

ERR_BUFFER_EMPTY

protected static final String ERR_BUFFER_EMPTY

Text of the error message used when a ByteBuffer with zero bytes Buffer.remaining() is passed to IRawStore.write(ByteBuffer).

See Also:

Constant Field Values

ERR_BUFFER_NULL

protected static final String ERR_BUFFER_NULL

Text of the error message used when a null reference is provided for a ByteBuffer.

See Also:

Constant Field Values

ERR_ADDRESS_NOT_WRITTEN

protected static final String ERR_ADDRESS_NOT_WRITTEN

Text of the error message used when an address is given has never been written. Since the journal is an append-only store, an address whose offset plus record length exceeds the nextOffset on which data would be written may be easily detected.

See Also:

Constant Field Values

ERR_ADDRESS_IS_NULL

protected static final String ERR_ADDRESS_IS_NULL

Text of the error message used when a ZERO (0L) is passed as an address to IRawStore.read(long) or similar methods. This value 0L is reserved to indicate a persistent null reference and may never be read.

See Also:

Constant Field Values

ERR_RECORD_LENGTH_ZERO

protected static final String ERR_RECORD_LENGTH_ZERO

Text of the error message used when an address provided to IRawStore.read(long) or a similar method encodes a record length of zero (0). Empty records are not permitted on write and addresses with a zero length are rejected on read.

See Also:

Constant Field Values

ERR_INT32

protected static final String ERR_INT32

Text of the error message used when a write operation would exceed the #of bytes that can be addressed by a ByteBuffer backed by an array or native memory (both are limited to int32 bytes since they are addressed by a Java int).

See Also:

Constant Field Values

ERR_TRUNCATE

protected static final String ERR_TRUNCATE

Text of the error message used when IBufferStrategy.truncate(long) would truncate data that has already been written.

See Also:

Constant Field Values

ERR_READ_ONLY

protected static final String ERR_READ_ONLY

Error message used when the writes are not allowed.

See Also:

Constant Field Values

ERR_BAD_RECORD_SIZE

protected static final String ERR_BAD_RECORD_SIZE

Error message used when the record size is invalid (e.g., negative).

See Also:

Constant Field Values

TODO:

There is some overlap with ERR_RECORD_LENGTH_ZERO and ERR_BUFFER_EMPTY.

ERR_NOT_OPEN

protected static final String ERR_NOT_OPEN

Error message used when the store is closed.

See Also:

Constant Field Values

initialExtent

protected final long initialExtent

maximumExtent

protected final long maximumExtent

bufferMode

protected final BufferMode bufferMode

The buffer strategy implemented by this class.

nextOffset

protected long nextOffset

The next offset at which a data item would be written on the store as an offset into the user extent (offset zero(0) addresses the first byte after the root blocks). This is updated each time a new record is written on the store. On restart, the value is initialized from the current root block. The current value is written as part of the new root block during each commit.

Note: It is NOT safe to reload the current root block and therefore reset this to an earlier offset unless all transactions are discarded. The reason is that transactions may use objects (btrees) to provide isolation. Those objects write on the store but do not register as ICommitters and therefore never make themselves restart safe. However, you can not discard the writes of those objects unless the entire store is being restarted, e.g., after a shutdown or a crash.

Method Detail

getInitialExtent

public final long getInitialExtent()

Description copied from interface: IBufferStrategy

The initial extent.

Specified by:

getInitialExtent in interface IBufferStrategy

getMaximumExtent

public final long getMaximumExtent()

Description copied from interface: IBufferStrategy

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.

Specified by:

getMaximumExtent in interface IBufferStrategy

Returns:

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

getBufferMode

public final BufferMode getBufferMode()

Description copied from interface: IBufferStrategy

The buffer mode supported by the implementation

Specified by:

getBufferMode in interface IBufferStrategy

Returns:

The implemented buffer mode.

getNextOffset

public final long getNextOffset()

Description copied from interface: IBufferStrategy

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

Specified by:

getNextOffset in interface IBufferStrategy

size

public final long size()

Description copied from interface: IRawStore

The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).

Specified by:

size in interface IRawStore

assertOpen

protected final void assertOpen()

isOpen

public boolean isOpen()

Description copied from interface: IRawStore

true iff the store is open.

Specified by:

isOpen in interface IRawStore

Returns:

true iff the store is open.

isReadOnly

public boolean isReadOnly()

Description copied from interface: IRawStore

true iff the store does not allow writes.

Specified by:

isReadOnly in interface IRawStore

close

public void close()

Manages the open flag state.

Specified by:

close in interface IRawStore

destroy

public final void destroy()

Description copied from interface: IRawStore

Closes the store immediately, deletes its persistent resources, and clears any records for the store from the IGlobalLRU.

Specified by:

destroy in interface IRawStore

See Also:

IRawStore.deleteResources()

overflow

public final boolean overflow(long needed)

Invoked if the store would exceed its current extent by IRawStore.write(ByteBuffer). The default behavior extends the capacity of the buffer by the at least the requested amount and a maximum of 32M or the Options.INITIAL_EXTENT.

If the data are fully buffered, then the maximum store size is limited to int32 bytes which is the maximum #of bytes that can be addressed in RAM (the pragmatic maximum is slightly less than 2G due to the limits of the JVM to address system memory).

Returns:

true if the capacity of the store was extended and the write operation should be retried.

transferFromDiskTo

protected static long transferFromDiskTo(IDiskBasedStrategy src,
                                         RandomAccessFile out)
                                  throws IOException

Helper method used by DiskBackedBufferStrategy and DiskOnlyStrategy to implement IBufferStrategy.transferTo(RandomAccessFile) using a FileChannel to FileChannel transfer.

Parameters:

src - The source.

out - The output file.

Returns:

The #of bytes transferred.

Throws:

IOException

getUUID

public UUID getUUID()

Not supported - this is available on the AbstractJournal.

Specified by:

getUUID in interface IRawStore

Throws:

UnsupportedOperationException - always

getResourceMetadata

public IResourceMetadata getResourceMetadata()

Not supported - this is available on the AbstractJournal.

Specified by:

getResourceMetadata in interface IRawStore

Throws:

UnsupportedOperationException - always

closeForWrites

public void closeForWrites()

Sets the readOnly flag.

Note: This method SHOULD be extended to release write caches, etc.

Specified by:

closeForWrites in interface IBufferStrategy