org.apache.manifoldcf.core.interfaces

Interface ILockManager

All Known Implementing Classes:

BaseLockManager, FileLockManager, LockManager, ZooKeeperLockManager

public interface ILockManager

The lock manager manages locks and shared data across all threads and JVMs and cluster members. It also manages transient shared data, which is not necessarily atomic and should be protected by locks.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	_rcsid

Method Summary

Modifier and Type	Method and Description
boolean	checkGlobalFlag(java.lang.String flagName) Check the condition of a specified flag.
boolean	checkServiceActive(java.lang.String serviceType, java.lang.String serviceName) Check whether a service is active or not.
boolean	cleanupInactiveService(java.lang.String serviceType, IServiceCleanup cleanup) Clean up any inactive services found.
void	clearGlobalFlag(java.lang.String flagName) Clear a flag.
void	clearLocks() Clear all outstanding locks in the system.
int	countActiveServices(java.lang.String serviceType) Count all active services of a given type.
void	endServiceActivity(java.lang.String serviceType, java.lang.String serviceName) End service activity.
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 simultaneously.
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 write critical section (NOT a lock).
void	enterWriteLock(java.lang.String lockKey) Enter a write locked code area (i.e., block out both readers and other writers).
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.
ManifoldCFConfiguration	getSharedConfiguration() Get the current shared configuration.
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[] nonExWriteLocks, 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 locked code area.
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 write critical section (NOT a lock).
void	leaveWriteLock(java.lang.String lockKey) Leave a write locked code area.
byte[]	readData(java.lang.String resourceName) Read data from a shared data resource.
java.lang.String	registerServiceBeginServiceActivity(java.lang.String serviceType, java.lang.String serviceName, byte[] initialData, IServiceCleanup cleanup) Register a service and begin service activity.
java.lang.String	registerServiceBeginServiceActivity(java.lang.String serviceType, java.lang.String serviceName, IServiceCleanup cleanup) Register a service and begin service activity.
byte[]	retrieveServiceData(java.lang.String serviceType, java.lang.String serviceName) Retrieve service data for a service.
void	scanServiceData(java.lang.String serviceType, IServiceDataAcceptor dataAcceptor) Scan service data for a service type.
void	setGlobalFlag(java.lang.String flagName) Raise a flag.
void	timedWait(int time) Wait for a time before retrying a lock.
void	updateServiceData(java.lang.String serviceType, java.lang.String serviceName, byte[] serviceData) Set service data for a service.
void	writeData(java.lang.String resourceName, byte[] data) Write data to a shared data resource.

Field Detail

_rcsid

static final java.lang.String _rcsid

See Also:

Constant Field Values

Method Detail

registerServiceBeginServiceActivity

java.lang.String registerServiceBeginServiceActivity(java.lang.String serviceType,
                                                     java.lang.String serviceName,
                                                     IServiceCleanup cleanup)
                                              throws ManifoldCFException

Register a service and begin service activity. This atomic operation creates a permanent registration entry for a service. If the permanent registration entry already exists, this method will not create it or treat it as an error. This operation also enters the "active" zone for the service. The "active" zone will remain in force until it is canceled, or until the process is interrupted. Ideally, the corresponding endServiceActivity method will be called when the service shuts down. Some ILockManager implementations require that this take place for proper management. If the transient registration already exists, it is treated as an error and an exception will be thrown. If registration will succeed, then this method may call an appropriate IServiceCleanup method to clean up either the current service, or all services on the cluster.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service to register. If null is passed, a transient unique service name will be created, and will be returned to the caller.

cleanup - is called to clean up either the current service, or all services of this type, if no other active service exists. May be null. Local service cleanup is never called if the serviceName argument is null.

Returns:

the actual service name.

Throws:

ManifoldCFException

registerServiceBeginServiceActivity

java.lang.String registerServiceBeginServiceActivity(java.lang.String serviceType,
                                                     java.lang.String serviceName,
                                                     byte[] initialData,
                                                     IServiceCleanup cleanup)
                                              throws ManifoldCFException

Register a service and begin service activity. This atomic operation creates a permanent registration entry for a service. If the permanent registration entry already exists, this method will not create it or treat it as an error. This operation also enters the "active" zone for the service. The "active" zone will remain in force until it is canceled, or until the process is interrupted. Ideally, the corresponding endServiceActivity method will be called when the service shuts down. Some ILockManager implementations require that this take place for proper management. If the transient registration already exists, it is treated as an error and an exception will be thrown. If registration will succeed, then this method may call an appropriate IServiceCleanup method to clean up either the current service, or all services on the cluster.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service to register. If null is passed, a transient unique service name will be created, and will be returned to the caller.

initialData - is the initial service data for this service.

cleanup - is called to clean up either the current service, or all services of this type, if no other active service exists. May be null. Local service cleanup is never called if the serviceName argument is null.

Returns:

the actual service name.

Throws:

ManifoldCFException

updateServiceData

void updateServiceData(java.lang.String serviceType,
                       java.lang.String serviceName,
                       byte[] serviceData)
                throws ManifoldCFException

Set service data for a service.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service.

serviceData - is the data to update to (may be null). This updates the service's transient data (or deletes it). If the service is not active, an exception is thrown.

Throws:

ManifoldCFException

retrieveServiceData

byte[] retrieveServiceData(java.lang.String serviceType,
                           java.lang.String serviceName)
                    throws ManifoldCFException

Retrieve service data for a service.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service.

Returns:

the service's transient data.

Throws:

ManifoldCFException

scanServiceData

void scanServiceData(java.lang.String serviceType,
                     IServiceDataAcceptor dataAcceptor)
              throws ManifoldCFException

Scan service data for a service type. Only active service data will be considered.

Parameters:

serviceType - is the type of service.

dataAcceptor - is the object that will be notified of each item of data for each service name found.

Throws:

ManifoldCFException

countActiveServices

int countActiveServices(java.lang.String serviceType)
                 throws ManifoldCFException

Count all active services of a given type.

Parameters:

serviceType - is the service type.

Returns:

the count.

Throws:

ManifoldCFException

cleanupInactiveService

boolean cleanupInactiveService(java.lang.String serviceType,
                               IServiceCleanup cleanup)
                        throws ManifoldCFException

Clean up any inactive services found. Calling this method will invoke cleanup of one inactive service at a time. If there are no inactive services around, then false will be returned. Note that this method will block whatever service it finds from starting up for the time the cleanup is proceeding. At the end of the cleanup, if successful, the service will be atomically unregistered.

Parameters:

serviceType - is the service type.

cleanup - is the object to call to clean up an inactive service.

Returns:

true if there were no cleanup operations necessary.

Throws:

ManifoldCFException

endServiceActivity

void endServiceActivity(java.lang.String serviceType,
                        java.lang.String serviceName)
                 throws ManifoldCFException

End service activity. This operation exits the "active" zone for the service. This must take place using the same ILockManager object that was used to registerServiceBeginServiceActivity() - which implies that it is the same thread.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service to exit.

Throws:

ManifoldCFException

checkServiceActive

boolean checkServiceActive(java.lang.String serviceType,
                           java.lang.String serviceName)
                    throws ManifoldCFException

Check whether a service is active or not. This operation returns true if the specified service is considered active at the moment. Once a service is not active anymore, it can only return to activity by calling beginServiceActivity() once more.

Parameters:

serviceType - is the type of service.

serviceName - is the name of the service to check on.

Returns:

true if the service is considered active.

Throws:

ManifoldCFException

getSharedConfiguration

ManifoldCFConfiguration getSharedConfiguration()
                                        throws ManifoldCFException

Get the current shared configuration. This configuration is available in common among all nodes, and thus must not be accessed through here for the purpose of finding configuration data that is specific to any one specific node.

Throws:

ManifoldCFException

setGlobalFlag

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.

Parameters:

flagName - is the name of the flag to set.

Throws:

ManifoldCFException

clearGlobalFlag

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

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

Parameters:

flagName - is the name of the flag to clear.

Throws:

ManifoldCFException

checkGlobalFlag

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

Check the condition of a specified flag.

Parameters:

flagName - is the name of the flag to check.

Returns:

true if the flag is set, false otherwise.

Throws:

ManifoldCFException

readData

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.

Parameters:

resourceName - is the global name of the resource.

Returns:

a byte array containing the data, or null.

Throws:

ManifoldCFException

writeData

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.

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

void timedWait(int time)
        throws ManifoldCFException

Wait for a time before retrying a lock. Use this method to wait after a LockException has been thrown. )If this is not done, the application will wind up busy waiting.)

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

enterWriteLock

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

Enter a write locked code area (i.e., block out both readers and other writers). Write locks permit only ONE thread to be in the named section, across JVM's as well. In order to guarantee this, the current thread may wait until all other threads have left the section.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterWriteLockNoWait

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

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.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveWriteLock

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

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.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterNonExWriteLock

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). This method works across JVMs, and may wait if the required lock cannot be immediately obtained.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterNonExWriteLockNoWait

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

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.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveNonExWriteLock

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

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

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterReadLock

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

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 may wait if the required lock cannot be immediately obtained.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterReadLockNoWait

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

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.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

LockException

leaveReadLock

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

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.

Parameters:

lockKey - is the name of the lock.

Throws:

ManifoldCFException

enterLocks

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

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 wait if the required locks are not available.

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

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

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.

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

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

Leave multiple locks. Use this method to leave a section started with enterLocks() or enterLocksNoWait(). The parameters must correspond to those passed to the enter method.

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

clearLocks

void clearLocks()
         throws ManifoldCFException

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

Throws:

ManifoldCFException

enterReadCriticalSection

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.

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

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.

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

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.

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

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.

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

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

Enter a named, 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.

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

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

Leave a named, 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.

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

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

Enter multiple critical sections simultaneously.

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

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

Leave multiple critical sections simultaneously.

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