001: /* Copyright 2002 The JA-SIG Collaborative. All rights reserved.
002: * See license distributed with this file and
003: * available online at http://www.uportal.org/license.html
004: */
005:
006: package org.jasig.portal.concurrency;
007:
008: import org.jasig.portal.EntityIdentifier;
009:
010: /**
011: * Defines an api for acquiring lock objects, <code>IEntityLocks</code>, that
012: * can be used to control concurrent access to portal entities. A lock is
013: * associated with a particular entity and has an <code>owner</code>, a
014: * <code>lockType</code> and a service-controlled <code>expirationTime</code>.
015: * Currently supported lock types are READ_LOCK and WRITE_LOCK.
016: * <p>
017: * If I want to lock an entity for update, I ask the service for a write lock:
018: * <p>
019: * <code>int lockType = IEntityLockService.WRITE_LOCK;<br>
020: * EntityIdentifier eid = myEntity.getEntityIdentifier();<br>
021: * IEntityLock lock = svc.newLock(eid, lockType, lockOwner);</code>
022: * <p>
023: * If there is no conflicting lock on the entity, the service responds with
024: * the requested lock. If I acquire the lock, I know that no other client will
025: * get be able to get a conflicting lock. From then on, I communicate with the
026: * service via the lock:
027: * <p>
028: * <code>
029: * lock.convert(int newType);<br>
030: * lock.isValid();<br>
031: * lock.release();<br>
032: * lock.renew();<br>
033: * </code>
034: * <p>
035: * A READ lock guarantees repeatable reads; other clients can get READ locks
036: * but not WRITE locks. A WRITE lock guarantees exclusive access; no other
037: * clients can get either READ or WRITE locks on the entity.
038: * <p>
039: * NB: since the locking service is not part of a transactional or object
040: * persistence framework, it has no way to enforce its own use.
041: *
042: * @author Dan Ellentuck
043: * @version $Revision: 34757 $
044: */
045: public interface IEntityLockService {
046:
047: // The different types of locks:
048: public static int READ_LOCK = 0;
049: public static int WRITE_LOCK = 1;
050:
051: /**
052: * Attempts to change the lock's <code>lockType</code> to <code>newType</code>.
053: * @param lock IEntityLock
054: * @param newType int
055: * @exception LockingException
056: */
057: public void convert(IEntityLock lock, int newType)
058: throws LockingException;
059:
060: /**
061: * Attempts to change the lock's <code>lockType</code> to <code>newType</code>.
062: * @param lock IEntityLock
063: * @param newType int
064: * @param newDuration int
065: * @exception org.jasig.portal.concurrency.LockingException
066: */
067: public void convert(IEntityLock lock, int newType, int newDuration)
068: throws LockingException;
069:
070: /**
071: * Answer if this <code>IEntityLock</code> exists in the store.
072: * @return boolean
073: * @param lock
074: */
075: public boolean existsInStore(IEntityLock lock)
076: throws LockingException;
077:
078: /**
079: * Answers if this <code>IEntityLock</code> represents a lock that is still
080: * good. To be valid, a lock must exist in the underlying store and be
081: * unexpired and unreleased.
082: *
083: * @param lock IEntityLock
084: * @exception org.jasig.portal.concurrency.LockingException
085: */
086: public boolean isValid(IEntityLock lock) throws LockingException;
087:
088: /**
089: * Returns a lock for the entity, lock type and owner.
090: * @return org.jasig.portal.concurrency.IEntityLock
091: * @param entityType Class
092: * @param entityKey String
093: * @param lockType int
094: * @param owner String
095: * @exception org.jasig.portal.concurrency.LockingException
096: */
097: public IEntityLock newLock(Class entityType, String entityKey,
098: int lockType, String owner) throws LockingException;
099:
100: /**
101: * Returns a lock for the entity, lock type and owner.
102: * @return org.jasig.portal.concurrency.IEntityLock
103: * @param entityType Class
104: * @param entityKey String
105: * @param lockType int
106: * @param owner String
107: * @param durationSecs int
108: * @exception org.jasig.portal.concurrency.LockingException
109: */
110: public IEntityLock newLock(Class entityType, String entityKey,
111: int lockType, String owner, int durationSecs)
112: throws LockingException;
113:
114: /**
115: * Returns a lock for the entity, lock type and owner.
116: * @return org.jasig.portal.concurrency.IEntityLock
117: * @param entityID EntityIdentifier
118: * @param lockType int
119: * @param owner String
120: * @exception org.jasig.portal.concurrency.LockingException
121: */
122: public IEntityLock newLock(EntityIdentifier entityID, int lockType,
123: String owner) throws LockingException;
124:
125: /**
126: * Returns a lock for the entity, lock type and owner.
127: * @return org.jasig.portal.concurrency.IEntityLock
128: * @param entityID EntityIdentifier
129: * @param lockType int
130: * @param owner String
131: * @param durationSecs int
132: * @exception org.jasig.portal.concurrency.LockingException
133: */
134: public IEntityLock newLock(EntityIdentifier entityID, int lockType,
135: String owner, int durationSecs) throws LockingException;
136:
137: /**
138: * Releases the <code>IEntityLock</code>.
139: * @param lock IEntityLock
140: * @exception org.jasig.portal.concurrency.LockingException
141: */
142: public void release(IEntityLock lock) throws LockingException;
143:
144: /**
145: * Extends the expiration time of the lock by the default increment.
146: * @param lock IEntityLock
147: * @exception org.jasig.portal.concurrency.LockingException
148: */
149: public void renew(IEntityLock lock) throws LockingException;
150:
151: /**
152: * Extends the expiration time of the lock by <code>duration</code> seconds.
153: * @param lock IEntityLock
154: * @param duration
155: * @exception LockingException
156: */
157: public void renew(IEntityLock lock, int duration)
158: throws LockingException;
159: }
|