com.sleepycat.je.txn

Class Locker

java.lang.Object

com.sleepycat.je.txn.Locker

Direct Known Subclasses:

BasicLocker, Txn

public abstract class Locker
extends java.lang.Object

Locker instances are JE's route to locking and transactional support. This class is the abstract base class for BasicLocker, ThreadLocker, Txn, MasterTxn and ReadonlyTxn. Locker instances are in fact only a transaction shell to get to the lock manager, and don't guarantee transactional semantics. Txn (includes Txns marked autoTxn) MasterTxn and ReadonlyTxn instances are truly transactional. They have potentially different transaction begin and end behaviors.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	defaultNoWait
protected java.util.Map<java.lang.Long,BINReference>	deleteInfo
protected EnvironmentImpl	envImpl
protected java.util.Map<java.lang.Long,java.util.Set<Database>>	handleLockToHandleMap
protected java.util.Map<Database,java.lang.Long>	handleToHandleLockMap
protected long	id
protected LockManager	lockManager
protected boolean	readUncommittedDefault
protected java.lang.Thread	thread The thread that created this locker.

Constructor Summary

Constructors

Modifier	Constructor and Description
(package private)	Locker() For reading from the log.
protected	Locker(EnvironmentImpl envImpl, boolean readUncommittedDefault, boolean noWait, boolean noAPIReadLock, long mandatedId) Create a locker id.
protected	Locker(EnvironmentImpl envImpl, boolean readUncommittedDefault, boolean noWait, long mandatedId) Create a locker id.

Method Summary

Methods

Modifier and Type	Method and Description
void	addDeleteInfo(BIN bin, Key deletedKey) Add delete information, to be added to the inCompressor queue when the transaction ends.
protected abstract void	addLock(java.lang.Long nodeId, LockType type, LockGrantType grantStatus) Add a lock to set owned by this transaction.
void	addToHandleMaps(java.lang.Long handleLockId, Database databaseHandle) Remember how handle locks and handles match up.
protected abstract void	checkState(boolean ignoreCalledByAbort)
(package private) void	close() Should be called by all subclasses when the locker is no longer used.
abstract LockStats	collectStats(LockStats stats) Get lock count, for per transaction lock stats, for internal debugging.
abstract boolean	createdNode(long nodeId)
void	demoteLock(long nodeId) Revert this lock from a write lock to a read lock.
void	dumpLockTable() Dump lock table, for debugging
protected abstract long	generateId(TxnManager txnManager, long mandatedId) A Locker has to generate its next id.
abstract long	getAbortLsn(long nodeId)
boolean	getDefaultNoWait()
long	getId()
long	getLockTimeout() Get the lock timeout period for this locker, in milliseconds WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.
abstract Txn	getTxnLocker() Returns the underlying Txn if the locker is transactional, or null if the locker is non-transactional.
(package private) long	getTxnStartMillis()
long	getTxnTimeout() Get the transaction timeout period for this locker, in milliseconds public for jca/ra/JELocalTransaction.
(package private) Lock	getWaitingFor()
abstract WriteLockInfo	getWriteLockInfo(long nodeId)
void	initApiReadLock()
boolean	isHandleLockTransferrable()
abstract boolean	isReadCommittedIsolation() Returns whether the isolation level of this locker is read-committed.
boolean	isReadUncommittedDefault()
abstract boolean	isSerializableIsolation() Returns whether the isolation level of this locker is serializable.
boolean	isTimedOut()
abstract boolean	isTransactional() Returns whether this locker is transactional.
LockResult	lock(long nodeId, LockType lockType, boolean noWait, DatabaseImpl database) Request a blocking or non-blocking lock of the given type on the given nodeId.
(package private) abstract LockResult	lockInternal(long nodeId, LockType lockType, boolean noWait, DatabaseImpl database) Abstract method to a blocking or non-blocking lock of the given type on the given nodeId.
abstract void	markDeleteAtTxnEnd(DatabaseImpl db, boolean deleteAtCommit) Database operations like remove and truncate leave behind residual DatabaseImpls that must be purged at transaction commit or abort.
(package private) abstract void	moveWriteToReadLock(long nodeId, Lock lock) A lock is being demoted.
abstract Locker	newNonTxnLocker() Creates a fresh non-transactional locker, while retaining any transactional locks held by this locker.
LockResult	nonBlockingLock(long nodeId, LockType lockType, DatabaseImpl database) Request a non-blocking lock of the given type on the given nodeId.
abstract void	nonTxnOperationEnd() Releases locks and closes the locker at the end of a non-transactional cursor operation.
void	operationEnd() The equivalent of calling operationEnd(true).
abstract void	operationEnd(boolean operationOK) Different types of transactions do different things when the operation ends.
void	operationEnd(OperationStatus status) A SUCCESS status equals operationOk.
abstract void	registerCursor(CursorImpl cursor) Tell this transaction about a cursor.
boolean	releaseLock(long nodeId) Release the lock on this LN and remove from the transaction's owning set.
abstract void	releaseNonTxnLocks() Releases any non-transactional locks held by this locker.
(package private) abstract void	removeLock(long nodeId) Remove the lock from the set owned by this transaction.
abstract void	setHandleLockOwner(boolean operationOK, Database dbHandle, boolean dbIsClosing) We're at the end of an operation.
void	setLockTimeout(long timeout) Set the lock timeout period for any locks in this transaction, in milliseconds.
void	setOnlyAbortable() Set the state of a transaction to ONLY_ABORTABLE.
void	setTxnTimeout(long timeout) Set the timeout period for this transaction, in milliseconds.
(package private) void	setWaitingFor(Lock lock)
boolean	sharesLocksWith(Locker other) Returns whether this locker can share locks with the given locker.
java.lang.String	toString()
void	transferHandleLock(Database dbHandle, Locker destLocker, boolean demoteToRead)
(package private) void	transferHandleLockToHandle(Database dbHandle) The currentTxn passes responsiblity for this db handle lock to a txn owned by the Database object.
abstract void	unRegisterCursor(CursorImpl cursor) Remove a cursor from this txn.
(package private) void	unregisterHandle(Database dbHandle) Remove this Database from the protected Database handle set

Methods inherited from class java.lang.Object

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

Field Detail

envImpl

protected EnvironmentImpl envImpl

lockManager

protected LockManager lockManager

id

protected long id

readUncommittedDefault

protected boolean readUncommittedDefault

defaultNoWait

protected boolean defaultNoWait

deleteInfo

protected java.util.Map<java.lang.Long,BINReference> deleteInfo

handleLockToHandleMap

protected java.util.Map<java.lang.Long,java.util.Set<Database>> handleLockToHandleMap

handleToHandleLockMap

protected java.util.Map<Database,java.lang.Long> handleToHandleLockMap

thread

protected java.lang.Thread thread

The thread that created this locker. Used for debugging, and by the ThreadLocker subclass. Note that thread may be null if the Locker is instantiated by reading the log.

Constructor Detail

Locker

protected Locker(EnvironmentImpl envImpl,
      boolean readUncommittedDefault,
      boolean noWait,
      long mandatedId)
          throws DatabaseException

Create a locker id. This constructor is called very often, so it should be as streamlined as possible. It should never be called directly, because the mandatedId mechanism only works if the generateId() method is overridden to use the mandatedId value.

Parameters:

lockManager - lock manager for this environment

readUncommittedDefault - if true, this transaction does read-uncommitted by default

noWait - if true, non-blocking lock requests are used.

Throws:

DatabaseException

Locker

protected Locker(EnvironmentImpl envImpl,
      boolean readUncommittedDefault,
      boolean noWait,
      boolean noAPIReadLock,
      long mandatedId)
          throws DatabaseException

Create a locker id. This constructor is called very often, so it should be as streamlined as possible. It should never be called directly, because the mandatedId mechanism only works if the generateId() method is overridden to use the mandatedId value.

Parameters:

lockManager - lock manager for this environment

readUncommittedDefault - if true, this transaction does read-uncommitted by default

noWait - if true, non-blocking lock requests are used.

noAPIReadLock - if true, the API read lock is not acquired.

Throws:

DatabaseException

Locker

Locker()

For reading from the log.

Method Detail

generateId

protected abstract long generateId(TxnManager txnManager,
              long mandatedId)

A Locker has to generate its next id. Some subtypes, like BasicLocker, have a single id for all instances because they are never used for recovery. Other subtypes ask the txn manager for an id or use a specific, mandated id.

getId

public long getId()

Returns:

the transaction's id.

getDefaultNoWait

public boolean getDefaultNoWait()

Returns:

the default no-wait (non-blocking) setting.

getLockTimeout

public long getLockTimeout()

Get the lock timeout period for this locker, in milliseconds WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.

setLockTimeout

public void setLockTimeout(long timeout)

Set the lock timeout period for any locks in this transaction, in milliseconds.

Parameters:

timeout - The timeout value for the transaction lifetime, in microseconds. A value of 0 disables timeouts for the transaction.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative

setTxnTimeout

public void setTxnTimeout(long timeout)

Set the timeout period for this transaction, in milliseconds.

Parameters:

timeout - The timeout value for the transaction lifetime, in microseconds. A value of 0 disables timeouts for the transaction.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative.

isReadUncommittedDefault

public boolean isReadUncommittedDefault()

Returns:

true if transaction was created with read-uncommitted as a default.

getWaitingFor

Lock getWaitingFor()

setWaitingFor

void setWaitingFor(Lock lock)

setOnlyAbortable

public void setOnlyAbortable()

Set the state of a transaction to ONLY_ABORTABLE.

initApiReadLock

public void initApiReadLock()
                     throws DatabaseException

Throws:

DatabaseException

checkState

protected abstract void checkState(boolean ignoreCalledByAbort)
                            throws DatabaseException

Throws:

DatabaseException

lockInternal

abstract LockResult lockInternal(long nodeId,
                      LockType lockType,
                      boolean noWait,
                      DatabaseImpl database)
                          throws DeadlockException,
                                 DatabaseException

Abstract method to a blocking or non-blocking lock of the given type on the given nodeId. Unlike the lock() method, this method does not throw LockNotGrantedException and can therefore be used by nonBlockingLock to probe for a lock without the overhead of an exception stack trace.

Parameters:

nodeId - 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 LockNotGrantedException if the lock cannot be granted without waiting.

database - is the database containing nodeId.

Throws:

DeadlockException - if acquiring a blocking lock would result in a deadlock.

DatabaseException

lock

public LockResult lock(long nodeId,
              LockType lockType,
              boolean noWait,
              DatabaseImpl database)
                throws LockNotGrantedException,
                       DeadlockException,
                       DatabaseException

Request a blocking or non-blocking lock of the given type on the given nodeId.

Parameters:

nodeId - 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 LockNotGrantedException if the lock cannot be granted without waiting.

database - is the database containing nodeId.

Throws:

LockNotGrantedException - if a non-blocking lock was denied.

DeadlockException - if acquiring a blocking lock would result in a deadlock.

DatabaseException

nonBlockingLock

public LockResult nonBlockingLock(long nodeId,
                         LockType lockType,
                         DatabaseImpl database)
                           throws DatabaseException

Request a non-blocking lock of the given type on the given nodeId.

Unlike lock(), this method returns LockGrantType.DENIED if the lock is denied rather than throwing LockNotGrantedException. This method should therefore not be used as the final lock for a user operation, since in that case LockNotGrantedException should be thrown for a denied lock. It is normally used only to probe for a lock, and other recourse is taken if the lock is denied.

Parameters:

nodeId - is the node to lock.

lockType - is the type of lock to request.

database - is the database containing nodeId.

Throws:

DatabaseException

releaseLock

public boolean releaseLock(long nodeId)
                    throws DatabaseException

Release the lock on this LN and remove from the transaction's owning set.

Throws:

DatabaseException

demoteLock

public void demoteLock(long nodeId)
                throws DatabaseException

Revert this lock from a write lock to a read lock.

Throws:

DatabaseException

isTransactional

public abstract boolean isTransactional()

Returns whether this locker is transactional.

isSerializableIsolation

public abstract boolean isSerializableIsolation()

Returns whether the isolation level of this locker is serializable.

isReadCommittedIsolation

public abstract boolean isReadCommittedIsolation()

Returns whether the isolation level of this locker is read-committed.

getTxnLocker

public abstract Txn getTxnLocker()

Returns the underlying Txn if the locker is transactional, or null if the locker is non-transactional. For a Txn-based locker, this method returns 'this'. For a BuddyLocker, this method may returns the buddy.

newNonTxnLocker

public abstract Locker newNonTxnLocker()
                                throws DatabaseException

Creates a fresh non-transactional locker, while retaining any transactional locks held by this locker. This method is called when the cursor for this locker is cloned.

This method must return a locker that shares locks with this locker, e.g., a ThreadLocker.

In general, transactional lockers return 'this' when this method is called, while non-transactional lockers return a new instance.

Throws:

DatabaseException

releaseNonTxnLocks

public abstract void releaseNonTxnLocks()
                                 throws DatabaseException

Releases any non-transactional locks held by this locker. This method is called when the cursor moves to a new position or is closed.

In general, transactional lockers do nothing when this method is called, while non-transactional lockers release all locks as if operationEnd were called.

Throws:

DatabaseException

nonTxnOperationEnd

public abstract void nonTxnOperationEnd()
                                 throws DatabaseException

Releases locks and closes the locker at the end of a non-transactional cursor operation. For a transctional cursor this method should do nothing, since locks must be held until transaction end.

Throws:

DatabaseException

sharesLocksWith

public boolean sharesLocksWith(Locker other)

Returns whether this locker can share locks with the given locker.

All lockers share locks with a BuddyLocker whose buddy is this locker. To support BuddyLocker when overriding this method, always return true if this implementation (super.sharesLocksWith(...)) returns true.

operationEnd

public final void operationEnd()
                        throws DatabaseException

The equivalent of calling operationEnd(true).

Throws:

DatabaseException

operationEnd

public final void operationEnd(OperationStatus status)
                        throws DatabaseException

A SUCCESS status equals operationOk.

Throws:

DatabaseException

operationEnd

public abstract void operationEnd(boolean operationOK)
                           throws DatabaseException

Different types of transactions do different things when the operation ends. Txn does nothing, auto Txn commits or aborts, and BasicLocker (and its subclasses) just releases locks.

Parameters:

operationOK - is whether the operation succeeded, since that may impact ending behavior. (i.e for an auto Txn)

Throws:

DatabaseException

close

void close()
     throws DatabaseException

Should be called by all subclasses when the locker is no longer used. For Txns and auto Txns this is at commit or abort. For non-transactional lockers it is at operationEnd.

Throws:

DatabaseException

setHandleLockOwner

public abstract void setHandleLockOwner(boolean operationOK,
                      Database dbHandle,
                      boolean dbIsClosing)
                                 throws DatabaseException

We're at the end of an operation. Move this handle lock to the appropriate owner.

Throws:

DatabaseException

registerCursor

public abstract void registerCursor(CursorImpl cursor)
                             throws DatabaseException

Tell this transaction about a cursor.

Throws:

DatabaseException

unRegisterCursor

public abstract void unRegisterCursor(CursorImpl cursor)
                               throws DatabaseException

Remove a cursor from this txn.

Throws:

DatabaseException

getAbortLsn

public abstract long getAbortLsn(long nodeId)
                          throws DatabaseException

Returns:

the abort LSN for this node.

Throws:

DatabaseException

getWriteLockInfo

public abstract WriteLockInfo getWriteLockInfo(long nodeId)
                                        throws DatabaseException

Returns:

the WriteLockInfo for this node.

Throws:

DatabaseException

markDeleteAtTxnEnd

public abstract void markDeleteAtTxnEnd(DatabaseImpl db,
                      boolean deleteAtCommit)
                                 throws DatabaseException

Database operations like remove and truncate leave behind residual DatabaseImpls that must be purged at transaction commit or abort.

Throws:

DatabaseException

addDeleteInfo

public void addDeleteInfo(BIN bin,
                 Key deletedKey)
                   throws DatabaseException

Add delete information, to be added to the inCompressor queue when the transaction ends.

Throws:

DatabaseException

addLock

protected abstract void addLock(java.lang.Long nodeId,
           LockType type,
           LockGrantType grantStatus)
                         throws DatabaseException

Add a lock to set owned by this transaction.

Throws:

DatabaseException

createdNode

public abstract boolean createdNode(long nodeId)
                             throws DatabaseException

Returns:

true if this transaction created this node, for a operation with transactional semantics.

Throws:

DatabaseException

removeLock

abstract void removeLock(long nodeId)
                  throws DatabaseException

Remove the lock from the set owned by this transaction. If specified to LockManager.release, the lock manager will call this when its releasing a lock.

Throws:

DatabaseException

moveWriteToReadLock

abstract void moveWriteToReadLock(long nodeId,
                       Lock lock)

A lock is being demoted. Move it from the write collection into the read collection.

collectStats

public abstract LockStats collectStats(LockStats stats)
                                throws DatabaseException

Get lock count, for per transaction lock stats, for internal debugging.

Throws:

DatabaseException

isTimedOut

public boolean isTimedOut()
                   throws DatabaseException

Throws:

DatabaseException

getTxnTimeout

public long getTxnTimeout()

Get the transaction timeout period for this locker, in milliseconds public for jca/ra/JELocalTransaction. WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.

getTxnStartMillis

long getTxnStartMillis()

unregisterHandle

void unregisterHandle(Database dbHandle)

Remove this Database from the protected Database handle set

addToHandleMaps

public void addToHandleMaps(java.lang.Long handleLockId,
                   Database databaseHandle)

Remember how handle locks and handles match up.

isHandleLockTransferrable

public boolean isHandleLockTransferrable()

Returns:

true if this txn is willing to give up the handle lock to another txn before this txn ends.

transferHandleLockToHandle

void transferHandleLockToHandle(Database dbHandle)
                          throws DatabaseException

The currentTxn passes responsiblity for this db handle lock to a txn owned by the Database object.

Throws:

DatabaseException

transferHandleLock

public void transferHandleLock(Database dbHandle,
                      Locker destLocker,
                      boolean demoteToRead)
                        throws DatabaseException

Throws:

DatabaseException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

dumpLockTable

public void dumpLockTable()
                   throws DatabaseException

Dump lock table, for debugging

Throws:

DatabaseException