com.bigdata.btree

Interface ICheckpointProtocol

All Superinterfaces:

ICommitter, ICounterSetAccess, IReadWriteLockManager, ISimpleIndexAccess

All Known Subinterfaces:

ISolutionSet

All Known Implementing Classes:

AbstractBTree, AbstractHTree, BTree, CommitRecordIndex, CommitTimeIndex, CounterSetBTree, EventReceiver.EventBTree, HTree, IndexSegment, IndexSegmentIndex, JournalIndex, MetadataIndex, Name2Addr, SolutionSetStream, Stream, TestMROWTransactions.MyBTree, TestRestartSafe.MyBTree, TxId2CommitTimeIndex

public interface ICheckpointProtocol
extends ICommitter, ICounterSetAccess, ISimpleIndexAccess, IReadWriteLockManager

Interface in support of the Checkpoint record protocol.

Author:

thompsonbry@users.sourceforge.net TODO Try to lift out an abstract implementation of this interface for HTree, BTree, and Stream. This will be another step towards GIST support. There are protected methods which are used on those classes which should be lifted into the abstract base class. Also, try to reconcile this interface with ILocalBTreeView implementations that do not implement ICheckpointProtocol (FusedView, ReadCommittedView).

See Also:

GIST

Method Summary

Methods

Modifier and Type	Method and Description
void	close() The contract for close() is to reduce the resource burden of the index while not rendering the index inoperative.
BaseIndexStats	dumpPages(boolean recursive, boolean visitLeaves) Reports statistics for the index.
ICheckpoint	getCheckpoint() Returns the most recent ICheckpoint record.
IDirtyListener	getDirtyListener() Return the IDirtyListener.
IndexMetadata	getIndexMetadata() The metadata for the index.
long	getLastCommitTime() The timestamp associated with the last IAtomicStore.commit() in which writes buffered by this index were made restart-safe on the backing store.
long	getMetadataAddr() The address at which the most recent IndexMetadata record was written.
long	getRecordVersion() The value of the record version number that will be assigned to the next node or leaf written onto the backing store.
long	getRootAddr() The address of the last written root of the persistent data structure -or- 0L if there is no root.
boolean	isOpen() An "open" index has may have some buffered data.
void	reopen() (Re-) open the index.
void	setDirtyListener(IDirtyListener listener) Set or clear the listener (there can be only one).
void	setLastCommitTime(long lastCommitTime) Sets the lastCommitTime.
long	writeCheckpoint() Checkpoint operation must #flush() dirty nodes, dirty persistent data structures, etc, write a new Checkpoint record on the backing store, save a reference to the current Checkpoint, and return the address of that Checkpoint record.
Checkpoint	writeCheckpoint2() Checkpoint operation must #flush() dirty nodes, dirty persistent data structures, etc, write a new Checkpoint record on the backing store, save a reference to the current Checkpoint, and return the address of that Checkpoint record.

Methods inherited from interface com.bigdata.journal.ICommitter

handleCommit, invalidate

Methods inherited from interface com.bigdata.counters.ICounterSetAccess

getCounters

Methods inherited from interface com.bigdata.btree.ISimpleIndexAccess

getStore, rangeCount, removeAll, scan

Methods inherited from interface com.bigdata.btree.IReadWriteLockManager

getReadLockCount, isReadOnly, readLock, writeLock

Method Detail

getRecordVersion

long getRecordVersion()

The value of the record version number that will be assigned to the next node or leaf written onto the backing store. This number is incremented each time a node or leaf is written onto the backing store. The initial value is ZERO (0). The first value assigned to a node or leaf will be ZERO (0). TODO Nobody is actually incrementing this value right now.

getCheckpoint

ICheckpoint getCheckpoint()

Returns the most recent ICheckpoint record.

Returns:

The most recent ICheckpoint record and never null.

getMetadataAddr

long getMetadataAddr()

The address at which the most recent IndexMetadata record was written.

getRootAddr

long getRootAddr()

The address of the last written root of the persistent data structure -or- 0L if there is no root. A 0L return may be an indication that an empty data structure will be created on demand.

setLastCommitTime

void setLastCommitTime(long lastCommitTime)

Sets the lastCommitTime.

Note: The lastCommitTime is set by a combination of the AbstractJournal and Name2Addr based on the actual commitTime of the commit during which an Name2Addr.Entry for that index was last committed. It is set for both historical index reads and unisolated index reads using Name2Addr.Entry.commitTime. The lastCommitTime for an unisolated index will advance as commits are performed with that index.

Parameters:

lastCommitTime - The timestamp of the last committed state of this index.

Throws:

IllegalArgumentException - if lastCommitTime is ZERO (0).

IllegalStateException - if the timestamp is less than the previous value (it is permitted to advance but not to go backwards).

getLastCommitTime

long getLastCommitTime()

The timestamp associated with the last IAtomicStore.commit() in which writes buffered by this index were made restart-safe on the backing store. The lastCommitTime is set when the index is loaded from the backing store and updated after each commit. It is ZERO (0L) when an index is first created and will remain ZERO (0L) until the index is committed. If the backing store does not support atomic commits, then this value will always be ZERO (0L).

writeCheckpoint

long writeCheckpoint()

Checkpoint operation must #flush() dirty nodes, dirty persistent data structures, etc, write a new Checkpoint record on the backing store, save a reference to the current Checkpoint, and return the address of that Checkpoint record.

Note: A checkpoint by itself is NOT an atomic commit. The commit protocol is at the store level and uses Checkpoints to ensure that the state of the persistence capable data structure is current on the backing store.

Returns:

The address at which the Checkpoint record for the persistence capable was written onto the store. The data structure can be reloaded from this Checkpoint record.

writeCheckpoint2

Checkpoint writeCheckpoint2()

Checkpoint operation must #flush() dirty nodes, dirty persistent data structures, etc, write a new Checkpoint record on the backing store, save a reference to the current Checkpoint, and return the address of that Checkpoint record.

Note: A checkpoint by itself is NOT an atomic commit. The commit protocol is at the store level and uses Checkpoints to ensure that the state of the persistence capable data structure is current on the backing store.

Returns:

The Checkpoint record for the persistent data structure which was written onto the store. The persistent data structure can be reloaded from this Checkpoint record.

getDirtyListener

IDirtyListener getDirtyListener()

Return the IDirtyListener.

setDirtyListener

void setDirtyListener(IDirtyListener listener)

Set or clear the listener (there can be only one).

Parameters:

listener - The listener.

getIndexMetadata

IndexMetadata getIndexMetadata()

The metadata for the index. This is full of good stuff about the index.

Note: The same method is also declared by IIndex in order to provide access to the IndexMetadata for remote clients in scale-out.

See Also:

IIndex.getIndexMetadata()

reopen

void reopen()

(Re-) open the index. This method is part of a close() / reopen() protocol. That protocol may be used to reduce the resource burden of an index. This method is automatically invoked by a variety of methods that need to ensure that the index is available for use.

See Also:

close(), isOpen(), #getRoot()

close

void close()

The contract for close() is to reduce the resource burden of the index while not rendering the index inoperative. An index that has been closed MAY be reopened at any time (conditional on the continued availability of the backing store). Such an index reference remains valid after a close(). A closed index is transparently reopened by any access to the index data (scanning the index, probing the index, etc).

Note: A close() on a dirty index MUST discard writes rather than flushing them to the store and MUST NOT update its Checkpoint record - (close() is used to discard indices with partial writes when an AbstractTask fails). If you are seeking to close() a mutable index view that state can be recovered by reopen() then you MUST write a new Checkpoint record before closing the index.

isOpen

boolean isOpen()

An "open" index has may have some buffered data. A closed index will have to re-read any backing data from the backing store.

Returns:

If the index is "open".

See Also:

close(), reopen()

dumpPages

BaseIndexStats dumpPages(boolean recursive,
                       boolean visitLeaves)

Reports statistics for the index.

Parameters:

recursive - When true, also collects statistics on the pages (nodes and leaves) using a low-level approach.

visitLeaves - When true and recursive:=true then the leaves of the index are also visited.

Returns:

Some interesting statistics about the index (and optionally the pages in that index) which the caller can print out.

See Also:

pre-heat the journal on startup