Package com.im.commons.progress

Interface DFLockable

  • All Known Implementing Classes:
    SimpleLockable
    public interface DFLockable
    Most of DIF write methods (methods which modifies data or model somehow) use locking. Before such a method is called you must obtain a lock, put it to DFEnvironmentRW and then pass this environment to the data modification method. Each lockable provides only a single DFLock instance at the same time. Lock should be held by calling thread to prevent other threads to doing modifications concurrently. It is forbidden to obtain a lock and use it from two different threads. Results of such actions are unpredictable and can corrupt the DIF internal status.

    DFLockable is a lock provider. There are more DFLockable instances in the system. You always need to choose the appropriate way how to obtain the DFLockable instance for your specific DIF operation.

    In many cases DIFUtilities.getLockable(yourObject) methods can help you with this, but these methods are just utilities which delegates to the real source of appropriate DFLockable.

    Once you lock the object using the appropriate DFLockable provider, perform the operation, never forget to release the lock (see DFLock for more details).

    Currently there are at least six types of known lockable types in DIF APIs. You can obtain them directly or for some of them also use DIFUtilities methods mentioned above.

    Types
    DescriptionHow many instances existsWhere to find itDetails
    Global DDL for shared items (com.im.df.api.ddl package) One instance per DFSchema DFSchema.getLockable() For manipulation with shared global DDL objects (DFSchema, DFEntity, DFField, DFDataTree, DFRelationship). This object is usually "locked forever" if you are not admin and aren't in single user mode
    Global DDL for user specific items One instance per DFSchema DFSchema.getUserLockable() For manipulation with user specific (user owned) objects (DFView, DFQuery, DFList). Typically even users with no access rights for data or schema modifications can obtain this lock.
    DML for data modifications in one DFEntity One instance per com.im.df.api.dml.DFEntityDataProvider which means one for each entity defined in the schema com.im.df.api.dml.DFEntityDataProvider.getLockable() For manipulation with data of one DFEntity which typically means one DB table
    DFResultSet operations (com.im.df.api.dml package) One instance per DFResultSet com.im.df.api.dml.DFResultSet.getLockable() For changing any property of DFResultSet and all its DFResultSet.VertexState(s). For example if you want to change sorting, apply a new query, etc.
    DFSchemaProvider operations (com.im.df.api package) One instance per DFSchemaProvider which means one per DFSchema DFSchemaProvider.getLockable() For changing the state of DFSchemaProvider - which means for opening/closing connection.
    Other service specific lockables (e.g. com.im.df.api.capabilities.IJCUserDetailsService) One instance per such a service For example IJCUserDetailsService.getLockable() For performing write operations on such a service object - in this case for example for adding or removeing users.
    Author:
    Petr Hamernik

    • Field Detail

      • PROP_LOCKED

        static final java.lang.String PROP_LOCKED
        Fired when lock managed by this lockable is acquired or released.
        See Also:
        Constant Field Values

    • Method Detail

      • obtainLock

        DFLock obtainLock​(java.lang.String reason)
           throws AlreadyLockedException
        Obtains the lock; fails with AlreadyLockedException if the object is already locked.
        Parameters:
        reason - The localized string explaining the operation or reason for locking. May be null.
        Returns:
        The lock, if one can be obtained. Never returns null, throws exception instead.
        Throws:
        AlreadyLockedException - if lockable provided another instance of DFLock before and this lock is still active

      • isLocked

        boolean isLocked()
        Is a valid lock held by someone already?
        Returns:
        true if locked

      • isLockedForever

        boolean isLockedForever()
        Is this lockable constantly locked? This can be used for lockables which are in readonly mode (e.g. when you log in as a user without appropriate access rights). If this method returns true, it means that isLocked() returns true during whole life time of this object and will never change. Lockable which is "forever locked" will never change this status to unlocked during one session. It also means that you don't need to listen to PROP_LOCKED property on this DFLockable, because it will be never fired.
        Returns:
        true if "forever locked"

      • addPropertyChangeListener

        void addPropertyChangeListener​(java.beans.PropertyChangeListener pcl)
        Register to listen to PROP_LOCKED property change.
        Parameters:
        pcl - The PropertyChangeListener to register

      • removePropertyChangeListener

        void removePropertyChangeListener​(java.beans.PropertyChangeListener pcl)
        Unregister to listen to PROP_LOCKED property change.
        Parameters:
        pcl - Th PropertyChangeListener to unregister

      • checkLock

        void checkLock​(DFLock testedLock)
        Checks whether the lock belongs to this lockable.
        Parameters:
        testedLock - The lock to check
        Throws:
        java.lang.IllegalStateException - thrown when the lock does not belongs to this lockable.