RootBlockView (Blazegraph Database Platform 2.1.5 API)

java.lang.Object
- com.bigdata.journal.RootBlockView

All Implemented Interfaces:

IRootBlockView
```
public class RootBlockView
extends Object
implements IRootBlockView
```
A view onto a root block of the Journal.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields
Modifier and Type Field and Description

static int currentVersion
The current version for new root blocks.

static short SIZEOF_ROOT_BLOCK
- Fields inherited from interface com.bigdata.journal.IRootBlockView
  NO_BLOCK_SEQUENCE

Fields
Modifier and Type	Field and Description
`static int`	`currentVersion` The current version for new root blocks.
`static short`	`SIZEOF_ROOT_BLOCK`

Constructor Summary

Constructors
Constructor and Description
`RootBlockView(boolean rootBlock0, ByteBuffer buf, ChecksumUtility checker)` Create a new read-only view from the supplied buffer.
`RootBlockView(boolean rootBlock0, int offsetBits, long nextOffset, long firstCommitTime, long lastCommitTime, long commitCounter, long commitRecordAddr, long commitRecordIndexAddr, UUID uuid, long blockSequence, long quorumToken, long metaStartAddr, long metaBitsAddr, StoreTypeEnum storeTypeEnum, long createTime, long closeTime, int version, ChecksumUtility checker)` Create a new read-only root block image with a unique timestamp.

Method Summary

Methods
Modifier and Type	Method and Description
`ByteBuffer`	`asReadOnlyBuffer()` A read-only buffer whose contents are the root block.
`IRootBlockView`	`asRootBlock(boolean rootBlock0)` Return a version of the caller's root block that is flagged as either rootBlock0 or rootBlock1 as indicated by the argument.
`int`	`calcChecksum(ChecksumUtility checker)` Compute the checksum of the root block (excluding only the field including the checksum value itself).
`boolean`	`equals(Object o)` Overriden to implement equality based on the data in the `IRootBlockView`.
`long`	`getBlockSequence()` Return the #of `WriteCache` blocks that have been written out as part of the current write set.
`long`	`getChallisField()` The "Challis field" is written at both the head and the tail of each root block and is a strictly increasing value positive long integer.
`int`	`getChecksum(ChecksumUtility checker)` Return the checksum store in the root block (excluding only the field including the checksum value itself).
`long`	`getCloseTime()` The timestamp assigned as the time at which writes were disallowed for the journal.
`long`	`getCommitCounter()` The commit counter is a positive long integer that is strictly local to the store.
`long`	`getCommitRecordAddr()` Return the address at which the `ICommitRecord` for this root block is stored.
`long`	`getCommitRecordIndexAddr()` The address of the root of the `CommitRecordIndex`.
`long`	`getCreateTime()` The timestamp assigned as the creation time for the journal.
`long`	`getFirstCommitTime()` The database wide timestamp of first commit on the store -or- 0L if there have been no commits.
`long`	`getLastCommitTime()` The database wide timestamp of the most recent commit on the store or 0L iff there have been no commits.
`long`	`getLocalTime()` A purely informative field whose value is the system local timestamp of the last commit as reported by `System.currentTimeMillis()` or the time at which the store was created iff there have been no commits.
`long`	`getMetaBitsAddr()` For the `StoreTypeEnum.RW` store, where we will read the metadata bits from.
`long`	`getMetaStartAddr()` For the `StoreTypeEnum.RW` store, the start of the area of the file where the allocation blocks are allocated.
`long`	`getNextOffset()` The next offset at which a data item would be written on the store.
`int`	`getOffsetBits()` The #of bits in a 64-bit long integer address that are dedicated to the byte offset into the store.
`long`	`getQuorumToken()` The `Quorum` token associated with this commit point or `Quorum.NO_QUORUM` if there was no quorum.
`StoreTypeEnum`	`getStoreType()` A byte value which specifies whether the backing store is a journal (log-structured store or WORM) or a read-write store.
`UUID`	`getUUID()` The unique journal identifier
`int`	`getVersion()` The root block version number.
`int`	`hashCode()`
`boolean`	`isRootBlock0()` There are two root blocks and they are written in an alternating order.
`String`	`toString()`
`static String`	`toString(long t)` Format a commit time as the raw milliseconds since the epoch value plus a fully expressed date and time.
`void`	`valid()` Assertion throws exception unless the root block is valid.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - SIZEOF_ROOT_BLOCK
```
public static final transient short SIZEOF_ROOT_BLOCK
```
    See Also:
    Constant Field Values
  - currentVersion
```
public static final int currentVersion
```
    The current version for new root blocks. While different kinds of backing store (e.g., the RW and WORM as of this time) may have some fields which are not used by the other kinds of backing stores, they ALL share the same root block versioning system. Further, all evolutions in the root block versioning MUST be backwards compatible (earlier versions must be readable). Finally, new root block images MUST be formed using the currentVersion.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - RootBlockView
```
public RootBlockView(boolean rootBlock0,
             int offsetBits,
             long nextOffset,
             long firstCommitTime,
             long lastCommitTime,
             long commitCounter,
             long commitRecordAddr,
             long commitRecordIndexAddr,
             UUID uuid,
             long blockSequence,
             long quorumToken,
             long metaStartAddr,
             long metaBitsAddr,
             StoreTypeEnum storeTypeEnum,
             long createTime,
             long closeTime,
             int version,
             ChecksumUtility checker)
```
    Create a new read-only root block image with a unique timestamp. The other fields are populated from the supplied parameters.
    
    Parameters:
    offsetBits - The #of bits out of a 64-bit long integer that are used to encode the byte offset as an unsigned integer. The remaining bits are used to encode the byte count (aka record length) as an unsigned integer.
    nextOffset - The next offset at which a record will be written on the store.
    firstCommitTime - The timestamp of the earliest commit on the store or zero (0L) iff there have been no commits.
    lastCommitTime - The timestamp of the most recent commit on the store or zero (0L) iff there have been no commits. This is distinct from the values written as part of the Challis algorithm. The latter exist solely to detect commit failures. This timestamp is assigned by the transaction commit protocol.
    commitCounter - The commit counter. This should be ZERO (0L) for a new journal. For an existing journal, the value should be incremented by ONE (1) each time the root block is written (as part of a commit naturally).
    commitRecordAddr - The address at which the ICommitRecord containing the root addresses was written or 0L if there are no root addresses (this is true when the store is first created).
    commitRecordIndexAddr - The address at which the IndexMetadata for the CommitRecordIndex was written or 0L if there are no historical ICommitRecords (this is true when the store is first created).
    uuid - The unique journal identifier.
    blockSequence - The WriteCache block sequence number as of the commit point (origin ZERO(0)).
    quorumToken - The current quorum token if this commit point is part of a Quorum.
    metaStartAddr - For the StoreTypeEnum.RW store, the start of the area of the file where the allocation blocks are allocated. This is also a byte offset into the file and is stored as a 64-bit integer. It is called metaStartAddr because that is the offset that is used with the metaBitsAddr to determine how to find the allocation blocks. The value for a WORM store is ZERO (0).
    metaBitsAddr - For the StoreTypeEnum.RW store, where we will read the metadata bits from. When we start the store up we need to retrieve the metabits from this address. This is a byte offset into the file and is stored as a long integer. Normal addresses are calculated with reference to the allocation blocks. The value for a WORM store is ZERO (0).
    storeTypeEnum - The kind of persistence store. See StoreTypeEnum.
    checker - An object that is used to compute the checksum to be stored in the root block (required).
    createTime - The timestamp of the creation event for the journal. This is mainly used by the ResourceManager to impose a chronological order on the journals.
    closeTime - ZERO(0L) unless the journal has been closed for write operations, in which case this is the timestamp of the event that disallowed further writes on this journal. This is mainly used by the ResourceManager to indicate that a journal is no longer available for writing (because it has been superseded by another journal).
    version -
  - RootBlockView
```
public RootBlockView(boolean rootBlock0,
             ByteBuffer buf,
             ChecksumUtility checker)
              throws RootBlockException
```
    Create a new read-only view from the supplied buffer.
    
    Parameters:
    rootBlock0 - There are two root blocks and they are written in an alternating order. For the sake of distinction, the first one is referred to as "rootBlock0" while the 2nd one is referred to as "rootBlock1". This parameter allows the caller to store a transient field on the view that indicates which root block it represents.
    buf - The buffer.
    checker - An object used to compute the checksum of the root block (optional, when null the checksum stored in the root block will not be verified).
    
    Throws:
    
    IllegalArgumentException - if the buffer is null or if the #of bytes remaining in the buffer is not exactly SIZEOF_ROOT_BLOCK.
    
    RootBlockException - if the root block is not valid (bad magic, timestamps do not agree, etc).
- Method Detail
  - isRootBlock0
```
public boolean isRootBlock0()
```
    Description copied from interface: IRootBlockView
    
    There are two root blocks and they are written in an alternating order. For the sake of distinction, the first one is referred to as "rootBlock0" while the 2nd one is referred to as "rootBlock1". This method indicates which root block is represented by this view based on metadata supplied to the constructor (the distinction is not persistent on disk).
    
    Specified by:
    
    isRootBlock0 in interface IRootBlockView
    
    Returns:
    True iff the root block view was constructed from "rootBlock0".
  - asReadOnlyBuffer
```
public ByteBuffer asReadOnlyBuffer()
```
    Description copied from interface: IRootBlockView
    
    A read-only buffer whose contents are the root block. The position, limit, and mark will be independent for each ByteBuffer that is returned by this method.
    
    Specified by:
    
    asReadOnlyBuffer in interface IRootBlockView
  - asRootBlock
```
public IRootBlockView asRootBlock(boolean rootBlock0)
```
    Description copied from interface: IRootBlockView
    
    Return a version of the caller's root block that is flagged as either rootBlock0 or rootBlock1 as indicated by the argument. Root blocks are immutable, so this will either return your argument or return a new IRootBlockView in which the sense of the IRootBlockView.isRootBlock0() flag is now correct.
    
    Specified by:
    
    asRootBlock in interface IRootBlockView
    
    Parameters:
    rootBlock0 - Whether you want rootBlock0 or rootBlock1.
    
    Returns:
    The root block.
  - hashCode
```
public int hashCode()
```
    Overridden to implement the hash code as the hash code of the data in the backing ByteBuffer. The IRootBlockView is immutable. The hash code is computed lazily. Once computed, the hash code is NOT recomputed for the same IRootBlockView.
    
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object o)
```
    Overriden to implement equality based on the data in the IRootBlockView.
    
    Overrides:
    
    equals in class Object
  - getVersion
```
public int getVersion()
```
    Description copied from interface: IRootBlockView
    
    The root block version number.
    
    Specified by:
    
    getVersion in interface IRootBlockView
  - getOffsetBits
```
public int getOffsetBits()
```
    Description copied from interface: IRootBlockView
    
    The #of bits in a 64-bit long integer address that are dedicated to the byte offset into the store.
    
    Specified by:
    
    getOffsetBits in interface IRootBlockView
    
    See Also:
    WormAddressManager
  - getNextOffset
```
public long getNextOffset()
```
    Description copied from interface: IRootBlockView
    
    The next offset at which a data item would be written on the store. FIXME The RWStore has different semantics for this field. Document those semantics and modify AbstractJournal so we can directly decide how many bytes were "written" (for the WORM) or were "allocated" (for the RWStore, in which case it should probably be the net of the bytes allocated and released). Update all the locations in the code which rely on IRootBlockView.getNextOffset() to compute the #of bytes written onto the store.
    
    Specified by:
    
    getNextOffset in interface IRootBlockView
  - getLocalTime
```
public long getLocalTime()
```
    A purely informative field whose value is the system local timestamp of the last commit as reported by System.currentTimeMillis() or the time at which the store was created iff there have been no commits. Unlike getFirstCommitTime() and getLastCommitTime() this field does NOT provide a guarantee that time is strictly increasing.
    Note: This field is stored for post-mortem purposes and is NOT used internally.
    
    Returns:
    A purely informative field whose value is the system local timestamp of the last commit.
  - getFirstCommitTime
```
public long getFirstCommitTime()
```
    Description copied from interface: IRootBlockView
    
    The database wide timestamp of first commit on the store -or- 0L if there have been no commits. In a local database, this timestamp is generated by a local timestamp service. In a distributed database, this timestamp is generated by a shared timestamp service. The timestamps returned by this method are strictly increasing for a given store and for a given database.
    
    Specified by:
    
    getFirstCommitTime in interface IRootBlockView
    
    Returns:
    The timestamp of the first commit on the store or 0L iff there have been no commits.
  - getLastCommitTime
```
public long getLastCommitTime()
```
    Description copied from interface: IRootBlockView
    
    The database wide timestamp of the most recent commit on the store or 0L iff there have been no commits. In a local database, this timestamp is generated by a local timestamp service. In a distributed database, this timestamp is generated by a shared timestamp service. The timestamps returned by this method are strictly increasing for a given store and for a given database.
    
    Specified by:
    
    getLastCommitTime in interface IRootBlockView
    
    Returns:
    The timestamp of the most recent commit on the store or 0L iff there have been no commits.
  - getChallisField
```
public long getChallisField()
                     throws RootBlockException
```
    The "Challis field" is written at both the head and the tail of each root block and is a strictly increasing value positive long integer. This field is used to detect partial writes of the root blocks (the values of the field in a given root block will not agree). This field is also used to identify which of the two root blocks is more recent (it will have the larger value for this field).
    
    Returns:
    The value of the "Challis" field.
    
    Throws:
    
    RootBlockException - if the values on the root block do not agree.
  - getCommitCounter
```
public long getCommitCounter()
```
    Description copied from interface: IRootBlockView
    
    The commit counter is a positive long integer that is strictly local to the store. The commit counter is used to avoid problems with timestamps generated by different machines or when time goes backwards or other nasty stuff. The correct root block is chosen by selecting the valid root block with the larger commit counter (the value of the commit counter is reused by the Challis field).
    
    Specified by:
    
    getCommitCounter in interface IRootBlockView
    
    Returns:
    The commit counter.
  - getCommitRecordAddr
```
public long getCommitRecordAddr()
```
    Description copied from interface: IRootBlockView
    
    Return the address at which the ICommitRecord for this root block is stored. The ICommitRecords are stored separately from the root block so that they may be indexed by the commit timestamps. This is necessary in order to be able to quickly recover the root addresses for a given commit timestamp, which is a featured used to support transactional isolation.
    Note: When a logical journal may overflow onto more than one physical journal then the address of the ICommitRecord MAY refer to a historical physical journal and care MUST be exercised to resolve the address against the appropriate journal file. [This paragraph is probably not valid. Verify and remove if it is not true.]
    
    Specified by:
    
    getCommitRecordAddr in interface IRootBlockView
    
    Returns:
    The address at which the ICommitRecord for this root block is stored.
  - getCommitRecordIndexAddr
```
public long getCommitRecordIndexAddr()
```
    Description copied from interface: IRootBlockView
    
    The address of the root of the CommitRecordIndex. The CommitRecordIndex contains the ordered addresses of the historical ICommitRecords on the Journal. The address of the CommitRecordIndex is stored directly in the root block rather than the ICommitRecord since we can not obtain this address until after we have formatted and written the ICommitRecord.
    
    Specified by:
    
    getCommitRecordIndexAddr in interface IRootBlockView
  - valid
```
public void valid()
```
    Description copied from interface: IRootBlockView
    
    Assertion throws exception unless the root block is valid. Conditions tested include the root block MAGIC and the root block timestamps (there are two and they must agree).
    
    Specified by:
    
    valid in interface IRootBlockView
  - getUUID
```
public UUID getUUID()
```
    Description copied from interface: IRootBlockView
    
    The unique journal identifier
    
    Specified by:
    
    getUUID in interface IRootBlockView
  - getCreateTime
```
public long getCreateTime()
```
    Description copied from interface: IRootBlockView
    
    The timestamp assigned as the creation time for the journal.
    
    Specified by:
    
    getCreateTime in interface IRootBlockView
  - getCloseTime
```
public long getCloseTime()
```
    Description copied from interface: IRootBlockView
    
    The timestamp assigned as the time at which writes were disallowed for the journal.
    
    Specified by:
    
    getCloseTime in interface IRootBlockView
  - getChecksum
```
public int getChecksum(ChecksumUtility checker)
                throws RootBlockException
```
    Return the checksum store in the root block (excluding only the field including the checksum value itself).
    
    Parameters:
    checker - An object used to compute the checksum. Note that you can disable the checksum test by passing in a null value here.
    
    Returns:
    The checksum stored in the root block.
    
    Throws:
    
    RootBlockException - if the checksum stored in the root block does not agree with the checksum computed by calcChecksum(ChecksumUtility).
  - calcChecksum
```
public int calcChecksum(ChecksumUtility checker)
```
    Compute the checksum of the root block (excluding only the field including the checksum value itself).
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toString
```
public static String toString(long t)
```
    Format a commit time as the raw milliseconds since the epoch value plus a fully expressed date and time.
    
    Parameters:
    t - The commit time.
    
    Returns:
    The date and time strong.
  - getMetaBitsAddr
```
public long getMetaBitsAddr()
```
    Description copied from interface: IRootBlockView
    
    For the StoreTypeEnum.RW store, where we will read the metadata bits from. When we start the store up we need to retrieve the metabits from this address. This is a byte offset into the file and is stored as a long integer. Normal addresses are calculated with reference to the allocation blocks. The value for a WORM store is ZERO (0).
    
    Specified by:
    
    getMetaBitsAddr in interface IRootBlockView
  - getMetaStartAddr
```
public long getMetaStartAddr()
```
    Description copied from interface: IRootBlockView
    
    For the StoreTypeEnum.RW store, the start of the area of the file where the allocation blocks are allocated. This is also a byte offset into the file and is stored as a 64-bit integer. It is called metaStartAddr because that is the offset that is used with the metaBitsAddr to determine how to find the allocation blocks. The value for a WORM store is ZERO (0).
    
    Specified by:
    
    getMetaStartAddr in interface IRootBlockView
  - getStoreType
```
public StoreTypeEnum getStoreType()
```
    A byte value which specifies whether the backing store is a journal (log-structured store or WORM) or a read-write store. Only two values are defined at present. ZERO (0) is a WORM; ONE (1) is a read/write store.
    Note: The OFFSET_STORETYPE field was defined in VERSION1. The default value for that field before VERSION1 is StoreTypeEnum.WORM since only the WORM persistence store existed in earlier versions of the root block.
    
    Specified by:
    
    getStoreType in interface IRootBlockView
  - getQuorumToken
```
public long getQuorumToken()
```
    The Quorum token associated with this commit point or Quorum.NO_QUORUM if there was no quorum.
    Note: If commit points are part of the resynchronization protocol, they MUST NOT use the current quorum token unless the service is synchronized with the quorum at that commit point.
    Note: The quorum token was introduced in VERSION2. The default value for that field before VERSION2 is {Quorum#NO_QUORUM}.
    
    Specified by:
    
    getQuorumToken in interface IRootBlockView
  - getBlockSequence
```
public long getBlockSequence()
```
    Return the #of WriteCache blocks that have been written out as part of the current write set. This value is origin ZERO (0) and is reset to ZERO (0) after each commit or abort.
    Note: The write cache block sequence was introduced in VERSION3. The default value for that field before VERSION3 is .
    
    Specified by:
    
    getBlockSequence in interface IRootBlockView

Class RootBlockView

Field Summary

Fields inherited from interface com.bigdata.journal.IRootBlockView

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SIZEOF_ROOT_BLOCK

currentVersion

Constructor Detail

RootBlockView

RootBlockView

Method Detail

isRootBlock0

asReadOnlyBuffer

asRootBlock

hashCode

equals

getVersion

getOffsetBits

getNextOffset

getLocalTime

getFirstCommitTime

getLastCommitTime

getChallisField

getCommitCounter

getCommitRecordAddr

getCommitRecordIndexAddr

valid

getUUID

getCreateTime

getCloseTime

getChecksum

calcChecksum

toString

toString

getMetaBitsAddr

getMetaStartAddr

getStoreType

getQuorumToken

getBlockSequence