com.sleepycat.je.rep.txn

Class MasterTxn

java.lang.Object

com.sleepycat.je.txn.Locker

com.sleepycat.je.txn.Txn

com.sleepycat.je.rep.txn.MasterTxn

All Implemented Interfaces:

Loggable, VersionedWriteLoggable

public class MasterTxn
extends Txn

A MasterTxn represents: - a user initiated Txn executed on the Master node, when local-write and read-only are not configured, or - an auto-commit Txn on the Master node for a replicated DB. This class uses the hooks defined by Txn to support the durability requirements of a replicated transaction on the Master.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MasterTxn.MasterTxnFactory

Field Summary

Fields inherited from class com.sleepycat.je.txn.Txn

ACCUMULATED_LIMIT, commitLsn, dbCleanupSet, firstLoggedLsn, lastLoggedLsn, openedDatabaseHandles, repContext, undoDatabases

Fields inherited from class com.sleepycat.je.txn.Locker

afterWaiterHook, envImpl, id, lockManager, thread

Constructor Summary

Constructors

Constructor and Description
MasterTxn(EnvironmentImpl envImpl, TransactionConfig config, NameIdPair nameIdPair)

Method Summary

Modifier and Type	Method and Description
protected void	checkIfFrozen(boolean isCommit) Used to hold the transaction stable while it is being cloned as a ReplayTxn, during master->replica transitions.
ReplayTxn	convertToReplayTxnAndClose(Logger logger, Replay replay) Convert a MasterTxn that has any write locks into a ReplayTxn, and close the MasterTxn after it is disemboweled.
static MasterTxn	create(EnvironmentImpl envImpl, TransactionConfig config, NameIdPair nameIdPair)
static MasterTxn	createNullTxn(EnvironmentImpl envImpl, TransactionConfig config, NameIdPair nameIdPair)
void	freeze()
protected long	generateId(TxnManager txnManager, long ignore) MasterTxns use txn ids from a reserved negative space.
boolean	getArbiterAck()
CommitToken	getCommitToken() Returns the transaction commit token used to identify the transaction.
VLSN	getCommitVLSN()
protected long	getDTVLSN() This method is overridden by replication txn subclasses and returns the DTVLSN associated with the Txn.
protected int	getReplicatorNodeId() A masterTxn always writes its own id into the commit or abort.
int	getRequiredAckCount()
long	getStartMs()
boolean	isLocalWrite() Returns true if writes may only be to non-replicated DBs using this locker, or false if writes may only be to replicated DBs.
boolean	isMasterTxn()
LockResult	lockInternal(long lsn, LockType lockType, boolean noWait, boolean jumpAheadOfWaiters, DatabaseImpl database) Prevent this MasterTxn from taking locks if the node becomes a replica.
boolean	lockOnce() Determines whether we should lock the block-latch lock.
long	messageTransferMs() Returns the amount of time it took to copy the commit record from the log buffer to the rep stream.
protected void	postLogAbortHook()
protected void	postLogCommitAbortHook() Invoked if the transaction associated with the preLogCommitHook was subsequently aborted, for example due to a lack of disk space.
protected void	postLogCommitHook(LogItem commitItem) This hook is invoked after the commit record has been written to the log, but before write locks have been released, so that other application cannot see the changes made by the transaction.
protected void	preLogAbortHook()
protected void	preLogCommitHook() This hook is invoked before the commit of a transaction that made changes to a replicated environment.
void	preLogWithoutLock(DatabaseImpl database) If logging occurs before locking, we must screen out write locks here.
protected boolean	propagatePostCommitException(DatabaseException postCommitException) Identifies exceptions that may be propagated back to the caller during the postCommit phase of a transaction commit.
void	resetRequiredAckCount()
void	setArbiterAck(boolean val)
void	setConvertHook(TestHook<Integer> hook)
static void	setFactory(MasterTxn.MasterTxnFactory factory) Method used for unit testing.
void	stampRepWriteTime()
protected void	txnBeginHook(TransactionConfig config) Causes the transaction to wait until we have sufficient replicas to acknowledge the commit.
boolean	unlockOnce() Determines whether we should unlock the block-latch lock.

Methods inherited from class com.sleepycat.je.txn.Txn

abort, abort, abort, addDbCleanup, addLock, addLogInfo, addOpenedDatabase, checkPreempted, checkState, cleanupDatabaseImpls, clearReadLocks, clearWriteLocks, close, collectStats, commit, commit, commit, createAutoTxn, createLocalAutoTxn, createLocalTxn, dumpLog, getCommitDurability, getDbCleanupSet, getDefaultDurability, getEmbeddedLoggables, getEnvironmentImpl, getExplicitDurabilityConfigured, getExplicitSyncConfigured, getFirstActiveLsn, getImportunate, getLastFormatChange, getLastLsn, getLogSize, getLogSize, getPrepared, getReadLockIds, getState, getTransaction, getTransactionId, getTriggerDbs, getTxnLocker, getUndoDatabases, getWriteLockIds, getWriteLockInfo, hasReplicationFormat, isAutoTxn, isClosed, isOnlyAbortable, isReadCommittedIsolation, isReadOnly, isReplicationFormatWorthwhile, isRolledBack, isSerializableIsolation, isSuspended, isTransactional, isValid, lockingRequired, logicalEquals, newNonTxnLocker, nonTxnOperationEnd, noteTriggerDb, operationEnd, prepare, readFromLog, registerCursor, registerImmediately, releaseNonTxnLocks, releaseWriteLocks, removeLock, setDbCleanupState, setImportunate, setOnlyAbortable, setPrepared, setRollback, setSuspended, setTransaction, undo, unRegisterCursor, updateLoggedForTxn, writeToLog, writeToLog

Methods inherited from class com.sleepycat.je.txn.Locker

addDeleteInfo, allowReleaseLockAfterLsnChange, demoteLock, disallowReplicaWrite, dumpLockTable, getDefaultNoWait, getEnvironment, getId, getInitialLockTimeout, getLockTimeout, getPreemptable, getTxnTimeout, isReadUncommittedDefault, isReplicated, isTimedOut, lock, lockAfterLsnChange, nonBlockingLock, openCursorHook, operationEnd, operationEnd, releaseLock, setClosingLocker, setDefaultNoWait, setLockTimeout, setPreemptable, setPreempted, setTxnTimeout, sharesLocksWith, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MasterTxn

public MasterTxn(EnvironmentImpl envImpl,
                 TransactionConfig config,
                 NameIdPair nameIdPair)
          throws DatabaseException

Throws:

DatabaseException

Method Detail

isLocalWrite

public boolean isLocalWrite()

Description copied from class: Locker

Returns true if writes may only be to non-replicated DBs using this locker, or false if writes may only be to replicated DBs. By default (this implementation) local-write is true, since it is allowed for all non-txnal lockers and for all lockers in a standalone environment. This method is overridden and returns false for for user transactions in a replicated environment that are not explicitly configured for local-write. This method is used to describe a locker's configured usage for checking the validity of an API write operation. This is checked by Cursor methods at the beginning of each write operation.

Overrides:

isLocalWrite in class Locker

getCommitToken

public CommitToken getCommitToken()

Returns the transaction commit token used to identify the transaction.

Overrides:

getCommitToken in class Txn

See Also:

Txn.getCommitToken()

getCommitVLSN

public VLSN getCommitVLSN()

generateId

protected long generateId(TxnManager txnManager,
                          long ignore)

MasterTxns use txn ids from a reserved negative space. So override the default generation of ids.

Overrides:

generateId in class Txn

txnBeginHook

protected void txnBeginHook(TransactionConfig config)
                     throws DatabaseException

Causes the transaction to wait until we have sufficient replicas to acknowledge the commit.

Overrides:

txnBeginHook in class Txn

Parameters:

config - the transaction config that applies to the txn

Throws:

DatabaseException - if there is a failure

preLogCommitHook

protected void preLogCommitHook()
                         throws DatabaseException

Description copied from class: Txn

This hook is invoked before the commit of a transaction that made changes to a replicated environment. It's invoked for transactions executed on the master or replica, but is only relevant to transactions being done on the master. When invoked for a transaction on a replica the implementation just returns. The hook is invoked at a very specific point in the normal commit sequence: immediately before the commit log entry is written to the log. It represents the last chance to abort the transaction and provides an opportunity to make some final checks before allowing the commit can go ahead. Note that it should be possible to abort the transaction at the time the hook is invoked. After invocation of the "pre" hook one of the "post" hooks: postLogCommitHook or postLogAbortHook must always be invoked. Exceptions thrown by this hook result in the transaction being aborted and the exception being propagated back to the application.

Overrides:

preLogCommitHook in class Txn

Throws:

DatabaseException - if there was a problem and that the transaction should be aborted.

postLogCommitHook

protected void postLogCommitHook(LogItem commitItem)
                          throws DatabaseException

Description copied from class: Txn

This hook is invoked after the commit record has been written to the log, but before write locks have been released, so that other application cannot see the changes made by the transaction. At this point the transaction has been committed by the Master. Exceptions thrown by this hook result in the transaction being completed on the Master, that is, locks are released, etc. and the exception is propagated back to the application.

Overrides:

postLogCommitHook in class Txn

Parameters:

commitItem - the commit item that was just logged

Throws:

DatabaseException - to indicate that there was a replication related problem that needs to be communicated back to the application.

preLogAbortHook

protected void preLogAbortHook()
                        throws DatabaseException

Overrides:

preLogAbortHook in class Txn

Throws:

DatabaseException

postLogCommitAbortHook

protected void postLogCommitAbortHook()

Description copied from class: Txn

Invoked if the transaction associated with the preLogCommitHook was subsequently aborted, for example due to a lack of disk space. This method is responsible for any cleanup that may need to be done as a result of the abort. Note that only one of the "post" hooks (commit or abort) is invoked following the invocation of the "pre" hook.

Overrides:

postLogCommitAbortHook in class Txn

postLogAbortHook

protected void postLogAbortHook()

Overrides:

postLogAbortHook in class Txn

lockInternal

public LockResult lockInternal(long lsn,
                               LockType lockType,
                               boolean noWait,
                               boolean jumpAheadOfWaiters,
                               DatabaseImpl database)
                        throws LockNotAvailableException,
                               LockConflictException,
                               DatabaseException

Prevent this MasterTxn from taking locks if the node becomes a replica. The application has a reference to this Txn, and may attempt to use it well after the node has transitioned from master to replica.

Overrides:

lockInternal in class Txn

Parameters:

lsn - is the node to lock.

lockType - is the type of lock to request.

noWait - is true to override the defaultNoWait setting. If true, or if defaultNoWait is true, throws LockNotAvailableException if the lock cannot be granted without waiting.

jumpAheadOfWaiters - grant the lock before other waiters, if any.

database - is the database containing lsn.

Throws:

LockConflictException - if a blocking lock could not be acquired.

LockNotAvailableException

DatabaseException

See Also:

Locker.lockInternal(long, com.sleepycat.je.txn.LockType, boolean, boolean, com.sleepycat.je.dbi.DatabaseImpl)

preLogWithoutLock

public void preLogWithoutLock(DatabaseImpl database)

If logging occurs before locking, we must screen out write locks here.

Overrides:

preLogWithoutLock in class Txn

lockOnce

public boolean lockOnce()

Determines whether we should lock the block-latch lock.

We acquire the lock during pre-log hook, and release it during post-log hook. Specifically, there are the following cases:

1. For a normal commit, we acquire it in preLogCommitHook() and release it in postLogCommitHook()
2. For a normal abort (invoked by the application on the Txn.abort() API), we acquire the lock in preLogAbortHook() and release it in postLogAbortHook().
3. When a commit fails in such a way as to call Txn.throwPreCommitException(), we go through the abort path as well. In this case:
   • we will of course already have called preLogCommitHook();
   • the abort path calls preLogAbortHook() and postLogAbortHook() as always;
   • finally we call postLogCommitAbortHook()
   Fortunately we can avoid the complexity of dealing with a second (recursive) lock acquisition here, because by the time either post-hook is called we've done any writing of VLSNs. Thus, when we want to take the lock, we take it if it hasn't already been taken, and do nothing if it has; when releasing, we release it if we have it, and do nothing if we don't.

See additional javadoc at RepImpl.blockLatchLock

unlockOnce

public boolean unlockOnce()

Determines whether we should unlock the block-latch lock.

See Also:

lockOnce()

getRequiredAckCount

public int getRequiredAckCount()

resetRequiredAckCount

public void resetRequiredAckCount()

getReplicatorNodeId

protected int getReplicatorNodeId()

A masterTxn always writes its own id into the commit or abort.

Overrides:

getReplicatorNodeId in class Txn

getDTVLSN

protected long getDTVLSN()

Description copied from class: Txn

This method is overridden by replication txn subclasses and returns the DTVLSN associated with the Txn.

Overrides:

getDTVLSN in class Txn

getStartMs

public long getStartMs()

stampRepWriteTime

public void stampRepWriteTime()

messageTransferMs

public long messageTransferMs()

Returns the amount of time it took to copy the commit record from the log buffer to the rep stream. It's measured as the time interval starting with the time the preCommit hook completed, to the time the message write to the replication stream was initiated.

propagatePostCommitException

protected boolean propagatePostCommitException(DatabaseException postCommitException)

Description copied from class: Txn

Identifies exceptions that may be propagated back to the caller during the postCommit phase of a transaction commit.

Overrides:

propagatePostCommitException in class Txn

Parameters:

postCommitException - the exception being evaluated

Returns:

true if the exception must be propagated back to the caller, false if the exception indicates there is a serious problem with the commit operation and the environment should be invalidated.

create

public static MasterTxn create(EnvironmentImpl envImpl,
                               TransactionConfig config,
                               NameIdPair nameIdPair)

createNullTxn

public static MasterTxn createNullTxn(EnvironmentImpl envImpl,
                                      TransactionConfig config,
                                      NameIdPair nameIdPair)

setFactory

public static void setFactory(MasterTxn.MasterTxnFactory factory)

Method used for unit testing. Sets the factory to the one supplied. If the argument is null it restores the factory to the original default value.

convertToReplayTxnAndClose

public ReplayTxn convertToReplayTxnAndClose(Logger logger,
                                            Replay replay)

Convert a MasterTxn that has any write locks into a ReplayTxn, and close the MasterTxn after it is disemboweled. A MasterTxn that only has read locks is unchanged and is still usable by the application. To be clear, the application can never use a MasterTxn to obtain a lock if the node is in Replica mode, but may indeed be able to use a read-lock-only MasterTxn if the node cycles back into Master status. For converted MasterTxns, all write locks are transferred to a replay transaction, read locks are released, and the txn is closed. Used when a node is transitioning from master to replica mode without recovery, which may happen for an explicit master transfer request, or merely for a network partition/election of new master. The newly created replay transaction will need to be in the appropriate state, holding all write locks, so that the node in replica form can execute the proper syncups. Note that the resulting replay txn will only be aborted, and will never be committed, because the txn originated on this node, which is transitioning from master -> replica. We only transfer write locks. We need not transfer read locks, because replays only operate on writes, and are never required to obtain read locks. Read locks are released though, because (a) this txn is now only abortable, and (b) although the Replay can preempt any read locks held by the MasterTxn, such preemption will add delay.

Returns:

a ReplayTxn, if there were locks in this transaction, and there's a need to create a ReplayTxn.

freeze

public void freeze()

checkIfFrozen

protected void checkIfFrozen(boolean isCommit)

Used to hold the transaction stable while it is being cloned as a ReplayTxn, during master->replica transitions. Essentially, there are two parties that now have a reference to this transaction -- the originating application thread, and the RepNode thread that is trying to set up internal state so it can begin to act as a replica. The transaction will throw UnknownMasterException or ReplicaWriteException if the transaction is frozen, so that the application knows that the transaction is no longer viable, but it doesn't attempt to do most of the follow-on cleanup and release of locks that failed aborts and commits normally attempt. One aspect of transaction cleanup can't be skipped though. It is necessary to do the post log hooks to free up the block txn latch lock so that the transaction can be closed by the RepNode thread. For example: - application thread starts transaction - application takes the block txn latch lock and attempts commit or abort, but is stopped because the txn is frozen by master transfer. - the application must release the block txn latch lock.

Overrides:

checkIfFrozen in class Txn

Parameters:

isCommit - true if called by commit.

See Also:

Replica.replicaTransitionCleanup()

setConvertHook

public void setConvertHook(TestHook<Integer> hook)

isMasterTxn

public boolean isMasterTxn()

Overrides:

isMasterTxn in class Txn

setArbiterAck

public void setArbiterAck(boolean val)

getArbiterAck

public boolean getArbiterAck()