com.bigdata.btree
Class IndexSegmentCheckpoint

java.lang.Object
  com.bigdata.btree.IndexSegmentCheckpoint

public class IndexSegmentCheckpoint
extends Object

The checkpoint record for an IndexSegment.

The checkpoint record for the index segment file is written at the head of the file. It should have identical timestamps at the start and end of the checkpoint record (e.g., it doubles as a root block). Since the file format is immutable it is ok to have what is essentially only a single root block. If the timestamps do not agree then the build was not successfully completed.

Similar to the BTree's Checkpoint record, this record contains only data that pertains specifically to the IndexSegment checkpoint or data otherwise required to bootstrap the load of the IndexSegment from the file. General purpose metadata is stored in the IndexMetadata record.

Version:

$Id: IndexSegmentCheckpoint.java 5897 2012-01-27 17:45:20Z thompsonbry $

Author:

Bryan Thompson

Field Summary

long	addrBloom Address of the optional bloom filter and 0L iff no bloom filter was constructed.
long	addrFirstLeaf Address of the first leaf in the file.
long	addrLastLeaf Address of the last leaf in the file.
long	addrMetadata The address of the IndexMetadata record.
long	addrRoot Address of the root node or leaf in the file.
long	commitTime The commit time associated with the view from which the IndexSegment was generated.
boolean	compactingMerge true iff the caller asserted that the IndexSegment was a fused view of the source index (partition) as of the specified commitTime.
static int	currentVersion The current serialization version.
long	extentBlobs The #of bytes in the optional contiguous region containing the raw records to be resolved by blob references or 0L iff there are no raw records in this region.
long	extentLeaves The #of bytes in the contiguous region containing the serialized leaves in the file.
long	extentNodes The #of bytes in the contiguous region containing the serialized nodes in the file or 0L iff there are no nodes in the file.
int	height Height of the index segment (origin zero, so height := 0 means that there is only a root leaf in the tree).
long	length Length of the file in bytes.
static int	MAGIC Magic value written at the start of the IndexSegmentCheckpoint record.
int	maxNodeOrLeafLength The maximum #of bytes in any node or leaf stored on the IndexSegment.
long	nentries The #of index entries serialized in the file (non-negative and MAY be zero).
int	nleaves The #of leaves serialized in the file.
int	nnodes The #of nodes serialized in the file.
int	offsetBits The #of bits in an 64-bit long integer address that are used to represent the byte offset into the IndexSegmentStore.
long	offsetBlobs The offset of the optional contiguous region containing the raw records to be resolved by blob references or 0L iff there are no raw records in this region.
long	offsetLeaves The offset of the contiguous region containing the serialized leaves in the file.
long	offsetNodes The offset of the contiguous region containing the serialized nodes in the file or 0L iff there are no nodes in the file.
UUID	segmentUUID UUID for this IndexSegment (it is a unique identifier for the index segment resource and is reported as the UUID of the IndexSegmentStore).
boolean	useChecksums true iff record level checksums are in use for the IndexSegment.
static int	VERSION0 Version 0 of the serialization format.
static int	VERSION1 Version 1 of the serialization format introduces an option for record level checksums.
static int	VERSION2 Version 2 of the serialization format replaced the int32 value for nentries with an int64 value.

Constructor Summary

IndexSegmentCheckpoint(int offsetBits, int height, int nleaves, int nnodes, long nentries, int maxNodeOrLeafLength, long offsetLeaves, long extentLeaves, long offsetNodes, long extentNodes, long offsetBlobs, long extentBlobs, long addrRoot, long addrMetadata, long addrBloom, long addrFirstLeaf, long addrLastLeaf, long length, boolean compactingMerge, boolean useChecksums, UUID segmentUUID, long commitTime)
Create a new checkpoint record in preparation for writing it on a file containing a newly constructed IndexSegment.

IndexSegmentCheckpoint(RandomAccessFile raf)
Reads the IndexSegmentCheckpoint record for the IndexSegment.

Method Summary

ByteBuffer	asReadOnlyBuffer() Returns a new view of the read-only ByteBuffer containing the serialized representation of the IndexSegmentCheckpoint record.
String	toString() A human readable representation of the IndexSegmentCheckpoint record.
void	validate() Test validity of the IndexSegmentCheckpoint record.
void	write(RandomAccessFile raf) Write the checkpoint record at the start of the file.

Methods inherited from class java.lang.Object

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

Field Detail

MAGIC

public static final transient int MAGIC

Magic value written at the start of the IndexSegmentCheckpoint record.

See Also:

Constant Field Values

VERSION0

public static final transient int VERSION0

Version 0 of the serialization format.

See Also:

Constant Field Values

VERSION1

public static final transient int VERSION1

Version 1 of the serialization format introduces an option for record level checksums. New fields in this version include:

useChecksums

true iff record level checksums are enabled. The default for earlier versions is false, which provides backward compatibility for existing IndexSegment files.

See Also:

Constant Field Values

VERSION2

public static final transient int VERSION2

Version 2 of the serialization format replaced the int32 value for nentries with an int64 value.

See Also:

Constant Field Values

currentVersion

public static final transient int currentVersion

The current serialization version.

See Also:

Constant Field Values

segmentUUID

public final UUID segmentUUID

UUID for this IndexSegment (it is a unique identifier for the index segment resource and is reported as the UUID of the IndexSegmentStore).

offsetBits

public final int offsetBits

The #of bits in an 64-bit long integer address that are used to represent the byte offset into the IndexSegmentStore.

height

public final int height

Height of the index segment (origin zero, so height := 0 means that there is only a root leaf in the tree).

nleaves

public final int nleaves

The #of leaves serialized in the file.

Note: IndexSegmentBuilder is restricted to MAX_INT leaves in its build plan.

nnodes

public final int nnodes

The #of nodes serialized in the file. If zero, then nleaves MUST be ONE (1) and the index consists solely of a root leaf.

Note: IndexSegmentBuilder is restricted to MAX_INT leaves in its build plan and there are always more leaves than nodes in a BTree so this is also an int32 value.

nentries

public final long nentries

The #of index entries serialized in the file (non-negative and MAY be zero).

maxNodeOrLeafLength

public final int maxNodeOrLeafLength

The maximum #of bytes in any node or leaf stored on the IndexSegment.

Note: while this appears to be unused now, it is still of interest and will be retained.

offsetLeaves

public final long offsetLeaves

The offset of the contiguous region containing the serialized leaves in the file.

Note: The offset must be equal to SIZE since the leaves are written immediately after the IndexSegmentCheckpoint record.

extentLeaves

public final long extentLeaves

The #of bytes in the contiguous region containing the serialized leaves in the file.

offsetNodes

public final long offsetNodes

The offset of the contiguous region containing the serialized nodes in the file or 0L iff there are no nodes in the file.

extentNodes

public final long extentNodes

The #of bytes in the contiguous region containing the serialized nodes in the file or 0L iff there are no nodes in the file.

offsetBlobs

public final long offsetBlobs

The offset of the optional contiguous region containing the raw records to be resolved by blob references or 0L iff there are no raw records in this region.

extentBlobs

public final long extentBlobs

The #of bytes in the optional contiguous region containing the raw records to be resolved by blob references or 0L iff there are no raw records in this region.

addrRoot

public final long addrRoot

Address of the root node or leaf in the file.

addrMetadata

public final long addrMetadata

The address of the IndexMetadata record.

addrBloom

public final long addrBloom

Address of the optional bloom filter and 0L iff no bloom filter was constructed.

addrFirstLeaf

public final long addrFirstLeaf

Address of the first leaf in the file.

addrLastLeaf

public final long addrLastLeaf

Address of the last leaf in the file.

length

public final long length

Length of the file in bytes.

compactingMerge

public final boolean compactingMerge

true iff the caller asserted that the IndexSegment was a fused view of the source index (partition) as of the specified commitTime. false implies that the IndexSegment is the result of an incremental build. This flag is important when attempting a bottom up reconstruction of a scale-out index from its components on various journals and IndexSegmentStores.

useChecksums

public final boolean useChecksums

true iff record level checksums are in use for the IndexSegment.

See Also:

VERSION1

commitTime

public final long commitTime

The commit time associated with the view from which the IndexSegment was generated. The IndexSegment state is equivalent to the state of the view as of that timestamp. However, the IndexSegment provides a view of only a single commit point in contrast to the many commit points that are typically available on a Journal.

Note: This field is written at the head and tail of the IndexSegmentCheckpoint record. If the timestamps on that record do not agree then the build operation probably failed while writing the checkpoint record.

Constructor Detail

IndexSegmentCheckpoint

public IndexSegmentCheckpoint(RandomAccessFile raf)
                       throws IOException

Reads the IndexSegmentCheckpoint record for the IndexSegment. The operation seeks to the start of the file and uses relative reads with the file pointer.

Parameters:

raf - The file.

Throws:

IOException - If there is a IO problem.

RootBlockException - if the IndexSegmentCheckpoint record is invalid (it doubles as a root block), including if the total file length is not large enough to contain an valid IndexSegmentCheckpoint record.

IndexSegmentCheckpoint

public IndexSegmentCheckpoint(int offsetBits,
                              int height,
                              int nleaves,
                              int nnodes,
                              long nentries,
                              int maxNodeOrLeafLength,
                              long offsetLeaves,
                              long extentLeaves,
                              long offsetNodes,
                              long extentNodes,
                              long offsetBlobs,
                              long extentBlobs,
                              long addrRoot,
                              long addrMetadata,
                              long addrBloom,
                              long addrFirstLeaf,
                              long addrLastLeaf,
                              long length,
                              boolean compactingMerge,
                              boolean useChecksums,
                              UUID segmentUUID,
                              long commitTime)

Create a new checkpoint record in preparation for writing it on a file containing a newly constructed IndexSegment.

TODO:

javadoc.

Method Detail

validate

public void validate()

Test validity of the IndexSegmentCheckpoint record.

asReadOnlyBuffer

public ByteBuffer asReadOnlyBuffer()

Returns a new view of the read-only ByteBuffer containing the serialized representation of the IndexSegmentCheckpoint record.

write

public void write(RandomAccessFile raf)
           throws IOException

Write the checkpoint record at the start of the file.

Parameters:

raf - The file.

Throws:

IOException

toString

public String toString()

A human readable representation of the IndexSegmentCheckpoint record.

Overrides:

toString in class Object