com.bigdata.ha

Interface HAGlue

All Superinterfaces:

HACommitGlue, HAGlueBase, HAPipelineGlue, HAReadGlue, HATXSGlue, IService, Remote

All Known Implementing Classes:

AbstractJournal.BasicHA

public interface HAGlue
extends HAGlueBase, HAPipelineGlue, HAReadGlue, HACommitGlue, HATXSGlue, IService

A Remote interface for methods supporting high availability for a set of journals or data services having shared persistent state.

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
long	awaitHAReady(long timeout, TimeUnit unit) Await the service being ready to partitipate in an HA quorum.
IHANotifyReleaseTimeResponse	awaitServiceJoin(IHAAwaitServiceJoinRequest req) A follower uses this message to request that the quorum leader await the visibility of the zookeeper event in which the service join becomes visible to the leader.
IHADigestResponse	computeDigest(IHADigestRequest req) Compute the digest of the entire backing store - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES.
IHALogDigestResponse	computeHALogDigest(IHALogDigestRequest req) Compute the digest of the entire HALog file - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES.
IHASnapshotDigestResponse	computeHASnapshotDigest(IHASnapshotDigestRequest req) Compute the digest of the entire snapshot file - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES. This digest is computed for the compressed data so it may be compared directly with the digest of the backing store from which the snapshot was obtained.
String	getExtendedRunState() The extended run state of the service - this embeds more information but is not designed for progamatic interpretation.
HAStatusEnum	getHAStatus() A simplified summary of the HA status of the service.
int	getNSSPort() The port that the NanoSparqlServer is running on.
IHARootBlockResponse	getRootBlock(IHARootBlockRequest msg) Return the then current root block for the persistence store.
RunState	getRunState() The RunState of the service - this does NOT tell you whether the service is ready to act as a leader or follower.
Future<Void>	rebuildFromLeader(IHARemoteRebuildRequest req) Disaster recovery (REBUILD) of the local database instance from the leader of a met quorum.
<T> Future<T>	submit(IIndexManagerCallable<T> callable, boolean asyncFuture) Run the caller's task on the service.
Future<IHASnapshotResponse>	takeSnapshot(IHASnapshotRequest req) Request that the service take a snapshot.

Methods inherited from interface com.bigdata.ha.HAGlueBase

getServiceId

Methods inherited from interface com.bigdata.ha.HAPipelineGlue

getHALogRootBlocksForWriteSet, getHAWriteSetState, getWritePipelineAddr, moveToEndOfPipeline, receiveAndReplicate, resetPipeline, sendHALogForWriteSet, sendHAStore

Methods inherited from interface com.bigdata.ha.HAReadGlue

readFromDisk

Methods inherited from interface com.bigdata.ha.HACommitGlue

abort2Phase, commit2Phase, prepare2Phase

Methods inherited from interface com.bigdata.ha.HATXSGlue

gatherMinimumVisibleCommitTime, notifyEarliestCommitTime

Methods inherited from interface com.bigdata.service.IService

destroy, getHostname, getServiceIface, getServiceName, getServiceUUID

Method Detail

awaitHAReady

long awaitHAReady(long timeout,
                TimeUnit unit)
                  throws IOException,
                         InterruptedException,
                         TimeoutException,
                         QuorumException,
                         AsynchronousQuorumCloseException

Await the service being ready to partitipate in an HA quorum. The preconditions include:

1. receiving notice of the quorum token via #setQuorumToken(long)
2. The service is joined with the met quorum for that token
3. 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.

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:

IOException

InterruptedException

TimeoutException

QuorumException

AsynchronousQuorumCloseException

awaitServiceJoin

IHANotifyReleaseTimeResponse awaitServiceJoin(IHAAwaitServiceJoinRequest req)
                                              throws IOException,
                                                     InterruptedException,
                                                     TimeoutException

A follower uses this message to request that the quorum leader await the visibility of the zookeeper event in which the service join becomes visible to the leader. This is invoked while holding a lock that blocks pipeline replication, so the leader can not flush the write replication pipeline and enter the commit. The callback to the leader ensures that the service join is visible to the leader before the leader makes an atomic decision about the set of services that are joined with the met quorum for a 2-phase commit.

Parameters:

req - The request.

Returns:

The most recent consensus release time for the quorum leader. This information is used to ensure that a service which joins after a gather and before a PREPARE will join with the correct release time for its local journal and thus will not permit transactions to start against commit points which have been recycled by the quorum leader.

Throws:

InterruptedException

TimeoutException - if the timeout is exceeded before the service join becomes visible to this service.

IOException

See Also:

HAJournalServer deadlock: pipelineRemove() and getLeaderId()

getRootBlock

IHARootBlockResponse getRootBlock(IHARootBlockRequest msg)
                                  throws IOException

Return the then current root block for the persistence store.

Note: The initial root blocks are identical, so this may be used to create a new journal in a quorum by replicating the root blocks of the quorum leader.

Parameters:

msg - The message requesting the then current root block.

Returns:

The then current root block.

Throws:

IOException

getNSSPort

int getNSSPort()
               throws IOException

The port that the NanoSparqlServer is running on.

Throws:

IOException

getRunState

RunState getRunState()
                     throws IOException

The RunState of the service - this does NOT tell you whether the service is ready to act as a leader or follower.

Throws:

IOException

getExtendedRunState

String getExtendedRunState()
                           throws IOException

The extended run state of the service - this embeds more information but is not designed for progamatic interpretation.

Throws:

IOException

getHAStatus

HAStatusEnum getHAStatus()
                         throws IOException

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.

Throws:

IOException

computeDigest

IHADigestResponse computeDigest(IHADigestRequest req)
                                throws IOException,
                                       NoSuchAlgorithmException,
                                       DigestException

Compute the digest of the entire backing store - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES.

The digest is useless if there are concurrent writes since it can not be meaningfully compared with the digest of another store unless both stores are known to be stable.

Throws:

IOException

NoSuchAlgorithmException

DigestException

computeHALogDigest

IHALogDigestResponse computeHALogDigest(IHALogDigestRequest req)
                                        throws IOException,
                                               NoSuchAlgorithmException,
                                               DigestException

Compute the digest of the entire HALog file - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES.

The digest is useless if there are concurrent writes since it can not be meaningfully compared with the digest of another store unless both stores are known to be stable.

Throws:

FileNotFoundException - if the HALog for the specified commit point does not exist.

IOException

NoSuchAlgorithmException

DigestException

computeHASnapshotDigest

IHASnapshotDigestResponse computeHASnapshotDigest(IHASnapshotDigestRequest req)
                                                  throws IOException,
                                                         NoSuchAlgorithmException,
                                                         DigestException

Compute the digest of the entire snapshot file - THIS METHOD IS ONLY FOR DIAGNOSTIC PURPOSES. This digest is computed for the compressed data so it may be compared directly with the digest of the backing store from which the snapshot was obtained.

Throws:

FileNotFoundException - if no snapshot exists for that commit point.

IOException

NoSuchAlgorithmException

DigestException

takeSnapshot

Future<IHASnapshotResponse> takeSnapshot(IHASnapshotRequest req)
                                         throws IOException

Request that the service take a snapshot. If there is already a snapshot in progress, then the Future for that request will be returned.

Parameters:

req - The request (optional). When null, the Future for any existing snapshot operation will be returned but the request WILL NOT schedule a snapshot if none is running.

Returns:

A Future for the snapshot -or- null if no snapshot is running and none will be taken for that request.

Throws:

IOException

rebuildFromLeader

Future<Void> rebuildFromLeader(IHARemoteRebuildRequest req)
                               throws IOException

Disaster recovery (REBUILD) of the local database instance from the leader of a met quorum. There are several preconditions:

• The quorum must be met and there must be an HAStatusEnum#Ready leader.
• This service must be HAStatusEnum.NotReady.
• This service MUST NOT be at the same commit point as the leader (if it is, then the service could meet in a data race with the met quorum and we do not permit RESTORE if the service is joined with the met quorum).
• The HAJournalServer must not be running a RESTORE (we don't want it to accidentally interrupt a RESTORE that is in progress).

Returns:

The (asynchronous) Future of the REBUILD operation -or- null if any of the pre-conditions were violated.

Throws:

IOException

submit

<T> Future<T> submit(IIndexManagerCallable<T> callable,
                   boolean asyncFuture)
                 throws IOException

Run the caller's task on the service.

Note: This interface provides direct access to the raw index manager. Caller's requiring concurrency control should submit an IApiTask in order to have their task queue for the necessary locks and run on the appropriate executor service.

Parameters:

callable - The task to run on the service.

asyncFuture - true if the task will execute asynchronously and return a Future for the computation that may be used to inspect and/or cancel the computation. false if the task will execute synchronously and return a thick Future.

Throws:

IOException