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

All Superinterfaces:
PropertySetCallback
All Known Implementing Classes:
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(java.lang.Object compatabilitySpace)
          Return true if locks are held in this compatability space.
 boolean areLocksHeld(java.lang.Object compatabilitySpace, java.lang.Object group)
          Return true if locks are held in this compatability space and this group.
 void clearLimit(java.lang.Object compatabilitySpace, java.lang.Object group)
          Clear a limit set by setLimit.
 boolean isLockHeld(java.lang.Object compatabilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier)
          Check to see if a specific lock is held.
 boolean latchObject(java.lang.Object compatabilitySpace, Lockable ref, java.lang.Object qualifier, int timeout)
          Latch an object.
 boolean lockObject(java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout, Latch latch)
          Lock an object within a compatability space and associate the lock with a group object, In addition a held latch is passed in.
 boolean lockObject(java.lang.Object compatabilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout)
          Lock an object within a compatability 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(java.lang.Object compatabilitySpace, 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(java.lang.Object compatabilitySpace, java.lang.Object oldGroup, java.lang.Object newGroup)
          Transfer a set of locks from one group to another.
 void unlatch(Latch heldLatch)
          Unlatch an object.
 int unlock(java.lang.Object compatabilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier)
          Unlock a single lock on a single object held within this compatability space that was locked with the supplied qualifier.
 void unlockGroup(java.lang.Object compatabilitySpace, java.lang.Object group)
          Unlock all locks in a group.
 void unlockGroup(java.lang.Object compatabilitySpace, java.lang.Object group, Matchable key)
          Unlock all locks on a group that match the passed in value.
 boolean zeroDurationlockObject(java.lang.Object compatabilitySpace, Lockable ref, java.lang.Object qualifier, int timeout)
          Lock an object with zero duration within a compatability 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

lockObject

public boolean lockObject(java.lang.Object compatabilitySpace,
                          java.lang.Object group,
                          Lockable ref,
                          java.lang.Object qualifier,
                          int timeout)
                   throws StandardException
Lock an object within a compatability 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 compatabile and granted by the lock manager if the trio {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality for qualifier, equals() method for compatabilitySpace and ref ). A typical reference to use for the compatability space is a reference to an object representing a transaction. Granted by the lock manager means that the Lockable object may or may not be queried to see if the request is compatible.
A compatability space is not assumed to be owned by a single thread.

Parameters:
compatabilitySpace - object defining compatability space (by value)
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 Cloudscape error policy.

lockObject

public boolean lockObject(java.lang.Object group,
                          Lockable ref,
                          java.lang.Object qualifier,
                          int timeout,
                          Latch latch)
                   throws StandardException
Lock an object within a compatability space and associate the lock with a group object, In addition a held latch is passed in. If the lock cannot be granted immediately, the latch will be released and relatched after the lock is obtained. If the lock can be granted immediately the latch is not released.
The compatability space of the request is defined by the compatability space of the latch.

Parameters:
group - handle of group, must be private to a compatability space.
ref - reference to object to be locked
qualifier - A qualification of the request.
timeout - amount of time to wait, NO_WAIT is not supported
latch - latch to be atomically released/re-latched in a wait.
Returns:
true if the latch was released, false otherwise.
Throws:
StandardException - A deadlock has occured (message id will be LockFactory.Deadlock)
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 Cloudscape error policy.

unlock

public int unlock(java.lang.Object compatabilitySpace,
                  java.lang.Object group,
                  Lockable ref,
                  java.lang.Object qualifier)
Unlock a single lock on a single object held within this compatability space that was locked with the supplied qualifier.

Parameters:
compatabilitySpace - object defining compatability space (by value)
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

public void unlockGroup(java.lang.Object compatabilitySpace,
                        java.lang.Object group)
Unlock all locks in a group.

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

unlockGroup

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


transfer

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


anyoneBlocked

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


areLocksHeld

public boolean areLocksHeld(java.lang.Object compatabilitySpace,
                            java.lang.Object group)
Return true if locks are held in this compatability space and this group.

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

areLocksHeld

public boolean areLocksHeld(java.lang.Object compatabilitySpace)
Return true if locks are held in this compatability space.


latchObject

public boolean latchObject(java.lang.Object compatabilitySpace,
                           Lockable ref,
                           java.lang.Object qualifier,
                           int timeout)
                    throws StandardException
Latch an object. A latch is a lock without a group. This means that it must be released explicitly by the owner. A latch is not released by any unlock methods, it must be released by the unlatch method. A latch is assumed to only be held by one locker at a time.
The first argument passed to lockEvent() is the Latch that is to be used in the unlatch() call. The firstArgument passed to unlockEvent() should be ignored.

Returns:
true if the latch 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 - Another thread interupted this thread while it was waiting for the latch. This will be a StandardException with a nested java.lang.InterruptedException exception, (message id will be LockFactory.InterruptedExceptionId)
StandardException - Standard Cloudscape error policy.

unlatch

public void unlatch(Latch heldLatch)
Unlatch an object.


zeroDurationlockObject

public boolean zeroDurationlockObject(java.lang.Object compatabilitySpace,
                                      Lockable ref,
                                      java.lang.Object qualifier,
                                      int timeout)
                               throws StandardException
Lock an object with zero duration within a compatability 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 compatabile and granted by the lock manager if the trio {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality for qualifier, equals() method for compatabilitySpace and ref ). A typical reference to use for the compatability space is a reference to an object representing a transaction. Granted by the lock manager means that the Lockable object may or may not be queried to see if the request is compatible.
A compatability space is not assumed to be owned by a single thread.

Parameters:
compatabilitySpace - object defining compatability space (by value)
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 Cloudscape error policy.

isLockHeld

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


setLimit

public void setLimit(java.lang.Object compatabilitySpace,
                     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

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


makeVirtualLockTable

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



Apache Derby V10.0 Engine Documentation - Copyright © 1997,2004 The Apache Software Foundation or its licensors, as applicable.