org.apache.manifoldcf.core.lockmanager
Class LockManager

java.lang.Object
  org.apache.manifoldcf.core.lockmanager.LockManager

All Implemented Interfaces:

ILockManager

public class LockManager
extends java.lang.Object
implements ILockManager

The lock manager manages locks across all threads and JVMs and cluster members. There should be no more than ONE instance of this class per thread!!! The factory should enforce this.

Nested Class Summary

protected static class	LockManager.ByteArrayBuffer
protected class	LockManager.LocalLock
protected class	LockManager.LockDescription

Field Summary

static java.lang.String	_rcsid
protected static int	BASE_SIZE
protected static java.util.HashMap	globalData Global resource data.
protected static java.util.HashMap	globalFlags Global flag information.
protected java.util.HashMap	localLocks
protected java.util.HashMap	localSections
protected static LockPool	myLocks
protected static LockPool	mySections
protected java.io.File	synchDirectory
static java.lang.String	synchDirectoryProperty Synchronization directory property - local to this implementation of ILockManager
protected static int	TYPE_READ
protected static int	TYPE_WRITE
protected static int	TYPE_WRITENONEX

Constructor Summary

LockManager()

Method Summary

boolean	checkGlobalFlag(java.lang.String flagName) Check the condition of a specified flag.
void	clearGlobalFlag(java.lang.String flagName) Clear a flag.
void	clearLocks() Clear all outstanding locks in the system.
void	enterCriticalSections(java.lang.String[] readSectionKeys, java.lang.String[] nonExSectionKeys, java.lang.String[] writeSectionKeys) Enter multiple critical sections simultaneously.
void	enterLocks(java.lang.String[] readLocks, java.lang.String[] nonExWriteLocks, java.lang.String[] writeLocks) Enter multiple locks
void	enterLocksNoWait(java.lang.String[] readLocks, java.lang.String[] nonExWriteLocks, java.lang.String[] writeLocks) Enter multiple locks simultaneously.
void	enterNonExWriteCriticalSection(java.lang.String sectionKey) Enter a named, non-exclusive write critical section (NOT a lock).
void	enterNonExWriteLock(java.lang.String lockKey) Enter a non-exclusive write-locked area (blocking out all readers, but letting in other "writers").
void	enterNonExWriteLockNoWait(java.lang.String lockKey) Enter a non-exclusive write-locked area (blocking out all readers, but letting in other "writers").
void	enterReadCriticalSection(java.lang.String sectionKey) Enter a named, read critical section (NOT a lock).
void	enterReadLock(java.lang.String lockKey) Enter a read-only locked area (i.e., block ONLY if there's a writer)
void	enterReadLockNoWait(java.lang.String lockKey) Enter a read-only locked area (i.e., block ONLY if there's a writer).
void	enterWriteCriticalSection(java.lang.String sectionKey) Enter a named, exclusive critical section (NOT a lock).
void	enterWriteLock(java.lang.String lockKey) Enter a write locked area (i.e., block out both readers and other writers) NOTE: Can't enter until all readers have left.
void	enterWriteLockNoWait(java.lang.String lockKey) Enter a write locked code area (i.e., block out both readers and other writers), but do not wait if the lock cannot be obtained.
protected static java.lang.String	getFlagResourceName(java.lang.String flagName) Calculate the name of a flag resource.
protected LockManager.LocalLock	getLocalLock(java.lang.String lockKey)
protected LockManager.LocalLock	getLocalSection(java.lang.String sectionKey)
protected LockManager.LockDescription[]	getSortedUniqueLocks(java.lang.String[] readLocks, java.lang.String[] writeNonExLocks, java.lang.String[] writeLocks) Process inbound locks into a sorted vector of most-restrictive unique locks
void	leaveCriticalSections(java.lang.String[] readSectionKeys, java.lang.String[] nonExSectionKeys, java.lang.String[] writeSectionKeys) Leave multiple critical sections simultaneously.
void	leaveLocks(java.lang.String[] readLocks, java.lang.String[] writeNonExLocks, java.lang.String[] writeLocks) Leave multiple locks
void	leaveNonExWriteCriticalSection(java.lang.String sectionKey) Leave a named, non-exclusive write critical section (NOT a lock).
void	leaveNonExWriteLock(java.lang.String lockKey) Leave a non-exclusive write lock.
void	leaveReadCriticalSection(java.lang.String sectionKey) Leave a named, read critical section (NOT a lock).
void	leaveReadLock(java.lang.String lockKey) Leave a read-locked code area.
void	leaveWriteCriticalSection(java.lang.String sectionKey) Leave a named, exclusive critical section (NOT a lock).
void	leaveWriteLock(java.lang.String lockKey) Leave a write locked code area.
protected java.lang.String	makeFilePath(java.lang.String key) Create a file path given a key name.
byte[]	readData(java.lang.String resourceName) Read data from a shared data resource.
protected void	releaseLocalLock(java.lang.String lockKey)
protected void	releaseLocalSection(java.lang.String sectionKey)
void	setGlobalFlag(java.lang.String flagName) Raise a flag.
void	timedWait(int time) Wait for a time before retrying a lock.
void	writeData(java.lang.String resourceName, byte[] data) Write data to a shared data resource.

Methods inherited from class java.lang.Object

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

Field Detail

_rcsid

public static final java.lang.String _rcsid

See Also:

Constant Field Values

synchDirectoryProperty

public static final java.lang.String synchDirectoryProperty

Synchronization directory property - local to this implementation of ILockManager

See Also:

Constant Field Values

TYPE_READ

protected static final int TYPE_READ

See Also:

Constant Field Values

TYPE_WRITENONEX

protected static final int TYPE_WRITENONEX

See Also:

Constant Field Values

TYPE_WRITE

protected static final int TYPE_WRITE

See Also:

Constant Field Values

localLocks

protected java.util.HashMap localLocks

myLocks

protected static LockPool myLocks

localSections

protected java.util.HashMap localSections

mySections

protected static LockPool mySections

synchDirectory

protected java.io.File synchDirectory

globalFlags

protected static java.util.HashMap globalFlags

Global flag information. This is used only when all of ManifoldCF is run within one process.

globalData

protected static java.util.HashMap globalData

Global resource data. Used only when ManifoldCF is run entirely out of one process.

BASE_SIZE

protected static final int BASE_SIZE

See Also:

Constant Field Values

Constructor Detail

LockManager

public LockManager()
            throws ManifoldCFException

Throws:

ManifoldCFException

Method Detail

getFlagResourceName

protected static java.lang.String getFlagResourceName(java.lang.String flagName)

Calculate the name of a flag resource.

Parameters:

flagName - is the name of the flag.

Returns:

the name for the flag resource.

setGlobalFlag

public void setGlobalFlag(java.lang.String flagName)
                   throws ManifoldCFException

Raise a flag. Use this method to assert a condition, or send a global signal. The flag will be reset when the entire system is restarted.

Specified by:

setGlobalFlag in interface ILockManager

Parameters:

flagName - is the name of the flag to set.

Throws:

ManifoldCFException

clearGlobalFlag

public void clearGlobalFlag(java.lang.String flagName)
                     throws ManifoldCFException

Clear a flag. Use this method to clear a condition, or retract a global signal.

Specified by:

clearGlobalFlag in interface ILockManager

Parameters:

flagName - is the name of the flag to clear.

Throws:

ManifoldCFException

checkGlobalFlag

public boolean checkGlobalFlag(java.lang.String flagName)
                        throws ManifoldCFException

Check the condition of a specified flag.

Specified by:

checkGlobalFlag in interface ILockManager

Parameters:

flagName - is the name of the flag to check.

Returns:

true if the flag is set, false otherwise.

Throws:

ManifoldCFException

readData

public byte[] readData(java.lang.String resourceName)
                throws ManifoldCFException

Read data from a shared data resource. Use this method to read any existing data, or get a null back if there is no such resource. Note well that this is not necessarily an atomic operation, and it must thus be protected by a lock.

Specified by:

readData in interface ILockManager

Parameters:

resourceName - is the global name of the resource.

Returns:

a byte array containing the data, or null.

Throws:

ManifoldCFException

writeData

public void writeData(java.lang.String resourceName,
                      byte[] data)
               throws ManifoldCFException

Write data to a shared data resource. Use this method to write a body of data into a shared resource. Note well that this is not necessarily an atomic operation, and it must thus be protected by a lock.

Specified by:

writeData in interface ILockManager

Parameters:

resourceName - is the global name of the resource.

data - is the byte array containing the data. Pass null if you want to delete the resource completely.

Throws:

ManifoldCFException

timedWait

public void timedWait(int time)
               throws ManifoldCFException

Wait for a time before retrying a lock.

Specified by:

timedWait in interface ILockManager

Parameters:

time - is the amount of time to wait, in milliseconds. Zero is a legal value, and will wait no time, but will give up the current timeslice to another thread.

Throws:

ManifoldCFException

enterNonExWriteLock

public void enterNonExWriteLock(java.lang.String lockKey)
                         throws ManifoldCFException

Enter a non-exclusive write-locked area (blocking out all readers, but letting in other "writers"). This kind of lock is designed to be used in conjunction with read locks. It is used typically in a situation where the read lock represents a query and the non-exclusive write lock represents a modification to an individual item that might affect the query, but where multiple modifications do not individually interfere with one another (use of another, standard, write lock per item can guarantee this).

Specified by:

enterNonExWriteLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterNonExWriteLockNoWait

public void enterNonExWriteLockNoWait(java.lang.String lockKey)
                               throws ManifoldCFException,
                                      LockException

Description copied from interface: ILockManager

Enter a non-exclusive write-locked area (blocking out all readers, but letting in other "writers"). This kind of lock is designed to be used in conjunction with read locks. It is used typically in a situation where the read lock represents a query and the non-exclusive write lock represents a modification to an individual item that might affect the query, but where multiple modifications do not individually interfere with one another (use of another, standard, write lock per item can guarantee this). This method works across JVMs, and will throw LockException if the lock condition cannot be immediately met.

Specified by:

enterNonExWriteLockNoWait in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveNonExWriteLock

public void leaveNonExWriteLock(java.lang.String lockKey)
                         throws ManifoldCFException

Leave a non-exclusive write lock.

Specified by:

leaveNonExWriteLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterWriteLock

public void enterWriteLock(java.lang.String lockKey)
                    throws ManifoldCFException

Enter a write locked area (i.e., block out both readers and other writers) NOTE: Can't enter until all readers have left.

Specified by:

enterWriteLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterWriteLockNoWait

public void enterWriteLockNoWait(java.lang.String lockKey)
                          throws ManifoldCFException,
                                 LockException

Description copied from interface: ILockManager

Enter a write locked code area (i.e., block out both readers and other writers), but do not wait if the lock cannot be obtained. Write locks permit only ONE thread to be in the named section, across JVM's as well. In order to guarantee this, an exception (LockException) will be thrown if the lock condition cannot be met immediately.

Specified by:

enterWriteLockNoWait in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveWriteLock

public void leaveWriteLock(java.lang.String lockKey)
                    throws ManifoldCFException

Description copied from interface: ILockManager

Leave a write locked code area. Use this method to exit a write-locked section. The lockKey parameter must correspond to the key used for the enter method.

Specified by:

leaveWriteLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterReadLock

public void enterReadLock(java.lang.String lockKey)
                   throws ManifoldCFException

Enter a read-only locked area (i.e., block ONLY if there's a writer)

Specified by:

enterReadLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterReadLockNoWait

public void enterReadLockNoWait(java.lang.String lockKey)
                         throws ManifoldCFException,
                                LockException

Description copied from interface: ILockManager

Enter a read-only locked area (i.e., block ONLY if there's a writer). This kind of lock permits multiple threads inside the same code area, but only if there is no "writer" in the same section at the same time. This method works across JVMs, and will throw LockException if the required lock cannot be immediately met.

Specified by:

enterReadLockNoWait in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveReadLock

public void leaveReadLock(java.lang.String lockKey)
                   throws ManifoldCFException

Description copied from interface: ILockManager

Leave a read-locked code area. Use this method to exit a read-locked section. The lockKey parameter must correspond to the key used for the enter method.

Specified by:

leaveReadLock in interface ILockManager

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

clearLocks

public void clearLocks()
                throws ManifoldCFException

Description copied from interface: ILockManager

Clear all outstanding locks in the system. This is a very dangerous method to use (obviously)...

Specified by:

clearLocks in interface ILockManager

Throws:

ManifoldCFException

enterLocks

public void enterLocks(java.lang.String[] readLocks,
                       java.lang.String[] nonExWriteLocks,
                       java.lang.String[] writeLocks)
                throws ManifoldCFException

Enter multiple locks

Specified by:

enterLocks in interface ILockManager

Parameters:

readLocks - is an array of read lock names, or null if there are no read locks desired.

nonExWriteLocks - is an array of non-ex write lock names, or null if none desired.

writeLocks - is an array of write lock names, or null if there are none desired.

Throws:

ManifoldCFException

enterLocksNoWait

public void enterLocksNoWait(java.lang.String[] readLocks,
                             java.lang.String[] nonExWriteLocks,
                             java.lang.String[] writeLocks)
                      throws ManifoldCFException,
                             LockException

Description copied from interface: ILockManager

Enter multiple locks simultaneously. Use this method if a series or set of locks needs to be thrown for an operation to take place. This operation will avoid deadlock if all the locks are thrown at the start of the area using this method. This method works cross-JVM, and will throw LockException if the required locks are not available.

Specified by:

enterLocksNoWait in interface ILockManager

Parameters:

readLocks - is an array of read lock names, or null if there are no read locks desired.

nonExWriteLocks - is an array of non-ex write lock names, or null if none desired.

writeLocks - is an array of write lock names, or null if there are none desired.

Throws:

ManifoldCFException

LockException

leaveLocks

public void leaveLocks(java.lang.String[] readLocks,
                       java.lang.String[] writeNonExLocks,
                       java.lang.String[] writeLocks)
                throws ManifoldCFException

Leave multiple locks

Specified by:

leaveLocks in interface ILockManager

Parameters:

readLocks - is an array of read lock names, or null if there are no read locks desired.

writeNonExLocks - is an array of non-ex write lock names, or null if none desired.

writeLocks - is an array of write lock names, or null if there are none desired.

Throws:

ManifoldCFException

enterReadCriticalSection

public void enterReadCriticalSection(java.lang.String sectionKey)
                              throws ManifoldCFException

Enter a named, read critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names do not collide with lock names; they have a distinct namespace.

Specified by:

enterReadCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to enter. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

leaveReadCriticalSection

public void leaveReadCriticalSection(java.lang.String sectionKey)
                              throws ManifoldCFException

Leave a named, read critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names do not collide with lock names; they have a distinct namespace.

Specified by:

leaveReadCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to leave. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

enterNonExWriteCriticalSection

public void enterNonExWriteCriticalSection(java.lang.String sectionKey)
                                    throws ManifoldCFException

Enter a named, non-exclusive write critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names do not collide with lock names; they have a distinct namespace.

Specified by:

enterNonExWriteCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to enter. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

leaveNonExWriteCriticalSection

public void leaveNonExWriteCriticalSection(java.lang.String sectionKey)
                                    throws ManifoldCFException

Leave a named, non-exclusive write critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names do not collide with lock names; they have a distinct namespace.

Specified by:

leaveNonExWriteCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to leave. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

enterWriteCriticalSection

public void enterWriteCriticalSection(java.lang.String sectionKey)
                               throws ManifoldCFException

Enter a named, exclusive critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names should be distinct from all lock names.

Specified by:

enterWriteCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to enter. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

leaveWriteCriticalSection

public void leaveWriteCriticalSection(java.lang.String sectionKey)
                               throws ManifoldCFException

Leave a named, exclusive critical section (NOT a lock). Critical sections never cross JVM boundaries. Critical section names should be distinct from all lock names.

Specified by:

leaveWriteCriticalSection in interface ILockManager

Parameters:

sectionKey - is the name of the section to leave. Only one thread can be in any given named section at a time.

Throws:

ManifoldCFException

enterCriticalSections

public void enterCriticalSections(java.lang.String[] readSectionKeys,
                                  java.lang.String[] nonExSectionKeys,
                                  java.lang.String[] writeSectionKeys)
                           throws ManifoldCFException

Enter multiple critical sections simultaneously.

Specified by:

enterCriticalSections in interface ILockManager

Parameters:

readSectionKeys - is an array of read section descriptors, or null if there are no read sections desired.

nonExSectionKeys - is an array of non-ex write section descriptors, or null if none desired.

writeSectionKeys - is an array of write section descriptors, or null if there are none desired.

Throws:

ManifoldCFException

leaveCriticalSections

public void leaveCriticalSections(java.lang.String[] readSectionKeys,
                                  java.lang.String[] nonExSectionKeys,
                                  java.lang.String[] writeSectionKeys)
                           throws ManifoldCFException

Leave multiple critical sections simultaneously.

Specified by:

leaveCriticalSections in interface ILockManager

Parameters:

readSectionKeys - is an array of read section descriptors, or null if there are no read sections desired.

nonExSectionKeys - is an array of non-ex write section descriptors, or null if none desired.

writeSectionKeys - is an array of write section descriptors, or null if there are none desired.

Throws:

ManifoldCFException

getLocalLock

protected LockManager.LocalLock getLocalLock(java.lang.String lockKey)

releaseLocalLock

protected void releaseLocalLock(java.lang.String lockKey)

getLocalSection

protected LockManager.LocalLock getLocalSection(java.lang.String sectionKey)

releaseLocalSection

protected void releaseLocalSection(java.lang.String sectionKey)

getSortedUniqueLocks

protected LockManager.LockDescription[] getSortedUniqueLocks(java.lang.String[] readLocks,
                                                             java.lang.String[] writeNonExLocks,
                                                             java.lang.String[] writeLocks)

Process inbound locks into a sorted vector of most-restrictive unique locks

makeFilePath

protected java.lang.String makeFilePath(java.lang.String key)

Create a file path given a key name.

Parameters:

key - is the key name.

Returns:

the file path.