Package org.apache.manifoldcf.core.lockmanager

Class 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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String _rcsid  
      protected ILockManager lockManager
      Backing lock manager

    • Constructor Summary

      Constructors 
      Constructor Description
      LockManager()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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
      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.
      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[] 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.
      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.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • registerServiceBeginServiceActivity

        public 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.
        Specified by:
        registerServiceBeginServiceActivity in interface ILockManager
        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

        public 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.
        Specified by:
        registerServiceBeginServiceActivity in interface ILockManager
        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

        public void updateServiceData​(java.lang.String serviceType,
                              java.lang.String serviceName,
                              byte[] serviceData)
                       throws ManifoldCFException
        Set service data for a service.
        Specified by:
        updateServiceData in interface ILockManager
        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

        public byte[] retrieveServiceData​(java.lang.String serviceType,
                                  java.lang.String serviceName)
                           throws ManifoldCFException
        Retrieve service data for a service.
        Specified by:
        retrieveServiceData in interface ILockManager
        Parameters:
        serviceType - is the type of service.
        serviceName - is the name of the service.
        Returns:
        the service's transient data.
        Throws:
        ManifoldCFException

      • scanServiceData

        public void scanServiceData​(java.lang.String serviceType,
                            IServiceDataAcceptor dataAcceptor)
                     throws ManifoldCFException
        Scan service data for a service type. Only active service data will be considered.
        Specified by:
        scanServiceData in interface ILockManager
        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

      • cleanupInactiveService

        public 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.
        Specified by:
        cleanupInactiveService in interface ILockManager
        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

        public 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.
        Specified by:
        endServiceActivity in interface ILockManager
        Parameters:
        serviceType - is the type of service.
        serviceName - is the name of the service to exit.
        Throws:
        ManifoldCFException

      • checkServiceActive

        public 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.
        Specified by:
        checkServiceActive in interface ILockManager
        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

      • 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

      • 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

      • 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

      • 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