com.im.commons.progress
Interface DFLockable

public interface DFLockable

Most of DIF write method (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.

Description	How many instances exists	Where to find it	Details
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.

Field Summary

static String

PROP_LOCKED

Method Summary

void	addPropertyChangeListener(PropertyChangeListener pcl) Register to listen to PROP_LOCKED property change.
void	checkLock(DFLock testedLock) Checks whether the lock belongs to this lockable.
boolean	isLocked() Is a valid lock held by someone already?
boolean	isLockedForever() Is this lockable constantly locked? This can be used for lockables which are in readonly mode (e.g.
DFLock	obtainLock(String reason) Obtains the lock; fails with AlreadyLockedException if the object is already locked.
void	removePropertyChangeListener(PropertyChangeListener pcl) Unregister to listen to PROP_LOCKED property change.

Field Detail

PROP_LOCKED

static final String PROP_LOCKED

See Also:

Constant Field Values

Method Detail

obtainLock

DFLock obtainLock(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 1. 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(PropertyChangeListener pcl)

Register to listen to PROP_LOCKED property change.

Parameters:

pcl - The PropertyChangeListener to register

removePropertyChangeListener

void removePropertyChangeListener(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:

IllegalStateException - thrown when the lock does not belongs to this lockable.