com.sleepycat.je.txn
Class Locker

java.lang.Object
  extended by 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
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
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
 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)
           
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.
 long getTxnTimeout()
          Get the transaction timeout period for this locker, in milliseconds public for jca/ra/JELocalTransaction.
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.
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.
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.
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.
 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)
           
abstract  void unRegisterCursor(CursorImpl cursor)
          Remove a cursor from this txn.
 
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
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.

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

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

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

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.


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.

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