AbstractJournal (Blazegraph Database Platform 2.1.5 API)

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

All Implemented Interfaces:

ICounterSetAccess, IAtomicStore, IBTreeManager, IGISTLocalManager, IGISTManager, IIndexManager, IIndexStore, IJournal, IAddressManager, IAllocationManagerStore, IMRMW, IMROW, IRawStore, IStreamStore, IAllocationManager

Direct Known Subclasses:

Journal, StoreManager.ManagedJournal
```
public abstract class AbstractJournal
extends Object
implements IJournal, IAllocationManager, IAllocationManagerStore
```
The journal is a persistence capable data structure supporting atomic commit, named indices, and full transactions. The BufferMode.DiskRW mode provides an persistence scheme based on reusable allocation slots while the BufferMode.DiskWORM mode provides an append only persistence scheme. Journals may be configured in highly available quorums.

This class is an abstract implementation of the IJournal interface that does not implement the IConcurrencyManager, IResourceManager, or ITransactionService interfaces. The Journal provides a concrete implementation that may be used for a standalone database complete with concurrency control and transaction management.

Limitations

The IIndexStore implementation on this class is NOT thread-safe. The basic limitation is that the mutable BTree is NOT thread-safe. The getIndex(String) method exposes this mutable BTree. If you use this method to access the mutable BTree then YOU are responsible for avoiding concurrent writes on the returned object.

See IConcurrencyManager.submit(AbstractTask) for a thread-safe API that provides suitable concurrency control for both isolated and unisolated operations on named indices. Note that the use of the thread-safe API does NOT protect against applications that directly access the mutable BTree using getIndex(String).

The IRawStore interface on this class is thread-safe. However, this is a low-level API that is not used by directly by most applications. The BTree class uses this low-level API to read and write its nodes and leaves on the store. Applications generally use named indices rather than the IRawStore interface.

Note: transaction processing MAY occur be concurrent since the write set of a each transaction is written on a distinct TemporaryStore. However, without additional concurrency controls, each transaction is NOT thread-safe and MUST NOT be executed by more than one concurrent thread. Again, see IConcurrencyManager.submit(AbstractTask) for a high-concurrency API for both isolated operations (transactions) and unisolated operations. Note that the TemporaryStore backing a transaction will spill automatically from memory onto disk if the write set of the transaction grows too large.

Commit processing

The journal maintains two root blocks. Commit updates the root blocks using the Challis algorithm. (The root blocks are updated using an alternating pattern and "timestamps" are recorded at the head and tail of each root block to detect partial writes. See IRootBlockView and RootBlockView.) When the journal is backed by a disk file, the data are optionally flushed to disk on commit. If desired, the writes may be flushed before the root blocks are updated to ensure that the writes are not reordered - see Options.DOUBLE_SYNC.

Author:

Bryan Thompson

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected class`	`AbstractJournal.BasicHA` Implementation hooks into the various low-level operations required to support HA for the journal.
`static interface`	`AbstractJournal.ISnapshotData`
`static interface`	`AbstractJournal.ISnapshotEntry`
`static class`	`AbstractJournal.SnapshotData`

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DELETEBLOCK` The index of the root address of the delete blocks associated with this transaction.
`protected boolean`	`deleteOnClose` Option set by the test suites causes the file backing the journal to be deleted when the journal is closed.
`protected boolean`	`doubleSync` Option controls whether the journal forces application data to disk before updating the root blocks.
`protected ForceEnum`	`forceOnCommit` Option controls how the journal behaves during a commit.
`protected static org.apache.log4j.Logger`	`haLog` Logger for HA events.
`static int`	`PREV_ROOTBLOCK` The index of the root address where the root block copy from the previous commit is stored.
`protected Properties`	`properties` A clone of the properties used to initialize the `Journal`.
`static int`	`ROOT_ICUVERSION` The index of the root address containing the `ICUVersionRecord`.
`static int`	`ROOT_NAME2ADDR` The index of the root address containing the address of the persistent `Name2Addr` mapping names to `BTree`s registered for the store.
`File`	`tmpDir` The directory that should be used for temporary files.

Fields inherited from interface com.bigdata.rawstore.IAddressManager
NULL

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractJournal(Properties properties)` Create or re-open a journal.
`protected`	`AbstractJournal(Properties properties, Quorum<HAGlue,QuorumService<HAGlue>> quorum)` Create or re-open a journal as part of a highly available `Quorum`.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`_close()` Core implementation of immediate shutdown handles event reporting.
`protected Name2Addr`	`_getName2Addr()` Return the "live" BTree mapping index names to the last metadata record committed for the named index.
`void`	`abort()` Abandon the current write set (synchronous).
`void`	`abortContext(IAllocationContext context)` Indicates that the allocation context will no longer be used and that the allocations made within the context should be discarded.
`protected void`	`assertBefore(UUID serviceId1, UUID serviceId2, long t1, long t2)` Assert that `t1` LT `t2`, where `t1` and `t2` are timestamps obtain such that this relation will be `true` if the clocks on the nodes are synchronized.
`protected void`	`assertCanRead()` Assert that the journal is readable.
`protected void`	`assertCanWrite()` Assert that the journal is writable.
`protected void`	`assertCommitTimeAdvances(long commitTime)` Method verifies that the commit time strictly advances on the local store by checking against the current root block.
`void`	`assertHAReady(long token)` Assert that the `getHAReady()` token has the specified value.
`protected void`	`assertOpen()` Assert that the store is open.
`protected static void`	`assertPriorCommitTimeAdvances(long currentCommitTime, long priorCommitTime)` Method verifies that the commit time strictly advances on the local store by checking against the current root block.
`long`	`awaitHAReady(long timeout, TimeUnit units)` Await the service being ready to partitipate in an HA quorum.
`protected void`	`clearQuorumToken(long newValue)` This method will update the quorum token on the journal and the associated values as if the service was not joined with a met quorum.
`void`	`close()` Invokes `shutdownNow()`.
`void`	`closeForWrites(long closeTime)` Restart safe conversion of the store into a read-only store with the specified closeTime.
`long`	`commit()` Atomic commit (synchronous).
`protected long`	`commitNow(long commitTime)` An atomic commit is performed by directing each registered `ICommitter` to flush its state onto the store using `ICommitter.handleCommit(long)`.
`void`	`delete(long addr)` Delete the data (unisolated).
`void`	`delete(long addr, IAllocationContext context)` Delete the data associated with the address within the allocation context.
`void`	`deleteResources()` Deletes the backing file(s) (if any).
`void`	`destroy()` Closes the store immediately (if open) and deletes its persistent resources.
`void`	`detachContext(IAllocationContext context)` Indicates that the allocation context will no longer be used, but that the allocations made within the context should be preserved.
`protected void`	`discardCommitters()` This method is invoked by `abort()` when the store must discard any hard references that it may be holding to objects registered as `ICommitter`s.
`void`	`doLocalAbort()` Local commit protocol (HA).
`void`	`doLocalCommit(IRootBlockView rootBlock)` Local commit protocol (HA, offline).
`protected void`	`doLocalCommit(QuorumService<HAGlue> localService, IRootBlockView rootBlock)` Local commit protocol (HA).
`void`	`dropIndex(String name)` Drops the named index.
`long`	`ensureMinFree(long minFree)` Make sure that the journal has at least the specified number of bytes of unused capacity remaining in the user extent.
`protected void`	`finalize()` Closes out the journal iff it is still open.
`void`	`force(boolean metadata)` Force the data to stable storage.
`IBufferStrategy`	`getBufferStrategy()` Return the delegate that implements the `BufferMode`.
`int`	`getByteCount(long addr)` The length of the datum in bytes.
`ICommitRecord`	`getCommitRecord()` Returns a read-only view of the most recently committed `ICommitRecord` containing the root addresses.
`ICommitRecord`	`getCommitRecord(long commitTime)` Return the `ICommitRecord` for the most recent committed state whose commit timestamp is less than or equal to timestamp.
`protected CommitRecordIndex`	`getCommitRecordIndex(long addr, boolean readOnly)` Create or load and return the index that resolves timestamps to `ICommitRecord`s.
`ICommitRecord`	`getCommitRecordStrictlyGreaterThan(long commitTime)` Return the first commit record whose timestamp is strictly greater than the given commitTime.
`CounterSet`	`getCounters()` Return counters reporting on various aspects of the journal.
`protected ICommitRecord`	`getEarliestVisibleCommitRecordForHA(long releaseTime)` Resolve the `ICommitRecord` for the earliest visible commit point based on the caller's releaseTime.
`abstract ExecutorService`	`getExecutorService()` Service for running arbitrary tasks in support of `IResourceLocator`.
`File`	`getFile()` The backing file -or- `null` if there is no backing file for the store.
`long`	`getHAPrepareTimeout()` The HA timeout in milliseconds for a 2-phase prepare.
`long`	`getHAReady()` Returns the current value of the `haReadyToken` (non-blocking).
`long`	`getHAReleaseTimeConsensusTimeout()` The HA timeout in milliseconds for the release time consensus protocol.
`HAStatusEnum`	`getHAStatus()` A simplified summary of the HA status of the service.
`protected int`	`getHistoricalIndexCacheSize()` The size of the canonicalizing cache from addr to `IIndex`.
`BTree`	`getIndex(String name)` Return the mutable view of the named index (aka the "live" or `ITx.UNISOLATED` index).
`IIndex`	`getIndex(String name, long commitTime)` Return a view of the named index as of the specified timestamp.
`protected int`	`getIndexCacheSize()` The size of the cache from (name,timestamp) to `IIndex`.
`protected CounterSet`	`getIndexCounters()` Return a `CounterSet` reflecting the named indices that are open or which have been recently opened.
`ICheckpointProtocol`	`getIndexLocal(String name, long commitTime)` Core implementation for access to historical index views.
`ICheckpointProtocol`	`getIndexWithCheckpointAddr(long checkpointAddr)` A canonicalizing mapping for historical (read-only) views of persistence capable data structures (core impl).
`ICheckpointProtocol`	`getIndexWithCommitRecord(String name, ICommitRecord commitRecord)` Returns a read-only named index loaded from a `ICommitRecord`.
`InputStream`	`getInputStream(long addr)` Return an input stream from which a previously written stream may be read back.
`long`	`getLastCommitTime()` The database wide timestamp of the most recent commit on the store or 0L iff there have been no commits.
`protected long`	`getMaximumClockSkewMillis()` The maximum error allowed (milliseconds) in the clocks.
`long`	`getMaximumExtent()` The maximum extent before a `commit()` will `#overflow()`.
`int`	`getMaxRecordSize()` The maximum length of a record that may be written on the store.
`IIndex`	`getName2Addr()` A read-only view of the `Name2Addr` object mapping index names to the most recent committed `Name2Addr.Entry` for the named index.
`IIndex`	`getName2Addr(long commitTime)` Return a read-only view of the `Name2Addr` object as of the specified commit time.
`long`	`getOffset(long addr)` The offset on the store at which the datum is stored.
`int`	`getOffsetBits()`
`IPSOutputStream`	`getOutputStream()` Return an output stream which can be used to write on the backing store.
`IPSOutputStream`	`getOutputStream(IAllocationContext context)` Return an output stream which can be used to write on the backing store within the given allocation context.
`long`	`getPhysicalAddress(long addr)` Determine the unencoded physical address
`Properties`	`getProperties()` A copy of the properties used to initialize this journal.
`protected static String`	`getProperty(Properties properties, String name, String defaultValue)` Resolves the property value (static variant for ctor initialization).
`protected String`	`getProperty(String name, String defaultValue)` Resolves the property value.
`protected <E> E`	`getProperty(String name, String defaultValue, IValidator<E> validator)` Resolves, parses, and validates the property value.
`Quorum<HAGlue,QuorumService<HAGlue>>`	`getQuorum()` The `Quorum` for this service -or- `null` if the service is not running with a quorum.
`protected long`	`getQuorumToken()`
`CommitRecordIndex`	`getReadOnlyCommitRecordIndex()` Return a read-only view of the last committed state of the `CommitRecordIndex`.
`IResourceMetadata`	`getResourceMetadata()` A description of this store in support of the scale-out architecture.
`long`	`getRootAddr(int index)` The last address stored in the specified root slot as of the last committed state of the store.
`protected IRootBlockView[]`	`getRootBlocks()` Return both root blocks (atomically - used by HA).
`IRootBlockView`	`getRootBlockView()` Return a read-only view of the current root block.
`IRootBlockView`	`getRootBlockViewWithLock()` Variant of `getRootBlockView()` that takes the internal lock in order to provide an appropriate synchronization barrier when installing new root blocks onto an empty journal in HA.
`ICheckpointProtocol`	`getUnisolatedIndex(String name)` Return the mutable view of the named persistence capable data structure (aka the "live" or `ITx.UNISOLATED` view).
`UUID`	`getUUID()` Return the `UUID` which identifies this `IRawStore`.
`Iterator<String>`	`indexNameScan(String prefix, long timestamp)` Iterator visits the names of all indices spanned by the given prefix.
`protected void`	`installRootBlocks(IRootBlockView rootBlock0, IRootBlockView rootBlock1)` Install identical root blocks on the journal.
`protected void`	`invalidateCommitters()` This method is invoked to mark any persistence capable data structures as invalid (in an error state).
`boolean`	`isChecked()` Return `true` if the persistence store uses record level checksums.
`boolean`	`isDirty()` Return `true` if the store has been modified since the last `IAtomicStore.commit()` or `IAtomicStore.abort()`.
`boolean`	`isDoubleSync()`
`boolean`	`isFullyBuffered()` True iff the store is fully buffered (all reads are against memory).
`boolean`	`isOpen()` `true` iff the store is open.
`boolean`	`isReadOnly()` Return `true` if the journal was opened in a read-only mode or if `closeForWrites(long)` was used to seal the journal against further writes.
`boolean`	`isStable()` True iff backed by stable storage.
`IAllocationContext`	`newAllocationContext(boolean isolated)` Creates a context to be used to isolate updates to within the context until it is released to the parent environment.
`protected HAGlue`	`newHAGlue(UUID serviceId)` Factory for the `HADelegate` object for this `AbstractJournal`.
`ByteBuffer`	`read(long addr)` Read the data (unisolated).
`ICheckpointProtocol`	`register(String name, IndexMetadata metadata)` Variant method creates and registered a named persistence capable data structure but does not assume that the data structure will be a `BTree`.
`void`	`registerIndex(IndexMetadata metadata)` Registers a named index.
`BTree`	`registerIndex(String name, BTree ndx)` Register a named index.
`void`	`registerIndex(String name, HTree ndx)`
`BTree`	`registerIndex(String name, IndexMetadata metadata)` Deprecated. by `register(String, IndexMetadata)`
`int`	`removeCommitRecordEntries(byte[] fromKey, byte[] toKey)` Remove all commit records between the two provided keys.
`void`	`rollback()` Deprecated. Do not use this method. HA provides point in time restore. Use that. Or you can open a journal using the alternate root block by specifying `Options.ALTERNATE_ROOT_BLOCK`
`void`	`setCommitter(int rootSlot, ICommitter committer)` Set a persistence capable data structure for callback during the commit protocol.
`protected void`	`setQuorumToken(long newValue)`
`protected void`	`setupCommitters()` Invoked when a journal is first created, re-opened, or when the committers have been `discarded`.
`void`	`shutdown()` Shutdown the journal (running tasks will run to completion, but no new tasks will start).
`void`	`shutdownNow()` Immediate shutdown (running tasks are canceled rather than being permitted to complete).
`long`	`size()` The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).
`AbstractJournal.ISnapshotData`	`snapshotAllocationData(AtomicReference<IRootBlockView> rbv)` With lock held to ensure that there is no concurrent commit, copy key data atomically to ensure recovered snapshot is consistent with the commit state when the snapshot is taken.
`long`	`toAddr(int nbytes, long offset)` Converts a byte count and offset into a long integer.
`String`	`toString(long addr)` A human readable representation of the address.
`void`	`truncate()` Truncate the backing buffer such that there is no remaining free space in the journal.
`protected void`	`validateIndexMetadata(String name, IndexMetadata metadata)` Provides an opportunity to validate some aspects of the `IndexMetadata` for an index partition.
`long`	`write(ByteBuffer data)` Write the data (unisolated).
`long`	`write(ByteBuffer data, IAllocationContext context)` Write the data within the allocation context.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.bigdata.journal.IJournal
getLocalTransactionManager, isHAJournal

Methods inherited from interface com.bigdata.journal.IIndexManager
isGroupCommit

Methods inherited from interface com.bigdata.journal.IIndexStore
addScheduledTask, getCollectPlatformStatistics, getCollectQueueStatistics, getGlobalFileSystem, getGlobalRowStore, getGlobalRowStore, getHttpdPort, getResourceLocator, getResourceLockService, getTempStore

- Field Detail
  - haLog
```
protected static final org.apache.log4j.Logger haLog
```
    Logger for HA events.
  - ROOT_NAME2ADDR
```
public static final transient int ROOT_NAME2ADDR
```
    The index of the root address containing the address of the persistent Name2Addr mapping names to BTrees registered for the store.
    
    See Also:
    Constant Field Values
  - PREV_ROOTBLOCK
```
public static final transient int PREV_ROOTBLOCK
```
    The index of the root address where the root block copy from the previous commit is stored.
    
    See Also:
    Constant Field Values
  - DELETEBLOCK
```
public static final transient int DELETEBLOCK
```
    The index of the root address of the delete blocks associated with this transaction.
    
    See Also:
    Constant Field Values
  - ROOT_ICUVERSION
```
public static final transient int ROOT_ICUVERSION
```
    The index of the root address containing the ICUVersionRecord. That record specifies the ICU version metadata which was in force when the journal was created.
    
    See Also:
    Constant Field Values
  - properties
```
protected final Properties properties
```
    A clone of the properties used to initialize the Journal.
  - tmpDir
```
public final File tmpDir
```
    The directory that should be used for temporary files.
  - doubleSync
```
protected final boolean doubleSync
```
    Option controls whether the journal forces application data to disk before updating the root blocks.
  - forceOnCommit
```
protected final ForceEnum forceOnCommit
```
    Option controls how the journal behaves during a commit.
  - deleteOnClose
```
protected final boolean deleteOnClose
```
    Option set by the test suites causes the file backing the journal to be deleted when the journal is closed.
- Constructor Detail
  - AbstractJournal
```
protected AbstractJournal(Properties properties)
```
    Create or re-open a journal.
    
    Parameters:
    properties - The properties as defined by Options.
    
    Throws:
    
    RuntimeException - If there is a problem when creating, opening, or reading from the journal file.
    See Also:
    Options
  - AbstractJournal
```
protected AbstractJournal(Properties properties,
               Quorum<HAGlue,QuorumService<HAGlue>> quorum)
```
    Create or re-open a journal as part of a highly available Quorum.
    
    Parameters:
    properties - The properties as defined by Options.
    quorum - The quorum with which the journal will join (HA mode only).
    
    Throws:
    
    RuntimeException - If there is a problem when creating, opening, or reading from the journal file.
    See Also:
    Options
- Method Detail
  - _getName2Addr
```
protected Name2Addr _getName2Addr()
```
    Return the "live" BTree mapping index names to the last metadata record committed for the named index. The keys are index names (unicode strings). The values are the names and the last known address of the named btree.
    The "live" name2addr index is required for unisolated writers regardless whether they are adding an index, dropping an index, or just recovering the "live" version of an existing named index.
    Operations that read on historical Name2Addr objects can of course be concurrent. Those objects are loaded from an ICommitRecord. See #getIndex(String, ICommitRecord).
    Note: the "live" Name2Addr index is a mutable BTree. All access to the object MUST be synchronized on that object.
  - getName2Addr
```
public IIndex getName2Addr()
```
    A read-only view of the Name2Addr object mapping index names to the most recent committed Name2Addr.Entry for the named index. The keys are index names (unicode strings). The values are Name2Addr.Entrys containing the names, commitTime, and last known Checkpoint address of the named BTree on the Journal.
  - getName2Addr
```
public IIndex getName2Addr(long commitTime)
```
    Return a read-only view of the Name2Addr object as of the specified commit time.
    
    Parameters:
    commitTime - A commit time.
    
    Returns:
    The read-only view -or- null if there is no commit record for that commitTime.
    See Also:
    getName2Addr()
  - getMaximumExtent
```
public final long getMaximumExtent()
```
    The maximum extent before a commit() will #overflow(). In practice, overflow tries to trigger before this point in order to avoid extending the journal.
    
    See Also:
    Options.MAXIMUM_EXTENT
  - getProperty
```
protected static String getProperty(Properties properties,
                 String name,
                 String defaultValue)
```
    Resolves the property value (static variant for ctor initialization).
    
    See Also:
    Configuration.getProperty(IIndexManager, Properties, String, String, String)
  - getProperty
```
protected String getProperty(String name,
                 String defaultValue)
```
    Resolves the property value.
    
    See Also:
    Configuration.getProperty(IIndexManager, Properties, String, String, String)
  - getProperty
```
protected <E> E getProperty(String name,
                String defaultValue,
                IValidator<E> validator)
```
    Resolves, parses, and validates the property value.
    
    Parameters:
    name - The property name.
    defaultValue - The default value.
    
    Returns:
  - getProperties
```
public final Properties getProperties()
```
    Description copied from interface: IJournal
    
    A copy of the properties used to initialize this journal.
    
    Specified by:
    
    getProperties in interface IJournal
  - getBufferStrategy
```
public IBufferStrategy getBufferStrategy()
```
    Return the delegate that implements the BufferMode.
    Note: this method MUST NOT check to see whether the journal is open since we need to use it if we want to invoke IRawStore.deleteResources() and we can only invoke that method once the journal is closed.
  - getExecutorService
```
public abstract ExecutorService getExecutorService()
```
    Service for running arbitrary tasks in support of IResourceLocator. There is no concurrency control associated with this service, but tasks run here may submit tasks to the ConcurrencyManager.
    
    Specified by:
    
    getExecutorService in interface IIndexStore
  - shutdown
```
public void shutdown()
```
    Shutdown the journal (running tasks will run to completion, but no new tasks will start).
    Note: You SHOULD use this method rather than close() for normal shutdown of the journal.
    
    Specified by:
    
    shutdown in interface IJournal
    
    See Also:
    shutdownNow()
  - shutdownNow
```
public void shutdownNow()
```
    Immediate shutdown (running tasks are canceled rather than being permitted to complete).
    
    Specified by:
    
    shutdownNow in interface IJournal
    
    See Also:
    shutdown()
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Closes out the journal iff it is still open.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - getCounters
```
public CounterSet getCounters()
```
    Return counters reporting on various aspects of the journal.
    
    Specified by:
    
    getCounters in interface ICounterSetAccess
  - getIndexCounters
```
protected final CounterSet getIndexCounters()
```
    Return a CounterSet reflecting the named indices that are open or which have been recently opened.
    Note: This method prefers the live view of the index since this gets us the most recent metadata for the index depth, #of nodes, #of leaves, etc. However, when the live view is not currently open, we prefer the most recent view of the index.
    Note: This scans the live Name2Addrs internal index cache for the live indices and then scans the historicalIndexCache for the read-only index views. Only a single CounterSet is reported for any given named index.
    
    Returns:
    A new CounterSet reflecting the named indices that were open as of the time that this method was invoked.
    See Also:
    Expose performance counters for read-only indices
  - getFile
```
public final File getFile()
```
    Description copied from interface: IRawStore
    
    The backing file -or- null if there is no backing file for the store.
    
    Specified by:
    
    getFile in interface IRawStore
  - assertBefore
```
protected void assertBefore(UUID serviceId1,
                UUID serviceId2,
                long t1,
                long t2)
                     throws ClocksNotSynchronizedException
```
    Assert that t1 LT t2, where t1 and t2 are timestamps obtain such that this relation will be true if the clocks on the nodes are synchronized.
    Note: Clock synchronization errors can arise across nodes if the nodes are not using a common network time source.
    Note: Synchronization errors can arise on a single node if the clock is changed on that node - specifically if the clock is move backwards to before the most recent commit timestamp. For example, if the timezone is changed.
    
    Parameters:
    serviceId1 - The service that reported the timestamp t1.
    serviceId2 - The service that reported the timestamp t2.
    t1 - A timestamp from one service.
    t2 - A timestamp from the another service.
    
    Throws:
    
    ClocksNotSynchronizedException
    See Also:
    ClocksNotSynchronizedException
  - getMaximumClockSkewMillis
```
protected long getMaximumClockSkewMillis()
```
    The maximum error allowed (milliseconds) in the clocks. This is used by assertBefore(UUID, UUID, long, long) to verify that the clocks are within some acceptable skew of one another. It is also used by nextCommitTimestamp() where it specifies the maximum clock skew that will be corrected without operator intervention.
    Note: This is overridden by the HAJournal.
    
    See Also:
    assertBefore(UUID, UUID, long, long)
  - getHAPrepareTimeout
```
public long getHAPrepareTimeout()
```
    The HA timeout in milliseconds for a 2-phase prepare.
    
    Throws:
    
    UnsupportedOperationException - always.
  - getHAReleaseTimeConsensusTimeout
```
public long getHAReleaseTimeConsensusTimeout()
```
    The HA timeout in milliseconds for the release time consensus protocol.
    
    Throws:
    
    UnsupportedOperationException - always.
  - _close
```
protected void _close()
```
    Core implementation of immediate shutdown handles event reporting.
  - deleteResources
```
public void deleteResources()
```
    Deletes the backing file(s) (if any).
    Note: This is the core implementation of delete and handles event reporting.
    
    Specified by:
    
    deleteResources in interface IRawStore
    
    Throws:
    
    IllegalStateException - if the journal is open.
  - truncate
```
public void truncate()
```
    Truncate the backing buffer such that there is no remaining free space in the journal.
    Note: The caller MUST have exclusive write access to the journal. When the ConcurrencyManager is used, that means that the caller MUST have an exclusive lock on the WriteExecutorService.
    Note: The BufferMode.DiskRW does NOT support this operation. This is because it stores meta-allocation information at the end of the file, which makes it impossible to shrink the file. Therefore this method will return without causing the file on disk to be shrunk for the RWStore.
  - ensureMinFree
```
public long ensureMinFree(long minFree)
```
    Make sure that the journal has at least the specified number of bytes of unused capacity remaining in the user extent.
    Note: You need an exclusive write lock on the journal to extend it.
    
    Parameters:
    minFree - The minimum #of bytes free for the user extent.
    
    Returns:
    The #of bytes of free space remaining in the user extent.
  - closeForWrites
```
public void closeForWrites(long closeTime)
```
    Restart safe conversion of the store into a read-only store with the specified closeTime.
    This implementation sets the "closeTime" on the root block such that the journal will no longer accept writes, flushes all buffered writes, and releases any write cache buffers since they will no longer be used. This method is normally used when one journal is being closed out for writes during synchronous overflow processing and new writes will be buffered on a new journal. This has advantages over closing the journal directly including that it does not disturb concurrent readers.
    Note: The caller MUST have exclusive write access to the journal. When the ConcurrencyManager is used, that means that the caller MUST have an exclusive lock on the WriteExecutorService.
    Note: This does NOT perform a commit - any uncommitted writes will be discarded.
    
    Throws:
    
    IllegalStateException - If there are no commits on the journal.
  - close
```
public void close()
```
    Invokes shutdownNow().
    
    Specified by:
    
    close in interface IRawStore
  - destroy
```
public void destroy()
```
    Description copied from interface: IRawStore
    
    Closes the store immediately (if open) and deletes its persistent resources. Does NOT throw an IllegalStateException if the store is already closed, but still deletes the backing resources.
    
    Specified by:
    
    destroy in interface IIndexStore
    
    Specified by:
    
    destroy in interface IRawStore
    
    See Also:
    IRawStore.deleteResources()
  - assertOpen
```
protected void assertOpen()
```
    Assert that the store is open.
    Note: You can see an IllegalStateException thrown out of here if there are tasks running during shutdown() and one of the various task services times out while awaiting termination. Such exceptions are normal since the store was closed asynchronously while task(s) were still running.
    
    Throws:
    
    IllegalStateException - if the store is closed.
  - getUUID
```
public final UUID getUUID()
```
    Description copied from interface: IRawStore
    
    Return the UUID which identifies this IRawStore. This supports IRawStore.getResourceMetadata().
    
    Specified by:
    
    getUUID in interface IRawStore
  - getResourceMetadata
```
public final IResourceMetadata getResourceMetadata()
```
    Description copied from interface: IRawStore
    
    A description of this store in support of the scale-out architecture.
    
    Specified by:
    
    getResourceMetadata in interface IRawStore
  - isOpen
```
public boolean isOpen()
```
    true iff the store is open.
    Note: This will report false for a new highly available journal until the quorum has met and #init() has been invoked for the Quorum.
    
    Specified by:
    
    isOpen in interface IRawStore
    
    Returns:
    true iff the store is open.
  - isReadOnly
```
public boolean isReadOnly()
```
    Return true if the journal was opened in a read-only mode or if closeForWrites(long) was used to seal the journal against further writes.
    
    Specified by:
    
    isReadOnly in interface IRawStore
  - assertCanRead
```
protected void assertCanRead()
```
    Assert that the journal is readable.
    
    Throws:
    
    IllegalStateException - if the journal is not writable at this time.
  - assertCanWrite
```
protected void assertCanWrite()
```
    Assert that the journal is writable.
    
    Throws:
    
    IllegalStateException - if the journal is not writable at this time.
  - isStable
```
public boolean isStable()
```
    Description copied from interface: IRawStore
    
    True iff backed by stable storage.
    
    Specified by:
    
    isStable in interface IRawStore
  - isFullyBuffered
```
public boolean isFullyBuffered()
```
    Description copied from interface: IRawStore
    
    True iff the store is fully buffered (all reads are against memory). Implementations MAY change the value returned by this method over the life cycle of the store, e.g., to conserve memory a store may drop or decrease its buffer if it is backed by disk.
    Note: This does not guarantee that the OS will not swap the buffer onto disk.
    
    Specified by:
    
    isFullyBuffered in interface IRawStore
  - isDoubleSync
```
public boolean isDoubleSync()
```
  - isChecked
```
public boolean isChecked()
```
    Return true if the persistence store uses record level checksums. When true, the store will detect bad reads by comparing the record as read from the disk against the checksum for that record.
  - getRootBlockView
```
public final IRootBlockView getRootBlockView()
```
    Return a read-only view of the current root block.
    Returns the current root block (immediate, non-blocking peek).
    Note: The root block reference can be null until the journal has been initialized. Once it has been set, the root block will always be non-null. Since this method does not obtain the inner lock, it is possible for another thread to change the root block reference through a concurrent abort() or commitNow(long). The IRootBlockView itself is an immutable data structure.
    
    Specified by:
    
    getRootBlockView in interface IAtomicStore
    
    Returns:
    The current root block.
  - getRootBlockViewWithLock
```
public final IRootBlockView getRootBlockViewWithLock()
```
    Variant of getRootBlockView() that takes the internal lock in order to provide an appropriate synchronization barrier when installing new root blocks onto an empty journal in HA.
    
    See Also:
    installRootBlocks(IRootBlockView, IRootBlockView)
  - getLastCommitTime
```
public final long getLastCommitTime()
```
    Description copied from interface: IIndexStore
    
    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.
    This method is useful if you plan to issue a series of read-consistent requests against the most current commit point of the database.
    
    Specified by:
    
    getLastCommitTime in interface IIndexStore
    
    Returns:
    The timestamp of the most recent commit on the store or 0L iff there have been no commits.
    See Also:
    IRootBlockView.getLastCommitTime()
  - setCommitter
```
public final void setCommitter(int rootSlot,
                ICommitter committer)
```
    Set a persistence capable data structure for callback during the commit protocol.
    Note: the committers must be reset after restart or whenever the committers are discarded (the committers are themselves transient objects).
    
    Specified by:
    
    setCommitter in interface IAtomicStore
    
    Parameters:
    rootSlot - The slot in the root block where the address of the ICommitter will be recorded.
    committer - The commiter.
  - abort
```
public void abort()
```
    Description copied from interface: IAtomicStore
    
    Abandon the current write set (synchronous).
    
    Specified by:
    
    abort in interface IAtomicStore
  - rollback
```
public void rollback()
```
    Deprecated. Do not use this method. HA provides point in time restore. Use that. Or you can open a journal using the alternate root block by specifying Options.ALTERNATE_ROOT_BLOCK
    
    Rollback a journal to its previous commit point.
    Note: You MUST have an exclusive write lock on the journal.
    Note: To restore the last root block we copy the alternative root block over the current root block. That gives us two identical root blocks and restores us to the root block that was in effect before the last commit.
  - isDirty
```
public boolean isDirty()
```
    Description copied from interface: IAtomicStore
    
    Return true if the store has been modified since the last IAtomicStore.commit() or IAtomicStore.abort().
    
    Specified by:
    
    isDirty in interface IAtomicStore
    
    Returns:
    true if store has been modified since last IAtomicStore.commit() or IAtomicStore.abort().
  - commit
```
public long commit()
```
    Description copied from interface: IAtomicStore
    
    Atomic commit (synchronous).
    Note: if the commit fails (by throwing any kind of exception) then you MUST invoke IAtomicStore.abort() to abandon the current write set.
    
    Specified by:
    
    commit in interface IAtomicStore
    
    Returns:
    The timestamp assigned to the ICommitRecord -or- 0L if there were no data to commit.
  - commitNow
```
protected long commitNow(long commitTime)
```
    An atomic commit is performed by directing each registered ICommitter to flush its state onto the store using ICommitter.handleCommit(long). The address returned by that method is the address from which the ICommitter may be reloaded (and its previous address if its state has not changed). That address is saved in the ICommitRecord under the index for which that committer was registered. We then force the data to stable store, update the root block, and force the root block and the file metadata to stable store.
    Note: Each invocation of this method MUST use a distinct commitTime and the commitTimes MUST be monotonically increasing. These guarantees support both the database version history mechanisms and the High Availability mechanisms.
    
    Parameters:
    commitTime - The commit time either of a transaction or of an unisolated commit. Note that when mixing isolated and unisolated commits you MUST use the same ITimestampService for both purposes.
    
    Returns:
    The timestamp assigned to the commit record -or- 0L if there were no data to commit.
  - assertCommitTimeAdvances
```
protected void assertCommitTimeAdvances(long commitTime)
```
    Method verifies that the commit time strictly advances on the local store by checking against the current root block.
    
    Parameters:
    commitTime - The proposed commit time.
    
    Throws:
    
    IllegalArgumentException - if the commitTime is LTE the value reported by IRootBlockView.getLastCommitTime().
  - assertPriorCommitTimeAdvances
```
protected static void assertPriorCommitTimeAdvances(long currentCommitTime,
                                 long priorCommitTime)
```
    Method verifies that the commit time strictly advances on the local store by checking against the current root block.
    
    Parameters:
    currentCommitTime -
    priorCommitTime -
    
    Throws:
    
    IllegalArgumentException - if the commitTime is LTE the value reported by IRootBlockView.getLastCommitTime().
  - force
```
public void force(boolean metadata)
```
    Description copied from interface: IRawStore
    
    Force the data to stable storage. While this is NOT sufficient to guarantee an atomic commit, the data must be forced to disk as part of an atomic commit protocol.
    
    Specified by:
    
    force in interface IRawStore
    
    Parameters:
    metadata - If true, then force both the file contents and the file metadata to disk.
  - size
```
public long size()
```
    Description copied from interface: IRawStore
    
    The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).
    
    Specified by:
    
    size in interface IRawStore
  - read
```
public ByteBuffer read(long addr)
```
    Description copied from interface: IRawStore
    
    Read the data (unisolated).
    
    Specified by:
    
    read in interface IRawStore
    
    Parameters:
    addr - A long integer that encodes both the offset from which the data will be read and the #of bytes to be read. See IAddressManager.toAddr(int, long).
    
    Returns:
    The data read. The buffer will be flipped to prepare for reading (the position will be zero and the limit will be the #of bytes read).
  - write
```
public long write(ByteBuffer data)
```
    Description copied from interface: IRawStore
    
    Write the data (unisolated).
    
    Specified by:
    
    write in interface IRawStore
    
    Parameters:
    data - The data. The bytes from the current Buffer.position() to the Buffer.limit() will be written and the Buffer.position() will be advanced to the Buffer.limit() . The caller may subsequently modify the contents of the buffer without changing the state of the store (i.e., the data are copied into the store).
    
    Returns:
    A long integer formed that encodes both the offset from which the data may be read and the #of bytes to be read. See IAddressManager.
  - write
```
public long write(ByteBuffer data,
         IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Write the data within the allocation context. The write is not visible outside of the allocation until the allocation context has been merged into the parent allocation context.
    
    Specified by:
    
    write in interface IAllocationManagerStore
    
    Parameters:
    data - The data.
    context - The allocation context.
    
    Returns:
    The address at which the data was written.
  - getOutputStream
```
public IPSOutputStream getOutputStream()
```
    Description copied from interface: IStreamStore
    
    Return an output stream which can be used to write on the backing store. You can recover the address used to read back the data from the IPSOutputStream.
    
    Specified by:
    
    getOutputStream in interface IStreamStore
    
    Returns:
    The output stream.
  - getOutputStream
```
public IPSOutputStream getOutputStream(IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Return an output stream which can be used to write on the backing store within the given allocation context. You can recover the address used to read back the data from the IPSOutputStream.
    
    Specified by:
    
    getOutputStream in interface IAllocationManagerStore
    
    Parameters:
    context - The context within which any allocations are made by the returned IPSOutputStream.
    
    Returns:
    an output stream to stream data to and to retrieve an address to later stream the data back.
  - getInputStream
```
public InputStream getInputStream(long addr)
```
    Description copied from interface: IStreamStore
    
    Return an input stream from which a previously written stream may be read back.
    
    Specified by:
    
    getInputStream in interface IStreamStore
    
    Parameters:
    addr - The address at which the stream was written.
    
    Returns:
    an input stream for the data for provided address
  - delete
```
public void delete(long addr)
```
    Description copied from interface: IRawStore
    
    Delete the data (unisolated).
    After this operation subsequent reads on the address MAY fail and the caller MUST NOT depend on the ability to read at that address.
    
    Specified by:
    
    delete in interface IRawStore
    
    Parameters:
    addr - A long integer formed using Addr that encodes both the offset at which the data was written and the #of bytes that were written.
  - delete
```
public void delete(long addr,
          IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Delete the data associated with the address within the allocation context. The delete is not visible outside of the allocation until the allocation context has been merged into the parent allocation context.
    
    Specified by:
    
    delete in interface IAllocationManagerStore
    
    Parameters:
    addr - The address whose allocation is to be deleted.
    context - The allocation context.
  - detachContext
```
public void detachContext(IAllocationContext context)
```
    Description copied from interface: IAllocationManager
    
    Indicates that the allocation context will no longer be used, but that the allocations made within the context should be preserved. The allocations associated with the context are propagated to the parent allocation context. The IStore is the top-level parent of allocation contexts. The allocators associated with the allocation context are return to the global list of available allocators.
    
    Specified by:
    
    detachContext in interface IAllocationManager
    
    Parameters:
    context - The application object which serves as the allocation context.
  - abortContext
```
public void abortContext(IAllocationContext context)
```
    Description copied from interface: IAllocationManager
    
    Indicates that the allocation context will no longer be used and that the allocations made within the context should be discarded. The allocations associated with the context are discarded, as are any deletes made within the scope of that allocation context. The allocators associated with the allocation context are return to the global list of available allocators.
    
    Specified by:
    
    abortContext in interface IAllocationManager
    
    Parameters:
    context - The application object which serves as the allocation context.
  - getRootAddr
```
public final long getRootAddr(int index)
```
    Description copied from interface: IAtomicStore
    
    The last address stored in the specified root slot as of the last committed state of the store.
    
    Specified by:
    
    getRootAddr in interface IAtomicStore
    
    Parameters:
    index - The index of the root address to be retrieved.
    
    Returns:
    The address stored at that index.
  - getEarliestVisibleCommitRecordForHA
```
protected ICommitRecord getEarliestVisibleCommitRecordForHA(long releaseTime)
```
    Resolve the ICommitRecord for the earliest visible commit point based on the caller's releaseTime.
    Note: This method is used for HA. The caller provides a releaseTime based on the readsOnCommitTime of the earliestActiveTx and the minReleaseAge rather than ITransactionService.getReleaseTime() since the latter is only updated by the release time consensus protocol during a 2-phase commit.
  - getCommitRecord
```
public ICommitRecord getCommitRecord()
```
    Returns a read-only view of the most recently committed ICommitRecord containing the root addresses.
    
    Returns:
    The current ICommitRecord and never null.
  - invalidateCommitters
```
protected void invalidateCommitters()
```
    This method is invoked to mark any persistence capable data structures as invalid (in an error state). This ensures that dirty committers are not accidentally flushed through after a call to abort().
    
    See Also:
    https://jira.blazegraph.com/browse/BLZG-1953
  - discardCommitters
```
protected void discardCommitters()
```
    This method is invoked by abort() when the store must discard any hard references that it may be holding to objects registered as ICommitters.
    The default implementation discards the btree mapping names to named btrees.
    Subclasses MAY extend this method to discard their own committers but MUST NOT override it completely.
  - setupCommitters
```
protected void setupCommitters()
```
    Invoked when a journal is first created, re-opened, or when the committers have been discarded.
    The basic implementation sets up the btree that is responsible for resolving named btrees.
    Subclasses may extend this method to setup their own committers.
  - getReadOnlyCommitRecordIndex
```
public CommitRecordIndex getReadOnlyCommitRecordIndex()
```
    Return a read-only view of the last committed state of the CommitRecordIndex.
    
    Returns:
    The read-only view of the CommitRecordIndex.
  - getCommitRecordIndex
```
protected CommitRecordIndex getCommitRecordIndex(long addr,
                                     boolean readOnly)
```
    Create or load and return the index that resolves timestamps to ICommitRecords. This method is capable of returning either the live CommitRecordIndex or a read-only view of any committed version of that index. CAUTION: DO NOT EXPOSE THE LIVE COMMIT RECORD INDEX OUTSIDE OF THIS CLASS. IT IS NOT POSSIBLE TO HAVE CORRECT SYNCHRONIZATION ON THAT INDEX IN ANOTHER CLASS.
    
    Parameters:
    addr - The root address of the index -or- 0L if the index has not been created yet. When addr is non-IAddressManager.NULL, each invocation will return a distinct CommitRecordIndex object.
    readOnly - When false the returned is NOT cached.
    
    Returns:
    The CommitRecordIndex for that address or a new index if 0L was specified as the address.
    See Also:
    _commitRecordIndex
  getCommitRecord
  
  public ICommitRecord getCommitRecord(long commitTime)
  
  Return the ICommitRecord for the most recent committed state whose commit timestamp is less than or equal to timestamp. This is used by a transaction to locate the committed state that is the basis for its operations.
  
  Specified by:
  
  getCommitRecord in interface IAtomicStore
  
  Parameters:
  commitTime - The timestamp of interest.
  
  Returns:
  The ICommitRecord for the most recent committed state whose commit timestamp is less than or equal to timestamp -or- null iff there are no ICommitRecords that satisfy the probe.
  
  getCommitRecordStrictlyGreaterThan
  
  public ICommitRecord getCommitRecordStrictlyGreaterThan(long commitTime)
  
  Return the first commit record whose timestamp is strictly greater than the given commitTime.
  
  Parameters:
  commitTime - The commit time.
  
  Returns:
  The commit record -or- null if there is no commit record whose timestamp is strictly greater than commitTime.
  
  getIndex
  
  public IIndex getIndex(String name, long commitTime)
  
  Return a view of the named index as of the specified timestamp.
  Note: Transactions should pass in the timestamp against which they are reading rather than the transaction identifier (aka startTime). By providing the timestamp of the commit point, the transaction will hit the indexCache. If the transaction passes the startTime instead, then all startTimes will be different and the cache will be defeated.
  
  Specified by:
  
  getIndex in interface IIndexManager
  
  Parameters:
  name - The index name.
  commitTime - A timestamp which represents either a possible commit time on the store or a read-only transaction identifier.
  
  Returns:
  The index or null iff there is no index registered with that name for that timestamp.
  
  Throws:
  
  UnsupportedOperationException - If you pass in ITx.UNISOLATED, ITx.READ_COMMITTED, or a timestamp that corresponds to a read-write transaction since those are not "commit times".
  See Also:
  indexCache, Add cache for access to historical index views on the Journal by name and commitTime. FIXME GIST Reconcile API tension with {@link IIndex} and {@link ICheckpointProtocol}, however this method is overridden by {@link Journal} and is also implemented by {@link IBigdataFederation}. The central remaining tensions are {@link FusedView} and the local/remote aspect. {@link FusedView} could probably be "fixed" by extending {@link AbstractBTree} rather than having an inner delegate for the mutable view. The local/remote issue is more complex.
  
  getIndexLocal
  
  public final ICheckpointProtocol getIndexLocal(String name, long commitTime)
  
  Core implementation for access to historical index views.
  Note: Transactions should pass in the timestamp against which they are reading rather than the transaction identifier (aka startTime). By providing the timestamp of the commit point, the transaction will hit the indexCache. If the transaction passes the startTime instead, then all startTimes will be different and the cache will be defeated.
  
  Specified by:
  
  getIndexLocal in interface IGISTLocalManager
  
  Throws:
  
  UnsupportedOperationException - If you pass in ITx.UNISOLATED, ITx.READ_COMMITTED, or a timestamp that corresponds to a read-write transaction since those are not "commit times".
  See Also:
  indexCache, getIndex(String, long), Add cache for access to historical index views on the Journal by name and commitTime.
  
  getIndexCacheSize
  
  protected int getIndexCacheSize()
  
  The size of the cache from (name,timestamp) to IIndex.
  
  getHistoricalIndexCacheSize
  
  protected int getHistoricalIndexCacheSize()
  
  The size of the canonicalizing cache from addr to IIndex.
  
  getIndexWithCommitRecord
  
  public final ICheckpointProtocol getIndexWithCommitRecord(String name, ICommitRecord commitRecord)
  
  Returns a read-only named index loaded from a ICommitRecord. The index will be marked as read-only, it will NOT permit writes, and ICheckpointProtocol#getLastCommitTime(long) will report the value associated with Name2Addr.Entry.commitTime for the historical Name2Addr instance for that ICommitRecord.
  Note: This method should be preferred to getIndexWithCheckpointAddr(long) for read-historical indices since it will explicitly mark the index as read-only and specifies the lastCommitTime on the returned index based on Name2Addr.Entry.commitTime, which is the actual commit time for the last update to the index.
  
  Returns:
  The named index -or- null iff the named index did not exist as of that commit record.
  
  getIndexWithCheckpointAddr
  
  public final ICheckpointProtocol getIndexWithCheckpointAddr(long checkpointAddr)
  
  A canonicalizing mapping for historical (read-only) views of persistence capable data structures (core impl).
  Note: This method imposes a canonicalizing mapping and ensures that there will be at most one object providing a view of the historical data structure as of the specified timestamp. This guarentee is used to facilitate buffer management.
  Note: The canonicalizing mapping for unisolated views of persistence capable data structures is maintained by the ITx.UNISOLATED Name2Addr instance.
  
  Parameters:
  checkpointAddr - The address of the Checkpoint record.
  
  Returns:
  The read-only persistence capable data structure associated with that Checkpoint.
  See Also:
  Options.HISTORICAL_INDEX_CACHE_CAPACITY
  
  registerIndex
  
  public final void registerIndex(IndexMetadata metadata)
  
  Registers a named index. Once registered the index will participate in atomic commits.
  Note: A named index must be registered outside of any transaction before it may be used inside of a transaction.
  Note: You MUST commit() before the registered index will be either restart-safe or visible to new transactions.
  
  Specified by:
  
  registerIndex in interface IGISTManager
  
  Parameters:
  metadata - The metadata describing the index.
  See Also:
  IGISTLocalManager.getIndexLocal(String, long)
  
  validateIndexMetadata
  
  protected void validateIndexMetadata(String name, IndexMetadata metadata)
  
  Provides an opportunity to validate some aspects of the IndexMetadata for an index partition.
  
  registerIndex
  
  public final BTree registerIndex(String name, IndexMetadata metadata)
  
  Deprecated. by register(String, IndexMetadata)
  
  Register a named index.
  This variant allows you to register an index under a name other than the value returned by IndexMetadata.getName().
  Note: This variant is generally by the IMetadataService when it needs to register a index partition of some scale-out index on a IDataService. In this case the name is the name of the index partition while the value reported by IndexMetadata.getName() is the name of the scale-out index. In nearly all other cases you can use IGISTManager.registerIndex(IndexMetadata) instead. The same method signature is also declared by IDataService.registerIndex(String, IndexMetadata) in order to support registration of index partitions.
  Note: Due to the method signature, this method CAN NOT be used to create and register persistence capable data structures other than an IIndex (aka B+Tree).
  Once registered the index will participate in atomic commits.
  Note: A named index must be registered outside of any transaction before it may be used inside of a transaction.
  Note: You MUST commit() before the registered index will be either restart-safe or visible to new transactions.
  
  Specified by:
  
  registerIndex in interface IBTreeManager
  
  Parameters:
  name - The name that can be used to recover the index.
  metadata - The metadata describing the index.
  
  Returns:
  The object that would be returned by IBTreeManager.getIndex(String).
  See Also:
  IIndexManager.getIndex(String, long), FIXME GIST Due to the method signature, this method CAN NOT be used to create and register persistence capable data structures other than an {@link IIndex} (aka B+Tree). It is difficult to reconcile this method with other method signatures since this method is designed for scale-out and relies on {@link IIndex}. However, only the B+Tree is an {@link IIndex}. Therefore, this method signature can not be readily reconciled with the {@link HTree}. The only interface which the {@link BTree} and {@link HTree} share is the {@link ICheckpointProtocol} interface, but that is a purely local (not remote) interface and is therefore not suitable to scale-out. Also, it is only in scale-out where the returned object can be a different type than the simple {@link BTree} class, e.g., a {@link FusedView} or even an {@link IClientIndex}.
  
  register
  
  public ICheckpointProtocol register(String name, IndexMetadata metadata)
  
  Variant method creates and registered a named persistence capable data structure but does not assume that the data structure will be a BTree.
  
  Specified by:
  
  register in interface IGISTLocalManager
  
  Parameters:
  store - The backing store.
  metadata - The metadata that describes the data structure to be created.
  
  Returns:
  The persistence capable data structure.
  See Also:
  Checkpoint.create(IRawStore, IndexMetadata)
  
  registerIndex
  
  public final BTree registerIndex(String name, BTree ndx)
  
  Description copied from interface: IBTreeManager
  
  Register a named index.
  
  Specified by:
  
  registerIndex in interface IBTreeManager
  
  Parameters:
  name - The name that can be used to recover the index.
  ndx - The btree.
  
  Returns:
  The object that would be returned by IBTreeManager.getIndex(String).
  See Also:
  IGISTManager.registerIndex(IndexMetadata), IIndexManager.getIndex(String, long), IGISTLocalManager.getIndexLocal(String, long)
  
  registerIndex
  
  public final void registerIndex(String name, HTree ndx)
  
  dropIndex
  
  public void dropIndex(String name)
  
  Drops the named index.
  Note: Whether or not and when index resources are reclaimed is dependent on the store. For example, an immortal store will retain all historical states for all indices. Likewise, a store that uses index partitions may be able to delete index segments immediately.
  Drops the named index. The index will no longer participate in atomic commits and will not be visible to new transactions. Storage will be reclaimed IFF the backing store support that functionality.
  
  Specified by:
  
  dropIndex in interface IGISTManager
  
  Parameters:
  name - The name of the index to be dropped.
  
  indexNameScan
  
  public Iterator<String> indexNameScan(String prefix, long timestamp)
  
  Description copied from interface: IGISTManager
  
  Iterator visits the names of all indices spanned by the given prefix.
  
  Specified by:
  
  indexNameScan in interface IGISTManager
  
  Parameters:
  prefix - The prefix (optional). When given, this MUST include a . if you want to restrict the scan to only those indices in a given namespace. Otherwise you can find indices in kb2 if you provide the prefix kb where both kb and kb2 are namespaces since the indices spanned by kb would include both kb.xyz and kb2.xyx.
  timestamp - A timestamp which represents either a possible commit time on the store or a read-only transaction identifier.
  
  Returns:
  An iterator visiting those index names.
  
  getIndex
  
  public final BTree getIndex(String name)
  
  Return the mutable view of the named index (aka the "live" or ITx.UNISOLATED index). This object is NOT thread-safe. You MUST NOT write on this index unless you KNOW that you are the only writer. See ConcurrencyManager, which handles exclusive locks for ITx.UNISOLATED indices.
  
  Specified by:
  
  getIndex in interface IBTreeManager
  
  Parameters:
  name - The name of the index.
  
  Returns:
  The mutable view of the index.
  See Also:
  #getLiveView(String, long)
  
  getUnisolatedIndex
  
  public final ICheckpointProtocol getUnisolatedIndex(String name)
  
  Return the mutable view of the named persistence capable data structure (aka the "live" or ITx.UNISOLATED view).
  
  Specified by:
  
  getUnisolatedIndex in interface IGISTLocalManager
  
  Returns:
  The mutable view of the persistence capable data structure.
  See Also:
  IIndexManager#getIndex(String), GIST
  
  getOffset
  
  public final long getOffset(long addr)
  
  Description copied from interface: IAddressManager
  
  The offset on the store at which the datum is stored. While this is often the offset of a byte into a file on disk, implementations MAY assign offsets using other strategies.
  
  Specified by:
  
  getOffset in interface IAddressManager
  
  Parameters:
  addr - The opaque identifier that is the within store locator for some datum.
  
  Returns:
  The offset of that datum.
  
  getPhysicalAddress
  
  public final long getPhysicalAddress(long addr)
  
  Description copied from interface: IAddressManager
  
  Determine the unencoded physical address
  
  Specified by:
  
  getPhysicalAddress in interface IAddressManager
  
  Parameters:
  addr - The encoded address
  
  Returns:
  an unencoded address offset
  
  getByteCount
  
  public final int getByteCount(long addr)
  
  Description copied from interface: IAddressManager
  
  The length of the datum in bytes. This must be the actual length of the record on the disk, not the length of the caller's byte[]. This is necessary in order to support transparent checksums and/or compression for records in the IRawStore.
  
  Specified by:
  
  getByteCount in interface IAddressManager
  
  Parameters:
  addr - The opaque identifier that is the within store locator for some datum.
  
  Returns:
  The offset of that datum.
  
  toAddr
  
  public final long toAddr(int nbytes, long offset)
  
  Description copied from interface: IAddressManager
  
  Converts a byte count and offset into a long integer.
  
  Specified by:
  
  toAddr in interface IAddressManager
  
  Parameters:
  nbytes - The byte count.
  offset - The byte offset.
  
  Returns:
  The long integer.
  
  toString
  
  public final String toString(long addr)
  
  Description copied from interface: IAddressManager
  
  A human readable representation of the address.
  
  Specified by:
  
  toString in interface IAddressManager
  
  Parameters:
  addr - The opaque identifier that is the within store locator for some datum.
  
  Returns:
  A human readable representation.
  
  getOffsetBits
  
  public final int getOffsetBits()
  
  getMaxRecordSize
  
  public final int getMaxRecordSize()
  
  The maximum length of a record that may be written on the store.
  
  getQuorumToken
  
  protected long getQuorumToken()
  
  clearQuorumToken
  
  protected void clearQuorumToken(long newValue)
  
  This method will update the quorum token on the journal and the associated values as if the service was not joined with a met quorum. This allows us to handle conditions where we know that the service will not be joined with the met quorum once it is able to observe the associated quorum events. However, those events can not be delivered until the service is connected to zookeeper and one of the common causes for entering the error state for the HAJournalServer is because the zk client connection has been closed, hence, no zk events.
  
  Parameters:
  newValue - The new value.
  
  setQuorumToken
  
  protected void setQuorumToken(long newValue)
  
  awaitHAReady
  
  public final long awaitHAReady(long timeout, TimeUnit units) throws InterruptedException, TimeoutException, AsynchronousQuorumCloseException
  
  Description copied from interface: IJournal
  
  Await the service being ready to partitipate in an HA quorum. The preconditions include:
  
  receiving notice of the quorum token via #setQuorumToken(long)
  
  The service is joined with the met quorum for that token
  
  If the service is a follower and it's local root blocks were at commitCounter:=0, then the root blocks from the leader have been installed on the follower.
  
  Specified by:
  
  awaitHAReady in interface IJournal
  
  Parameters:
  timeout - The timeout to await this condition.
  units - The units for that timeout.
  
  Returns:
  the quorum token for which the service became HA ready.
  
  Throws:
  
  InterruptedException
  
  TimeoutException
  
  AsynchronousQuorumCloseException
  
  getHAReady
  
  public final long getHAReady()
  
  Returns the current value of the haReadyToken (non-blocking).
  
  getHAStatus
  
  public final HAStatusEnum getHAStatus()
  
  A simplified summary of the HA status of the service. This may be used to reliably decide whether the service is the HAStatusEnum.Leader, a HAStatusEnum.Follower, or HAStatusEnum.NotReady. This is exposed both here (an RMI interface) and by the REST API.
  
  Returns:
  The HAStatusEnum or null if the store is not associated with a Quorum.
  See Also:
  HAGlue.getHAStatus()
  
  assertHAReady
  
  public final void assertHAReady(long token) throws QuorumException
  
  Assert that the getHAReady() token has the specified value.
  
  Parameters:
  token - The specified value.
  
  Throws:
  
  QuorumException
  
  installRootBlocks
  
  protected void installRootBlocks(IRootBlockView rootBlock0, IRootBlockView rootBlock1)
  
  Install identical root blocks on the journal. This is used for a few different conditions in HA.
  
  When the quorum meets for the first time, we need to take the root block from the leader and use it to replace both of our root blocks (the initial root blocks are identical). That will make the root blocks the same on all quorum members.
  
  REBUILD: When a service goes through an automated disaster recovery, we need to install new root blocks in order to make the local journal logically empty. This prevents the service from attempting to interpret the data on the backing file if there is a restart part way through the rebuild operation.
  
  FIXME We should also verify the following:
  - the DirectBufferPool.INSTANCE has the same buffer capacity (so there will be room for the write cache data in the buffers on all nodes).
  
  See Also:
  QuorumService#installRootBlocks(IRootBlockView)
  
  doLocalAbort
  
  public final void doLocalAbort()
  
  Local commit protocol (HA). This exists to do a non-2-phase abort in HA.
  
  doLocalCommit
  
  public final void doLocalCommit(IRootBlockView rootBlock)
  
  Local commit protocol (HA, offline).
  Note: This is used to support RESTORE by replay of HALog files when the HAJournalServer is offline. TODO This method should be protected. If we move the HARestore class into this package, then it can be changed from public to protected or package private.
  
  doLocalCommit
  
  protected void doLocalCommit(QuorumService<HAGlue> localService, IRootBlockView rootBlock)
  
  Local commit protocol (HA).
  
  Parameters:
  localService - For HA modes only. When non-null, this is used to identify whether the service is the leader. When the service is not the leader, we need to do some additional work to maintain the IRWStrategy allocators in synch at each commit point.
  rootBlock - The new root block.
  
  getQuorum
  
  public Quorum<HAGlue,QuorumService<HAGlue>> getQuorum()
  
  Description copied from interface: IJournal
  
  The Quorum for this service -or- null if the service is not running with a quorum.
  
  Specified by:
  
  getQuorum in interface IJournal
  
  newHAGlue
  
  protected HAGlue newHAGlue(UUID serviceId)
  
  Factory for the HADelegate object for this AbstractJournal. The object returned by this method will be made available using QuorumMember.getService().
  
  Throws:
  
  UnsupportedOperationException - always.
  
  getRootBlocks
  
  protected IRootBlockView[] getRootBlocks()
  
  Return both root blocks (atomically - used by HA).
  Note: This takes a lock to ensure that the root blocks are consistent with a commit point on the backing store.
  
  snapshotAllocationData
  
  public AbstractJournal.ISnapshotData snapshotAllocationData(AtomicReference<IRootBlockView> rbv) throws IOException
  
  With lock held to ensure that there is no concurrent commit, copy key data atomically to ensure recovered snapshot is consistent with the commit state when the snapshot is taken. This atomic data snapshot can be merged with the file data to ensure a valid new store copy.
  If this is not done then it is possible for the allocation data - both metabits and fixed allocator commit bits - to be overwritten and inconsistent with the saved root blocks.
  
  Throws:
  
  IOException
  
  removeCommitRecordEntries
  
  public int removeCommitRecordEntries(byte[] fromKey, byte[] toKey)
  
  Remove all commit records between the two provided keys.
  This is called from the RWStore when it checks for deferredFrees against the CommitRecordIndex where the CommitRecords reference the deleteBlocks that have been deferred.
  Once processed the records for the effected range muct be removed as they reference invalid states.
  
  Parameters:
  fromKey -
  toKey -
  See Also:
  https://sourceforge.net/apps/trac/bigdata/ticket/440, IHistoryManager.checkDeferredFrees(AbstractJournal)
  
  newAllocationContext
  
  public IAllocationContext newAllocationContext(boolean isolated)
  
  Description copied from interface: IAllocationManager
  
  Creates a context to be used to isolate updates to within the context until it is released to the parent environment.
  
  Specified by:
  
  newAllocationContext in interface IAllocationManager
  
  Returns:
  a new IAlocationContext

Class AbstractJournal

Limitations

Commit processing

Nested Class Summary

Field Summary

Fields inherited from interface com.bigdata.rawstore.IAddressManager

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.bigdata.journal.IJournal

Methods inherited from interface com.bigdata.journal.IIndexManager

Methods inherited from interface com.bigdata.journal.IIndexStore

Field Detail

haLog

ROOT_NAME2ADDR

PREV_ROOTBLOCK

DELETEBLOCK

ROOT_ICUVERSION

properties

tmpDir

doubleSync

forceOnCommit

deleteOnClose

Constructor Detail

AbstractJournal

AbstractJournal

Method Detail

_getName2Addr

getName2Addr

getName2Addr

getMaximumExtent

getProperty

getProperty

getProperty

getProperties

getBufferStrategy

getExecutorService

shutdown

shutdownNow

finalize

getCounters

getIndexCounters

getFile

assertBefore

getMaximumClockSkewMillis

getHAPrepareTimeout

getHAReleaseTimeConsensusTimeout

_close

deleteResources

truncate

ensureMinFree

closeForWrites

close

destroy

assertOpen

getUUID

getResourceMetadata

isOpen

isReadOnly

assertCanRead

assertCanWrite

isStable

isFullyBuffered

isDoubleSync

isChecked

getRootBlockView

getRootBlockViewWithLock

getLastCommitTime

setCommitter

abort

rollback

isDirty

commit

commitNow

assertCommitTimeAdvances

assertPriorCommitTimeAdvances

force

size

read

write