org.entityfs.lock
Interface EntityLock

All Superinterfaces:

Lock

All Known Implementing Classes:

CompoundEntityLock, DummyLock, EntityLockReentrantLockAdapterImpl, NoObjectDummyLock

public interface EntityLock
extends Lock

The EntityLock is a reentrant Lock for a lockable object (not only for entity objects). A lockable object implements ReadLockable, WriteLockable or both.

Depending on the EntityLockAdapterFactory used, an EntityLock can be a read lock, a write lock or both at the same time. For entities, their file system's EntityLockAdapterFactory is used. For other objects, this has to be provided by the creator somehow,

A lockable object is locked by calling its ReadLockable.lockForReading() or WriteLockable.lockForWriting() methods. A client can also get a custom lock for an entity by calling its EntityView.lock(Object) method.

If a locking method is called on the view of an entity, it locks the entity itself.

A client that uses EntityFS entities concurrently from several threads must implement a locking strategy to avoid deadlocks. The entity objects themselves do not assume any specific locking strategy; the client should be free to choose a suitable strategy for itself. The static utility classes like Files or Directories , however, use the following locking strategy:

• Locks are acquired top-down in the file system hierarchy. A parent entity is locked before its child entities.
• If several entities are locked in the same directory, they are locked in hashCode order. Entities are Comparable based on their hashCode:s to make this easier.
• Locks are released as soon as possible, in no specific order.

Always keep a reference to a locked lock or to the locked entity. If the locking thread does not, the locked entity object may be garbage collected and then the next thread wanting to use the same entity will then get a new, unlocked entity object for the same entity.

The class EntityLocks contains static utility methods for working with locks.

Java Concurrency in Practice is an excellent book on concurrent programming in Java.

Since:

1.0

Author:

Karl Gustafsson

See Also:

ReadLockable, WriteLockable

In_jar:

entityfs-core

Method Summary

int	getHoldCount() Get the hold count of the lock.
Lockable	getLocked() Get the locked object.
boolean	isDummy() Is this lock a dummy lock.
boolean	isHeldByCurrentThread() Is this lock held by the current thread? (This is implemented by ReentrantLock but not specified in the Lock interface.)
boolean	isReadLock() Returns true if this lock is a read lock.
boolean	isWriteLock() Returns true if this lock is a write lock.

Methods inherited from interface java.util.concurrent.locks.Lock

lock, lockInterruptibly, newCondition, tryLock, tryLock, unlock

Method Detail

getLocked

Lockable getLocked()

Get the locked object. For locks that are not connected to any particular object (dummy locks, mostly), this method returns null.

Returns:

The locked object or null if this lock is not connected to any particular object.

isReadLock

boolean isReadLock()

Returns true if this lock is a read lock.

Returns:

true if this is a read lock, false if it is a write lock.

isWriteLock

boolean isWriteLock()

Returns true if this lock is a write lock.

Returns:

true if this is a write lock, false if this is a read lock.

isHeldByCurrentThread

boolean isHeldByCurrentThread()

Is this lock held by the current thread? (This is implemented by ReentrantLock but not specified in the Lock interface.)

Returns:

true if this lock is locked by the current thread.

getHoldCount

int getHoldCount()

Get the hold count of the lock. (How many Lock.lock() has been called minus the number of times Lock.unlock() has been called by the current thread.) If the hold count is 0, the lock is unlocked. The hold count can never be less than 0.

Returns:

The hold count of the lock

isDummy

boolean isDummy()

Is this lock a dummy lock. A dummy lock does not actually do any locking.

Returns:

true if this is a dummy lock.