001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.locks.LockFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.locks;
023:
024: import org.apache.derby.iapi.util.Matchable;
025: import org.apache.derby.iapi.error.StandardException;
026: import org.apache.derby.iapi.services.property.PropertySetCallback;
027: import java.util.Enumeration;
028:
029: /**
030: Generic locking of objects. Enables deadlock detection.
031:
032: <BR>
033: MT - Mutable - Container Object - Thread Safe
034:
035:
036: */
037: public interface LockFactory extends PropertySetCallback {
038:
039: /**
040: Lock an object within a compatability space
041: and associate the lock with a group object,
042: waits up to timeout milli-seconds for the object to become unlocked. A
043: timeout of 0 means do not wait for the lock to be unlocked.
044: Note the actual time waited is approximate.
045: <P>
046: A compatibility space in an space where lock requests are assumed to be
047: compatabile and granted by the lock manager if the trio
048: {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
049: for qualifier, equals() method
050: for compatabilitySpace and ref ). A typical reference to use for the compatability
051: space is a reference to an object representing a transaction.
052: Granted by the lock manager means that the Lockable object may or may
053: not be queried to see if the request is compatible.
054: <BR>
055: A compatability space is not assumed to be owned by a single thread.
056:
057:
058:
059: @param compatabilitySpace object defining compatability space (by value)
060: @param group handle of group, must be private to a thread.
061: @param ref reference to object to be locked
062: @param qualifier A qualification of the request.
063: @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
064:
065: @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock
066: could not be granted.
067:
068: @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
069: @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).
070: @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
071: it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
072: (message id will be LockFactory.InterruptedExceptionId)
073: @exception StandardException Standard Cloudscape error policy.
074:
075: */
076: public boolean lockObject(Object compatabilitySpace, Object group,
077: Lockable ref, Object qualifier, int timeout)
078: throws StandardException;
079:
080: /**
081: Lock an object within a compatability space
082: and associate the lock with a group object,
083: waits forever the object to become unlocked.
084: <P>
085: A compatibility space in an space where lock requests are assumed to be
086: compatabile and granted by the lock manager if the trio
087: {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
088: for qualifier, equals() method
089: for compatabilitySpace and ref ). A typical reference to use for the compatability
090: space is a reference to an object representing a transaction.
091: Granted by the lock manager means that the Lockable object may or may
092: not be queried to see if the request is compatible.
093: <BR>
094: A compatability space is not assumed to be owned by a single thread.
095:
096:
097:
098: @param compatabilitySpace object defining compatability space (by value)
099: @param group handle of group, must be private to a thread.
100: @param ref reference to object to be locked
101: @param qualifier A qualification of the request.
102:
103: @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
104: @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
105: it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
106: (message id will be LockFactory.InterruptedExceptionId)
107: @exception StandardException Standard Cloudscape error policy.
108:
109: */
110: //public void lockObject(Object compatabilitySpace, Object group, Lockable ref, Object qualifier)
111: // throws StandardException;
112: /**
113: Lock an object within a compatability space
114: and associate the lock with a group object,
115: In addition a held latch is passed in. If the lock
116: cannot be granted immediately, the latch will be released
117: and relatched after the lock is obtained. If the lock can be granted
118: immediately the latch is not released.
119: <BR>
120: The compatability space of the request is defined by the compatability
121: space of the latch.
122: <P>
123: @param group handle of group, must be private to a compatability space.
124: @param ref reference to object to be locked
125: @param qualifier A qualification of the request.
126: @param timeout amount of time to wait, <B>NO_WAIT is not supported</B>
127: @param latch latch to be atomically released/re-latched in a wait.
128:
129: @return true if the latch was released, false otherwise.
130:
131: @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
132: @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
133: it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
134: (message id will be LockFactory.InterruptedExceptionId)
135: @exception StandardException Standard Cloudscape error policy.
136:
137: */
138: public boolean lockObject(Object group, Lockable ref,
139: Object qualifier, int timeout, Latch latch)
140: throws StandardException;
141:
142: /**
143: Unlock a single lock on a single object held within this compatability space
144: that was locked with the supplied qualifier.
145:
146: @param compatabilitySpace object defining compatability space (by value)
147: @param group handle of group.
148: @param ref Reference to object to be unlocked.
149: @param qualifier qualifier of lock to be unlocked
150:
151: @return number of locks released (one or zero).
152: */
153: public int unlock(Object compatabilitySpace, Object group,
154: Lockable ref, Object qualifier);
155:
156: /**
157: Unlock all locks in a group.
158:
159: @param group handle of group that objects were locked with.
160: */
161: public void unlockGroup(Object compatabilitySpace, Object group);
162:
163: /**
164: Unlock all locks on a group that match the passed in value.
165: */
166: public void unlockGroup(Object compatabilitySpace, Object group,
167: Matchable key);
168:
169: /**
170: Transfer a set of locks from one group to another.
171: */
172: public void transfer(Object compatabilitySpace, Object oldGroup,
173: Object newGroup);
174:
175: /**
176: Returns true if locks held by anyone are blocking anyone else
177: */
178: public boolean anyoneBlocked();
179:
180: /**
181: Return true if locks are held in this compatability space and
182: this group.
183:
184: @param group handle of group that objects were locked with.
185:
186: */
187: public boolean areLocksHeld(Object compatabilitySpace, Object group);
188:
189: /**
190: Return true if locks are held in this compatability space.
191: */
192: public boolean areLocksHeld(Object compatabilitySpace);
193:
194: /**
195: Latch an object. A latch is a lock without a group.
196: This means that it must be released explicitly by the owner.
197: A latch is not released by any unlock methods, it must be
198: released by the unlatch method. A latch is assumed to only
199: be held by one locker at a time.
200: <BR>
201: The first argument passed to lockEvent() is the Latch that
202: is to be used in the unlatch() call.
203: The firstArgument passed to unlockEvent() should be ignored.
204:
205: @return true if the latch was obtained,
206: false if timeout is equal to LockFactory.NO_WAIT and the lock could not be granted.
207:
208:
209: @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
210: @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
211: it was waiting for the latch. This will be a StandardException with a nested java.lang.InterruptedException exception,
212: (message id will be LockFactory.InterruptedExceptionId)
213: @exception StandardException Standard Cloudscape error policy.
214: */
215: public boolean latchObject(Object compatabilitySpace, Lockable ref,
216: Object qualifier, int timeout) throws StandardException;
217:
218: /**
219: Unlatch an object.
220: */
221: public void unlatch(Latch heldLatch);
222:
223: /**
224: Lock an object with zero duration within a compatability space,
225: waits up to timeout milli-seconds for the object to become unlocked. A
226: timeout of 0 means do not wait for the lock to be unlocked.
227: Note the actual time waited is approximate.
228: <P>
229: Zero duration means the lock is released as soon as it is obtained.
230: <P>
231: A compatibility space in an space where lock requests are assumed to be
232: compatabile and granted by the lock manager if the trio
233: {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
234: for qualifier, equals() method
235: for compatabilitySpace and ref ). A typical reference to use for the compatability
236: space is a reference to an object representing a transaction.
237: Granted by the lock manager means that the Lockable object may or may
238: not be queried to see if the request is compatible.
239: <BR>
240: A compatability space is not assumed to be owned by a single thread.
241:
242:
243:
244: @param compatabilitySpace object defining compatability space (by value)
245: @param ref reference to object to be locked
246: @param qualifier A qualification of the request.
247: @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
248:
249: @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock
250: could not be granted.
251:
252: @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
253: @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).
254: @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
255: it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
256: (message id will be LockFactory.InterruptedExceptionId)
257: @exception StandardException Standard Cloudscape error policy.
258:
259: */
260: public boolean zeroDurationlockObject(Object compatabilitySpace,
261: Lockable ref, Object qualifier, int timeout)
262: throws StandardException;
263:
264: /**
265: Check to see if a specific lock is held.
266: */
267: public boolean isLockHeld(Object compatabilitySpace, Object group,
268: Lockable ref, Object qualifier);
269:
270: /**
271: Install a limit that is called when the size of the group exceeds
272: the required limit.
273: <BR>
274: It is not guaranteed that the callback method (Limit.reached) is
275: called as soon as the group size exceeds the given limit.
276: If the callback method does not result in a decrease in the
277: number of locks held then the lock factory implementation
278: may delay calling the method again. E.g. with a limit
279: of 500 and a reached() method that does nothing, may result
280: in the call back method only being called when the group size reaches
281: 550.
282: <BR>
283: Only one limit may be in place for a group at any time.
284: @see Limit
285: */
286: public void setLimit(Object compatabilitySpace, Object group,
287: int limit, Limit callback);
288:
289: /**
290: Clear a limit set by setLimit.
291: */
292: public void clearLimit(Object compatabilitySpace, Object group);
293:
294: /**
295: Make a virtual lock table for diagnostics.
296: */
297: public Enumeration makeVirtualLockTable();
298:
299: }
|