uPortal 2.4.1
API Documentation

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: 1.5 $
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(java.lang.Class entityType, java.lang.String entityKey, int lockType, java.lang.String owner)
          Returns a lock for the entity, lock type and owner.
 IEntityLock newLock(java.lang.Class entityType, java.lang.String entityKey, int lockType, java.lang.String owner, int durationSecs)
          Returns a lock for the entity, lock type and owner.
 IEntityLock newLock(EntityIdentifier entityID, int lockType, java.lang.String owner)
          Returns a lock for the entity, lock type and owner.
 IEntityLock newLock(EntityIdentifier entityID, int lockType, java.lang.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

public static final int READ_LOCK
See Also:
Constant Field Values

WRITE_LOCK

public static final int WRITE_LOCK
See Also:
Constant Field Values
Method Detail

convert

public 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

public 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

public boolean existsInStore(IEntityLock lock)
                      throws LockingException
Answer if this IEntityLock exists in the store.

Parameters:
lock -
Returns:
boolean
Throws:
LockingException

isValid

public 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

public IEntityLock newLock(java.lang.Class entityType,
                           java.lang.String entityKey,
                           int lockType,
                           java.lang.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

public IEntityLock newLock(java.lang.Class entityType,
                           java.lang.String entityKey,
                           int lockType,
                           java.lang.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

public IEntityLock newLock(EntityIdentifier entityID,
                           int lockType,
                           java.lang.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

public IEntityLock newLock(EntityIdentifier entityID,
                           int lockType,
                           java.lang.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

public void release(IEntityLock lock)
             throws LockingException
Releases the IEntityLock.

Parameters:
lock - IEntityLock
Throws:
LockingException

renew

public void renew(IEntityLock lock)
           throws LockingException
Extends the expiration time of the lock by the default increment.

Parameters:
lock - IEntityLock
Throws:
LockingException

renew

public void renew(IEntityLock lock,
                  int duration)
           throws LockingException
Extends the expiration time of the lock by duration seconds.

Parameters:
lock - IEntityLock
duration -
Throws:
LockingException

uPortal 2.4.1
API Documentation