org.jasig.portal.concurrency
Interface IEntityLockService

All Known Implementing Classes:

ReferenceEntityLockService

public interface IEntityLockService

Defines an api for acquiring lock objects, IEntityLocks, that can be used to control concurrent access to portal entities. A lock is associated with a particular entity and has an owner, a lockType and a service-controlled expirationTime. Currently supported lock types are READ_LOCK and WRITE_LOCK.

If I want to lock an entity for update, I ask the service for a write lock:

int lockType = IEntityLockService.WRITE_LOCK;
EntityIdentifier eid = myEntity.getEntityIdentifier();
IEntityLock lock = svc.newLock(eid, lockType, lockOwner);

If there is no conflicting lock on the entity, the service responds with the requested lock. If I acquire the lock, I know that no other client will get be able to get a conflicting lock. From then on, I communicate with the service via the lock:

lock.convert(int newType);
lock.isValid();
lock.release();
lock.renew();


A READ lock guarantees repeatable reads; other clients can get READ locks but not WRITE locks. A WRITE lock guarantees exclusive access; no other clients can get either READ or WRITE locks on the entity.

NB: since the locking service is not part of a transactional or object persistence framework, it has no way to enforce its own use.

Version:

$Revision: 19776 $

Author:

Dan Ellentuck

Field Summary

static int	READ_LOCK
static int	WRITE_LOCK

Method Summary

void	convert(IEntityLock lock, int newType) Attempts to change the lock's lockType to newType.
void	convert(IEntityLock lock, int newType, int newDuration) Attempts to change the lock's lockType to newType.
boolean	existsInStore(IEntityLock lock) Answer if this IEntityLock exists in the store.
boolean	isValid(IEntityLock lock) Answers if this IEntityLock represents a lock that is still good.
IEntityLock	newLock(Class entityType, String entityKey, int lockType, String owner) Returns a lock for the entity, lock type and owner.
IEntityLock	newLock(Class entityType, String entityKey, int lockType, String owner, int durationSecs) Returns a lock for the entity, lock type and owner.
IEntityLock	newLock(EntityIdentifier entityID, int lockType, String owner) Returns a lock for the entity, lock type and owner.
IEntityLock	newLock(EntityIdentifier entityID, int lockType, String owner, int durationSecs) Returns a lock for the entity, lock type and owner.
void	release(IEntityLock lock) Releases the IEntityLock.
void	renew(IEntityLock lock) Extends the expiration time of the lock by the default increment.
void	renew(IEntityLock lock, int duration) Extends the expiration time of the lock by duration seconds.

Field Detail

READ_LOCK

static final int READ_LOCK

See Also:

Constant Field Values

WRITE_LOCK

static final int WRITE_LOCK

See Also:

Constant Field Values

Method Detail

convert

void convert(IEntityLock lock,
             int newType)
             throws LockingException

Attempts to change the lock's lockType to newType.

Parameters:

lock - IEntityLock

newType - int

Throws:

LockingException

convert

void convert(IEntityLock lock,
             int newType,
             int newDuration)
             throws LockingException

Attempts to change the lock's lockType to newType.

Parameters:

lock - IEntityLock

newType - int

newDuration - int

Throws:

LockingException

existsInStore

boolean existsInStore(IEntityLock lock)
                      throws LockingException

Answer if this IEntityLock exists in the store.

Parameters:

lock -

Returns:

boolean

Throws:

LockingException

isValid

boolean isValid(IEntityLock lock)
                throws LockingException

Answers if this IEntityLock represents a lock that is still good. To be valid, a lock must exist in the underlying store and be unexpired and unreleased.

Parameters:

lock - IEntityLock

Throws:

LockingException

newLock

IEntityLock newLock(Class entityType,
                    String entityKey,
                    int lockType,
                    String owner)
                    throws LockingException

Returns a lock for the entity, lock type and owner.

Parameters:

entityType - Class

entityKey - String

lockType - int

owner - String

Returns:

org.jasig.portal.concurrency.IEntityLock

Throws:

LockingException

newLock

IEntityLock newLock(Class entityType,
                    String entityKey,
                    int lockType,
                    String owner,
                    int durationSecs)
                    throws LockingException

Returns a lock for the entity, lock type and owner.

Parameters:

entityType - Class

entityKey - String

lockType - int

owner - String

durationSecs - int

Returns:

org.jasig.portal.concurrency.IEntityLock

Throws:

LockingException

newLock

IEntityLock newLock(EntityIdentifier entityID,
                    int lockType,
                    String owner)
                    throws LockingException

Returns a lock for the entity, lock type and owner.

Parameters:

entityID - EntityIdentifier

lockType - int

owner - String

Returns:

org.jasig.portal.concurrency.IEntityLock

Throws:

LockingException

newLock

IEntityLock newLock(EntityIdentifier entityID,
                    int lockType,
                    String owner,
                    int durationSecs)
                    throws LockingException

Returns a lock for the entity, lock type and owner.

Parameters:

entityID - EntityIdentifier

lockType - int

owner - String

durationSecs - int

Returns:

org.jasig.portal.concurrency.IEntityLock

Throws:

LockingException

release

void release(IEntityLock lock)
             throws LockingException

Releases the IEntityLock.

Parameters:

lock - IEntityLock

Throws:

LockingException

renew

void renew(IEntityLock lock)
           throws LockingException

Extends the expiration time of the lock by the default increment.

Parameters:

lock - IEntityLock

Throws:

LockingException

renew

void renew(IEntityLock lock,
           int duration)
           throws LockingException

Extends the expiration time of the lock by duration seconds.

Parameters:

lock - IEntityLock

duration -

Throws:

LockingException