Interface Lockable

  • All Known Subinterfaces:
    RecordHandle
    All Known Implementing Classes:
    BaseContainer, CacheLock, ClassLoaderLock, ContainerKey, FileContainer, InputStreamContainer, RAFContainer, RAFContainer4, RecordId, ShExLockable, TempRAFContainer

    public interface Lockable
    Any object that needs to be locked must implement Lockable. This allows a generic lock manager that can have locking policies defined on a per-object basis. A request to lock the object takes a qualifier, this qualifier may be used the object to implement a complex locking policy, e.g. traditional database shared, update and exclusive locks.

    The lock manager uses this ordered protocol to determine if a lock request on a Lockable L with qualifier Q1 in compatibility space CS1 can be granted:

    1. If no locks are held on L in any compatability space then the request is granted.
    2. If L.requestCompatible(Q1) returns true then the lock is granted.
    3. Otherwise the request is granted if the following expression evaluates to true for every other lock { CSn, Qn} held on L
      •     ( ( CSn == CS1 ) && L.lockerAlwaysCompatible() ) 
      •  || (L.reqestCompatible(Q1, Qn)) 

    If the request is granted then a call is made to L.lockEvent(CS1, Q1) .
    When the lock is released a call is made to L.unlockEvent(CS1, Q1) .

    The lock manager uses equals() and hashCode() to identify unique Lockables.
    If the class implementing Lockable requires that each instance of class correspond to a different locked object then the equals() method must test equality via the reference equality test (==), this is the default behaviour for equality.
    If the class implementing Lockable require that each instance of the class that has the same value (as defined by the class) corresponds to a locked object then its equals() method must reflect that, e.g. by testing equality of its fields. In this case the first Lockable to be locked will be kept by lock manager as the key for the lock. Thus even after the first caller unlocks the object, its reference will still be kept by the lock manager. Thus Lockable's that per value equality must be designed so that they are never re-used for different lockable concepts.
    In either case the equals() method must accept a reference to an object of a different type.
    As per standard hashtable rules the value returned by hashCode() must be in sync with the equals() method.
    MT - Mutable - : single thread required, synchronization is provided by the lock manager. If the class implementing Lockable uses value equality then it must have an immutable identity.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean lockAttributes​(int flag, java.util.Hashtable<java.lang.String,​java.lang.Object> attributes)
      If this lockable object wants to participate in a diagnostic virtual lock table, then put any relevant attributes of this lock into the attributes list (the attribute must be an immutable object).
      boolean lockerAlwaysCompatible()
      Returns true if any lock request on a Lockable L in a compatibility space CS1 is compatible with any other lock held on L in CS1.
      void lockEvent​(Latch lockInfo)
      Note the fact the object is locked.
      boolean requestCompatible​(java.lang.Object requestedQualifier, java.lang.Object grantedQualifier)
      Return true if the requested qualifier is compatible with the already granted qualifier.
      void unlockEvent​(Latch lockInfo)
      Note that the object has been unlocked
    • Method Detail

      • lockEvent

        void lockEvent​(Latch lockInfo)
        Note the fact the object is locked. Performs required actions to ensure that unlockEvent() work correctly. This method does not actually perform any locking of the object, the locking mechanism is provided by the lock manager.

        If the class supports multiple lockers of the object then this method will be called once per locker, each with their own qualifier.

        Must only be called by the lock manager. Synchronization will be handled by the lock manager.

      • requestCompatible

        boolean requestCompatible​(java.lang.Object requestedQualifier,
                                  java.lang.Object grantedQualifier)
        Return true if the requested qualifier is compatible with the already granted qualifier.
      • lockerAlwaysCompatible

        boolean lockerAlwaysCompatible()
        Returns true if any lock request on a Lockable L in a compatibility space CS1 is compatible with any other lock held on L in CS1.
      • unlockEvent

        void unlockEvent​(Latch lockInfo)
        Note that the object has been unlocked

        Must only be called by the lock manager. Synchronization will be handled by the lock manager.

      • lockAttributes

        boolean lockAttributes​(int flag,
                               java.util.Hashtable<java.lang.String,​java.lang.Object> attributes)
        If this lockable object wants to participate in a diagnostic virtual lock table, then put any relevant attributes of this lock into the attributes list (the attribute must be an immutable object). The list of attributes of interest to the virtual lock table can be found in VirtualLockTable. The toString method will be called by the VirtualTable on the attribute value for display.

        Parameters:
        flag - use the bits in this int to decide if the user is interested in this kind of lockable object. The bits are defined in VirtualLockTable. For instance, the user may only ask for TABLE_AND_ROWLOCK and if this is not a table or row lock, then don't participate.
        attributes - if this decides to participate, put all relevant attributes into the Hashtable. The complete list of interesting attributes is listed in VirtualLockTable. The following attributes must be present for all participating lockables: VirtualLockTable.LOCKNAME, VirtualLockTable.LOCKTYPE, either VirtualLockTable.CONTAINERID or VirtualLockTable.CONGLOMID,

        MT - this routine must be MP safe, caller will not be single threading the lock manager.

        Returns:
        true if this object has diagnostic information to add to the virtual lock table. If this object either does not want to participate in the diagnostic virtual lock table or none of the attributes requested are attributes of this lock, returns false.
        See Also:
        VirtualLockTable