IndexSegmentCheckpoint (Blazegraph Database Platform 2.1.5 API)

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

All Implemented Interfaces:

ICheckpoint
```
public class IndexSegmentCheckpoint
extends Object
implements ICheckpoint
```
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$

Author:

Bryan Thompson

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`ByteBuffer`	`asReadOnlyBuffer()` Returns a new view of the read-only `ByteBuffer` containing the serialized representation of the `IndexSegmentCheckpoint` record.
`long`	`getBloomFilterAddr()` Address of the `IBloomFilter`.
`long`	`getCheckpointAddr()` The address used to read this `Checkpoint` record from the store.
`long`	`getCounter()` Return the value of the B+Tree local counter stored in the `Checkpoint` record.
`long`	`getEntryCount()` The #of index entries (aka tuple count).
`int`	`getGlobalDepth()` The global depth of the root directory (HTree only).
`int`	`getHeight()` The height of a B+Tree.
`IndexTypeEnum`	`getIndexType()` The type of index for this checkpoint record.
`long`	`getLeafCount()` The #of leaves (B+Tree), hash buckets (HTree), or ZERO (0) for a solution set stream.
`long`	`getMetadataAddr()` Address that can be used to read the `IndexMetadata` record for the index from the store.
`long`	`getNodeCount()` The #of non-leaf nodes (B+Tree) or directories (HTree).
`long`	`getRecordVersion()` Return the value of the next record version number to be assigned that is stored in the `Checkpoint` record.
`long`	`getRootAddr()` Address of the root node or leaf of the `BTree`.
`boolean`	`hasCheckpointAddr()` Return `true` iff the checkpoint address is defined.
`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.
- 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
  - getCheckpointAddr
```
public long getCheckpointAddr()
```
    The address used to read this Checkpoint record from the store.
    Note: This is set as a side-effect by #write(IRawStore).
    Note: The checkpoint is assembled from the root block by the constructor. There is no address from which it can be re-read.
    
    Specified by:
    
    getCheckpointAddr in interface ICheckpoint
    
    Returns:
    0L
  - hasCheckpointAddr
```
public boolean hasCheckpointAddr()
```
    Return true iff the checkpoint address is defined.
    Note: The checkpoint is assembled from the root block by the constructor. There is no address from which it can be re-read.
    
    Specified by:
    
    hasCheckpointAddr in interface ICheckpoint
    
    Returns:
    false
  - getMetadataAddr
```
public long getMetadataAddr()
```
    Description copied from interface: ICheckpoint
    
    Address that can be used to read the IndexMetadata record for the index from the store.
    
    Specified by:
    
    getMetadataAddr in interface ICheckpoint
  - getRootAddr
```
public long getRootAddr()
```
    Description copied from interface: ICheckpoint
    
    Address of the root node or leaf of the BTree.
    
    Specified by:
    
    getRootAddr in interface ICheckpoint
    
    Returns:
    The address of the root -or- 0L iff the index does not have a root page.
  - getBloomFilterAddr
```
public long getBloomFilterAddr()
```
    Description copied from interface: ICheckpoint
    
    Address of the IBloomFilter.
    
    Specified by:
    
    getBloomFilterAddr in interface ICheckpoint
    
    Returns:
    The address of the bloom filter -or- 0L iff the index does not have a bloom filter.
  - getHeight
```
public int getHeight()
```
    Description copied from interface: ICheckpoint
    
    The height of a B+Tree. ZERO(0) means just a root leaf. Values greater than zero give the #of levels of abstract nodes. There is always one layer of leaves which is not included in this value.
    
    Specified by:
    
    getHeight in interface ICheckpoint
    
    Returns:
    The global depth and ZERO (0) unless the checkpoint record is for an IndexTypeEnum.BTree
  - getGlobalDepth
```
public int getGlobalDepth()
```
    Description copied from interface: ICheckpoint
    
    The global depth of the root directory (HTree only).
    
    Specified by:
    
    getGlobalDepth in interface ICheckpoint
    
    Returns:
    The global depth and ZERO (0) unless the checkpoint record is for an IndexTypeEnum.HTree
  - getNodeCount
```
public long getNodeCount()
```
    Description copied from interface: ICheckpoint
    
    The #of non-leaf nodes (B+Tree) or directories (HTree). This is ZERO (0) for a non-recursive data structure such as a solution set stream.
    
    Specified by:
    
    getNodeCount in interface ICheckpoint
  - getLeafCount
```
public long getLeafCount()
```
    Description copied from interface: ICheckpoint
    
    The #of leaves (B+Tree), hash buckets (HTree), or ZERO (0) for a solution set stream.
    
    Specified by:
    
    getLeafCount in interface ICheckpoint
  - getEntryCount
```
public long getEntryCount()
```
    Description copied from interface: ICheckpoint
    
    The #of index entries (aka tuple count).
    
    Specified by:
    
    getEntryCount in interface ICheckpoint
  - getCounter
```
public long getCounter()
```
    Return the value of the B+Tree local counter stored in the Checkpoint record.
    Note: There is no counter associated with an IndexSegment. The counter is only available for the BTree.
    
    Specified by:
    
    getCounter in interface ICheckpoint
    
    Returns:
    0L
  - getRecordVersion
```
public long getRecordVersion()
```
    Description copied from interface: ICheckpoint
    
    Return the value of the next record version number to be assigned that is stored in the Checkpoint record. 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).
    
    Specified by:
    
    getRecordVersion in interface ICheckpoint
  - getIndexType
```
public IndexTypeEnum getIndexType()
```
    Description copied from interface: ICheckpoint
    
    The type of index for this checkpoint record.
    
    Specified by:
    
    getIndexType in interface ICheckpoint

Class IndexSegmentCheckpoint

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAGIC

VERSION0

VERSION1

VERSION2

currentVersion

segmentUUID

offsetBits

height

nleaves

nnodes

nentries

maxNodeOrLeafLength

offsetLeaves

extentLeaves

offsetNodes

extentNodes

offsetBlobs

extentBlobs

addrRoot

addrMetadata

addrBloom

addrFirstLeaf

addrLastLeaf

length

compactingMerge

useChecksums

commitTime

Constructor Detail

IndexSegmentCheckpoint

IndexSegmentCheckpoint

Method Detail

validate

asReadOnlyBuffer

write

toString

getCheckpointAddr

hasCheckpointAddr

getMetadataAddr

getRootAddr

getBloomFilterAddr

getHeight

getGlobalDepth

getNodeCount

getLeafCount

getEntryCount

getCounter

getRecordVersion

getIndexType