org.apache.derby.iapi.services.locks
Interface LockFactory

All Superinterfaces:
PropertySetCallback
All Known Implementing Classes:
AbstractPool, ConcurrentPool, SinglePool

public interface LockFactory
extends PropertySetCallback

Generic locking of objects. Enables deadlock detection.
MT - Mutable - Container Object - Thread Safe


Method Summary
 boolean anyoneBlocked()
          Returns true if locks held by anyone are blocking anyone else
 boolean areLocksHeld(CompatibilitySpace compatibilitySpace)
          Return true if locks are held in this compatibility space.
 boolean areLocksHeld(CompatibilitySpace compatibilitySpace, java.lang.Object group)
          Return true if locks are held in this compatibility space and this group.
 void clearLimit(CompatibilitySpace compatibilitySpace, java.lang.Object group)
          Clear a limit set by setLimit.
 CompatibilitySpace createCompatibilitySpace(LockOwner owner)
          Create an object which can be used as a compatibility space.
 int getWaitTimeout()
          Get the lock timeout in milliseconds.
 boolean isLockHeld(CompatibilitySpace compatibilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier)
          Check to see if a specific lock is held.
 boolean lockObject(CompatibilitySpace compatibilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout)
          Lock an object within a compatibility space and associate the lock with a group object, waits up to timeout milli-seconds for the object to become unlocked.
 java.util.Enumeration makeVirtualLockTable()
          Make a virtual lock table for diagnostics.
 void setLimit(CompatibilitySpace compatibilitySpace, java.lang.Object group, int limit, Limit callback)
          Install a limit that is called when the size of the group exceeds the required limit.
 void transfer(CompatibilitySpace compatibilitySpace, java.lang.Object oldGroup, java.lang.Object newGroup)
          Transfer a set of locks from one group to another.
 int unlock(CompatibilitySpace compatibilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier)
          Unlock a single lock on a single object held within this compatibility space and locked with the supplied qualifier.
 void unlockGroup(CompatibilitySpace compatibilitySpace, java.lang.Object group)
          Unlock all locks in a group.
 void unlockGroup(CompatibilitySpace compatibilitySpace, java.lang.Object group, Matchable key)
          Unlock all locks on a group that match the passed in value.
 boolean zeroDurationlockObject(CompatibilitySpace compatibilitySpace, Lockable ref, java.lang.Object qualifier, int timeout)
          Lock an object with zero duration within a compatibility space, waits up to timeout milli-seconds for the object to become unlocked.
 
Methods inherited from interface org.apache.derby.iapi.services.property.PropertySetCallback
apply, init, map, validate
 

Method Detail

createCompatibilitySpace

CompatibilitySpace createCompatibilitySpace(LockOwner owner)
Create an object which can be used as a compatibility space. A compatibility space object can only be used in the LockFactory that created it.

Parameters:
owner - the owner of the compatibility space (typically a transaction object). Might be null.
Returns:
an object which represents a compatibility space

lockObject

boolean lockObject(CompatibilitySpace compatibilitySpace,
                   java.lang.Object group,
                   Lockable ref,
                   java.lang.Object qualifier,
                   int timeout)
                   throws StandardException
Lock an object within a compatibility space and associate the lock with a group object, waits up to timeout milli-seconds for the object to become unlocked. A timeout of 0 means do not wait for the lock to be unlocked. Note the actual time waited is approximate.

A compatibility space in an space where lock requests are assumed to be compatible and granted by the lock manager if the trio {compatibilitySpace, ref, qualifier} are equal (i.e. reference equality for qualifier and compatibilitySpace, equals() method for ref). Granted by the lock manager means that the Lockable object may or may not be queried to see if the request is compatible.
A compatibility space is not assumed to be owned by a single thread.

Parameters:
compatibilitySpace - object defining compatibility space
group - handle of group, must be private to a thread.
ref - reference to object to be locked
qualifier - A qualification of the request.
timeout - the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
Returns:
true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock could not be granted.
Throws:
StandardException - A deadlock has occured (message id will be LockFactory.Deadlock)
StandardException - The wait for the lock timed out (message id will be LockFactory.TimeOut).
StandardException - Another thread interupted this thread while it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception, (message id will be LockFactory.InterruptedExceptionId)
StandardException - Standard Derby error policy.

unlock

int unlock(CompatibilitySpace compatibilitySpace,
           java.lang.Object group,
           Lockable ref,
           java.lang.Object qualifier)
Unlock a single lock on a single object held within this compatibility space and locked with the supplied qualifier.

Parameters:
compatibilitySpace - object defining compatibility space
group - handle of group.
ref - Reference to object to be unlocked.
qualifier - qualifier of lock to be unlocked
Returns:
number of locks released (one or zero).

unlockGroup

void unlockGroup(CompatibilitySpace compatibilitySpace,
                 java.lang.Object group)
Unlock all locks in a group.

Parameters:
compatibilitySpace - object defining compatibility space
group - handle of group that objects were locked with.

unlockGroup

void unlockGroup(CompatibilitySpace compatibilitySpace,
                 java.lang.Object group,
                 Matchable key)
Unlock all locks on a group that match the passed in value.


transfer

void transfer(CompatibilitySpace compatibilitySpace,
              java.lang.Object oldGroup,
              java.lang.Object newGroup)
Transfer a set of locks from one group to another.


anyoneBlocked

boolean anyoneBlocked()
Returns true if locks held by anyone are blocking anyone else


areLocksHeld

boolean areLocksHeld(CompatibilitySpace compatibilitySpace,
                     java.lang.Object group)
Return true if locks are held in this compatibility space and this group.

Parameters:
group - handle of group that objects were locked with.

areLocksHeld

boolean areLocksHeld(CompatibilitySpace compatibilitySpace)
Return true if locks are held in this compatibility space.


zeroDurationlockObject

boolean zeroDurationlockObject(CompatibilitySpace compatibilitySpace,
                               Lockable ref,
                               java.lang.Object qualifier,
                               int timeout)
                               throws StandardException
Lock an object with zero duration within a compatibility space, waits up to timeout milli-seconds for the object to become unlocked. A timeout of 0 means do not wait for the lock to be unlocked. Note the actual time waited is approximate.

Zero duration means the lock is released as soon as it is obtained.

A compatibility space in an space where lock requests are assumed to be compatible and granted by the lock manager if the trio {compatibilitySpace, ref, qualifier} are equal (i.e. reference equality for qualifier and compatibilitySpace, equals() method for ref). Granted by the lock manager means that the Lockable object may or may not be queried to see if the request is compatible.
A compatibility space is not assumed to be owned by a single thread.

Parameters:
compatibilitySpace - object defining compatibility space
ref - reference to object to be locked
qualifier - A qualification of the request.
timeout - the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
Returns:
true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock could not be granted.
Throws:
StandardException - A deadlock has occured (message id will be LockFactory.Deadlock)
StandardException - The wait for the lock timed out (message id will be LockFactory.TimeOut).
StandardException - Another thread interupted this thread while it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception, (message id will be LockFactory.InterruptedExceptionId)
StandardException - Standard Derby error policy.

isLockHeld

boolean isLockHeld(CompatibilitySpace compatibilitySpace,
                   java.lang.Object group,
                   Lockable ref,
                   java.lang.Object qualifier)
Check to see if a specific lock is held.


getWaitTimeout

int getWaitTimeout()
Get the lock timeout in milliseconds. A negative number means that there is no timeout.


setLimit

void setLimit(CompatibilitySpace compatibilitySpace,
              java.lang.Object group,
              int limit,
              Limit callback)
Install a limit that is called when the size of the group exceeds the required limit.
It is not guaranteed that the callback method (Limit.reached) is called as soon as the group size exceeds the given limit. If the callback method does not result in a decrease in the number of locks held then the lock factory implementation may delay calling the method again. E.g. with a limit of 500 and a reached() method that does nothing, may result in the call back method only being called when the group size reaches 550.
Only one limit may be in place for a group at any time.

See Also:
Limit

clearLimit

void clearLimit(CompatibilitySpace compatibilitySpace,
                java.lang.Object group)
Clear a limit set by setLimit.


makeVirtualLockTable

java.util.Enumeration makeVirtualLockTable()
Make a virtual lock table for diagnostics.


Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.