IRootBlockView (Blazegraph Database Platform 2.1.5 API)

All Known Implementing Classes:

RootBlockView
```
public interface IRootBlockView
```
Interface for a root block on the journal. The root block provides metadata about the journal. The journal has two root blocks. The root blocks are written in an alternating order according to the Challis algorithm. Each root block includes a field at the head and tail whose value is strictly increasing fields. This field is often referred to as a root block "timestamps", but in practice we use the commit counter. On restart, the root block is choosen whose (a) strictly increasing fields agree; and (b) whose value on those fields is greater. This protected against both crashes and partial writes of the root block itself.
The commit counter is a store local strictly increasing non-negative long integer (commit counters are distinct for each store regardless of whether they are part of the same distributed database). The commit counters MUST be strictly increasing (a) so that they place the commit records into a total ordering; (b) so that the more current root block may be choose by comparing the value of the field in each of the two root blocks; and (c) so that a partial write of a root block may be detected by the presence of different values for the field at the head and tail of a given root block. The commit counter is also used as the field written at the head and tail of each root block according to the Challis algorithm. If those fields are the same then the root block is assumed to have been completely written.
Note that random data may still result in an identical value during a partial write. This possibility is guarded against by storing the checksum of the root block.
The first and last commit times are persisted in each root block in order to support both unisolated commits and transactions, whether in a local or a distributed database. These "times" are generated by the appropriate ITransactionManagerService service, which is responsible both for assigning transaction start times (which are in fact the transaction identifier) and transaction commit times, which are stored in root blocks of the various stored that participate in a given database and reported via getFirstCommitTime() and getLastCommitTime(). While these do not strictly speaking have to be "times" they do have to be assigned using the same measure as the transaction identifiers, so either a coordinated time server or a strictly increasing counter. Regardless, we need to know "when" a transaction commits as well as "when" it starts whether we measure "when" using a counter or a clock. Also note that we need to assign "commit times" even when the operation is unisolated. This means that we have to coordinate an unisolated commit on a store that is part of a distributed database with the centralized transaction manager. This should be done as part of the group commit since we are waiting at that point anyway to optimize IO by minimizing syncs to disk.
Note that some file systems or disks can re-order writes of by the application and write the data in a more efficient order. This can cause the root blocks to be written before the application data is stable on disk. The Options.DOUBLE_SYNC option exists to defeat this behavior and ensure restart-safety for such systems.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields
Modifier and Type Field and Description

static long NO_BLOCK_SEQUENCE
The value used for getBlockSequence() for both historical stores and for stores that do not support this concept.

Fields
Modifier and Type	Field and Description
`static long`	`NO_BLOCK_SEQUENCE` The value used for `getBlockSequence()` for both historical stores and for stores that do not support this concept.

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.
`long`	`getBlockSequence()` Return the #of `WriteCache` blocks that have been written out as part of the current write set.
`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`	`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.
`boolean`	`isRootBlock0()` There are two root blocks and they are written in an alternating order.
`void`	`valid()` Assertion throws exception unless the root block is valid.

- Field Detail
  - NO_BLOCK_SEQUENCE
```
static final long NO_BLOCK_SEQUENCE
```
    The value used for getBlockSequence() for both historical stores and for stores that do not support this concept.
    
    See Also:
    Constant Field Values
- Method Detail
  - valid
```
void valid()
           throws RootBlockException
```
    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).
    
    Throws:
    
    RootBlockException
  - isRootBlock0
```
boolean isRootBlock0()
```
    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).
    
    Returns:
    True iff the root block view was constructed from "rootBlock0".
  - getVersion
```
int getVersion()
```
    The root block version number.
  - getNextOffset
```
long getNextOffset()
```
    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 getNextOffset() to compute the #of bytes written onto the store.
  - getFirstCommitTime
```
long getFirstCommitTime()
```
    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.
    
    Returns:
    The timestamp of the first commit on the store or 0L iff there have been no commits.
  - getLastCommitTime
```
long getLastCommitTime()
```
    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.
    
    Returns:
    The timestamp of the most recent commit on the store or 0L iff there have been no commits.
  - getCommitCounter
```
long getCommitCounter()
```
    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).
    
    Returns:
    The commit counter.
  - getCommitRecordAddr
```
long getCommitRecordAddr()
```
    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.]
    
    Returns:
    The address at which the ICommitRecord for this root block is stored.
  - getCommitRecordIndexAddr
```
long getCommitRecordIndexAddr()
```
    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.
  - getUUID
```
UUID getUUID()
```
    The unique journal identifier
  - getOffsetBits
```
int getOffsetBits()
```
    The #of bits in a 64-bit long integer address that are dedicated to the byte offset into the store.
    
    See Also:
    WormAddressManager
  - getCreateTime
```
long getCreateTime()
```
    The timestamp assigned as the creation time for the journal.
  - getCloseTime
```
long getCloseTime()
```
    The timestamp assigned as the time at which writes were disallowed for the journal.
  - getStoreType
```
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.
  - getMetaBitsAddr
```
long getMetaBitsAddr()
```
    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).
  - getMetaStartAddr
```
long getMetaStartAddr()
```
    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).
  - getQuorumToken
```
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.
  - getBlockSequence
```
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.
  - asReadOnlyBuffer
```
ByteBuffer asReadOnlyBuffer()
```
    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.
  - asRootBlock
```
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. Root blocks are immutable, so this will either return your argument or return a new IRootBlockView in which the sense of the isRootBlock0() flag is now correct.
    
    Parameters:
    rootBlock0 - Whether you want rootBlock0 or rootBlock1.
    
    Returns:
    The root block.

Interface IRootBlockView

Field Summary

Method Summary

Field Detail

NO_BLOCK_SEQUENCE

Method Detail

valid

isRootBlock0

getVersion

getNextOffset

getFirstCommitTime

getLastCommitTime

getCommitCounter

getCommitRecordAddr

getCommitRecordIndexAddr

getUUID

getOffsetBits

getCreateTime

getCloseTime

getStoreType

getMetaBitsAddr

getMetaStartAddr

getQuorumToken

getBlockSequence

asReadOnlyBuffer

asRootBlock