org.apache.derby.impl.services.locks
Class SinglePool

java.lang.Object
  extended byjava.util.Dictionary
      extended byjava.util.Hashtable
          extended byorg.apache.derby.impl.services.locks.SinglePool
All Implemented Interfaces:
java.lang.Cloneable, LockFactory, java.util.Map, PropertySetCallback, java.io.Serializable

public class SinglePool
extends java.util.Hashtable
implements LockFactory

An implementation of LockFactory that uses a single pool for the locks, i.e. all lock requests go through a single point of synchronisation.

The default concrete class "SinglePool.java", prints nothing and thus incurs no overhead associated with the code to dump lock information. An alternate concrete class "LockDebug/TracingSinglePool.java", attempts to output only lock information that "makes sense" to a user - for instance it doesn't print latch locks.
MT - Mutable - Container Object : Thread Aware

See Also:
Serialized Form

Nested Class Summary
 
Nested classes inherited from class java.util.Hashtable
 
Field Summary
(package private)  int deadlockMonitor
          True if all deadlocks errors should be logged.
protected  LockSet lockTable
          The complete set of locks in the system
MT - immutable - content dynamic : LockSet is ThreadSafe
 
Fields inherited from class java.util.Hashtable
 
Constructor Summary
SinglePool()
           
 
Method Summary
 boolean anyoneBlocked()
          Returns true if locks by anyone are blocking anyone else
 Serviceable apply(java.lang.String key, java.io.Serializable value, java.util.Dictionary p)
          Apply a property change.
 boolean areLocksHeld(java.lang.Object compatabilitySpace)
          Return true if locks are held in this space
MT - thread safe
 boolean areLocksHeld(java.lang.Object compatabilitySpace, java.lang.Object group)
          Return true if locks are held in this group and this space.
 void clearLimit(java.lang.Object compatabilitySpace, java.lang.Object group)
          Clear a limit set by setLimit.
private  void getAndApply(boolean dbOnly, java.util.Dictionary p, java.lang.String key)
           
private static int getWaitValue(java.lang.String value, int defaultValue)
           
 void init(boolean dbOnly, java.util.Dictionary p)
          Initialize the properties for this callback.
 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 a specific object with a timeout.
protected  Lock lockAnObject(java.lang.Object compatabilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout, Latch heldLatch)
          Lock a specific object with a timeout.
 boolean lockObject(java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout, Latch latch)
          Lock a specific object while holding a latch
MT - thread safe
 boolean lockObject(java.lang.Object compatabilitySpace, java.lang.Object group, Lockable ref, java.lang.Object qualifier, int timeout)
          Lock a specific object
MT - thread safe
 java.util.Enumeration makeVirtualLockTable()
          Routines to support lock diagnostics VTIs for the benefit of VirtualLockTable
 java.io.Serializable map(java.lang.String key, java.io.Serializable value, java.util.Dictionary p)
          Map a proposed new value for a property to an official value.
 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.
 java.lang.String toDebugString()
           
 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 specific object
MT - thread safe
 void unlockGroup(java.lang.Object compatabilitySpace, java.lang.Object group)
          Unlock a group of objects.
 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 validate(java.lang.String key, java.io.Serializable value, java.util.Dictionary p)
          Validate a property change.
 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 class java.util.Hashtable
clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

lockTable

protected final LockSet lockTable
The complete set of locks in the system
MT - immutable - content dynamic : LockSet is ThreadSafe


deadlockMonitor

int deadlockMonitor
True if all deadlocks errors should be logged.

Constructor Detail

SinglePool

public SinglePool()
Method Detail

latchObject

public boolean latchObject(java.lang.Object compatabilitySpace,
                           Lockable ref,
                           java.lang.Object qualifier,
                           int timeout)
                    throws StandardException
Latch a specific object with a timeout.
MT - thread safe

Specified by:
latchObject in interface LockFactory
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 - Standard Cloudscape error policy
See Also:
LockFactory.latchObject(java.lang.Object, org.apache.derby.iapi.services.locks.Lockable, java.lang.Object, int)

unlatch

public void unlatch(Latch heldLatch)
Unlatch an object.
MT - thread safe

Specified by:
unlatch in interface LockFactory
See Also:
LockFactory.unlatch(org.apache.derby.iapi.services.locks.Latch)

lockAnObject

protected Lock lockAnObject(java.lang.Object compatabilitySpace,
                            java.lang.Object group,
                            Lockable ref,
                            java.lang.Object qualifier,
                            int timeout,
                            Latch heldLatch)
                     throws StandardException
Lock a specific object with a timeout.
MT - thread safe

Throws:
StandardException - Standard Cloudscape error policy
See Also:
LockFactory.lockObject(java.lang.Object, java.lang.Object, org.apache.derby.iapi.services.locks.Lockable, java.lang.Object, int)

lockObject

public boolean lockObject(java.lang.Object compatabilitySpace,
                          java.lang.Object group,
                          Lockable ref,
                          java.lang.Object qualifier,
                          int timeout)
                   throws StandardException
Lock a specific object
MT - thread safe

Specified by:
lockObject in interface LockFactory
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 - Standard Cloudscape error policy
See Also:
LockFactory.lockObject(java.lang.Object, java.lang.Object, org.apache.derby.iapi.services.locks.Lockable, java.lang.Object, int)

lockObject

public boolean lockObject(java.lang.Object group,
                          Lockable ref,
                          java.lang.Object qualifier,
                          int timeout,
                          Latch latch)
                   throws StandardException
Lock a specific object while holding a latch
MT - thread safe

Specified by:
lockObject in interface LockFactory
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 - Standard Cloudscape error policy
See Also:
LockFactory.lockObject(java.lang.Object, java.lang.Object, org.apache.derby.iapi.services.locks.Lockable, java.lang.Object, int)

unlock

public int unlock(java.lang.Object compatabilitySpace,
                  java.lang.Object group,
                  Lockable ref,
                  java.lang.Object qualifier)
Unlock a specific object
MT - thread safe

Specified by:
unlock in interface LockFactory
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).
See Also:
LockFactory.unlock(java.lang.Object, java.lang.Object, org.apache.derby.iapi.services.locks.Lockable, java.lang.Object)

unlockGroup

public void unlockGroup(java.lang.Object compatabilitySpace,
                        java.lang.Object group)
Unlock a group of objects.
MT - thread safe

Specified by:
unlockGroup in interface LockFactory
Parameters:
group - handle of group that objects were locked with. If group is null then this call is equivilent to unlockAll().
See Also:
LockFactory.unlockGroup(java.lang.Object, java.lang.Object)

unlockGroup

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

Specified by:
unlockGroup in interface LockFactory

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.
MT - thread safe

Specified by:
transfer in interface LockFactory
See Also:
LockFactory.transfer(java.lang.Object, java.lang.Object, java.lang.Object)

anyoneBlocked

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

Specified by:
anyoneBlocked in interface LockFactory

areLocksHeld

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

Specified by:
areLocksHeld in interface LockFactory
Parameters:
group - handle of group that objects were locked with.
See Also:
LockFactory.areLocksHeld(java.lang.Object, java.lang.Object)

areLocksHeld

public boolean areLocksHeld(java.lang.Object compatabilitySpace)
Return true if locks are held in this space
MT - thread safe

Specified by:
areLocksHeld in interface LockFactory
See Also:
LockFactory.areLocksHeld(java.lang.Object, java.lang.Object)

zeroDurationlockObject

public boolean zeroDurationlockObject(java.lang.Object compatabilitySpace,
                                      Lockable ref,
                                      java.lang.Object qualifier,
                                      int timeout)
                               throws StandardException
Description copied from interface: LockFactory
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.

Specified by:
zeroDurationlockObject in interface LockFactory
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 - 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)

isLockHeld

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

Specified by:
isLockHeld in interface LockFactory

setLimit

public void setLimit(java.lang.Object compatabilitySpace,
                     java.lang.Object group,
                     int limit,
                     Limit callback)
Description copied from interface: LockFactory
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.

Specified by:
setLimit in interface LockFactory
See Also:
Limit

clearLimit

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

Specified by:
clearLimit in interface LockFactory

makeVirtualLockTable

public java.util.Enumeration makeVirtualLockTable()
Routines to support lock diagnostics VTIs for the benefit of VirtualLockTable

Specified by:
makeVirtualLockTable in interface LockFactory

toDebugString

public java.lang.String toDebugString()

init

public void init(boolean dbOnly,
                 java.util.Dictionary p)
Description copied from interface: PropertySetCallback
Initialize the properties for this callback. Called when addPropertySetNotification() is called with a non-null transaction controller. This allows code to set read its initial property values at boot time.

Code within an init() method should use the 3 argument PropertyUtil method getPropertyFromSet() to obtain a property's value.

Specified by:
init in interface PropertySetCallback
Parameters:
dbOnly - true if only per-database properties are to be looked at
p - the complete set of per-database properties.

getAndApply

private void getAndApply(boolean dbOnly,
                         java.util.Dictionary p,
                         java.lang.String key)

validate

public boolean validate(java.lang.String key,
                        java.io.Serializable value,
                        java.util.Dictionary p)
                 throws StandardException
Description copied from interface: PropertySetCallback
Validate a property change.

Specified by:
validate in interface PropertySetCallback
Parameters:
key - Property key for the property being set
value - proposed new value for the property being set or null if the property is being dropped.
p - Property set before the change. SettingProperty may read but must never change p.
Returns:
true if this object was interested in this property, false otherwise.
Throws:
StandardException - Oh well.

apply

public Serviceable apply(java.lang.String key,
                         java.io.Serializable value,
                         java.util.Dictionary p)
                  throws StandardException
Description copied from interface: PropertySetCallback
Apply a property change. Will only be called after validate has been called and only if validate returned true. If this method is called then the new value is the value to be used, ie. the property is not set in the overriding JVM system set.

Specified by:
apply in interface PropertySetCallback
Parameters:
key - Property key for the property being set
value - proposed new value for the property being set or null if the property is being dropped.
p - Property set before the change. SettingProperty may read but must never change p.
Returns:
post commit work for the property change.
Throws:
StandardException - Oh well.

map

public java.io.Serializable map(java.lang.String key,
                                java.io.Serializable value,
                                java.util.Dictionary p)
Description copied from interface: PropertySetCallback
Map a proposed new value for a property to an official value. Will only be called after apply() has been called.

Specified by:
map in interface PropertySetCallback
Parameters:
key - Property key for the property being set
value - proposed new value for the property being set or null if the property is being dropped.
p - Property set before the change. SettingProperty may read but must never change p.
Returns:
new value for the change

getWaitValue

private static int getWaitValue(java.lang.String value,
                                int defaultValue)

Built on Mon 2007-06-04 09:58:47+0400, from revision ???

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