LockFactory


1   /*
2   
3      Derby - Class org.apache.derby.iapi.services.locks.LockFactory
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.iapi.services.locks;
23  
24  import org.apache.derby.iapi.util.Matchable;
25  import org.apache.derby.iapi.error.StandardException;
26  import org.apache.derby.iapi.services.property.PropertySetCallback;
27  import java.util.Enumeration  ;
28  
29  
30  /**
31      Generic locking of objects. Enables deadlock detection.
32  
33    <BR>
34      MT - Mutable - Container Object - Thread Safe
35  
36  
37  */
38  public interface LockFactory extends PropertySetCallback {
39  
40      /**
41          Lock an object within a compatability space
42          and associate the lock with a group object,
43          waits up to timeout milli-seconds for the object to become unlocked. A 
44          timeout of 0 means do not wait for the lock to be unlocked.
45          Note the actual time waited is approximate.
46          <P>
47          A compatibility space in an space where lock requests are assumed to be
48          compatabile and granted by the lock manager if the trio
49          {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
50          for qualifier, equals() method
51          for compatabilitySpace and ref ). A typical reference to use for the compatability
52          space is a reference to an object representing a transaction.
53          Granted by the lock manager means that the Lockable object may or may 
54          not be queried to see if the request is compatible.
55          <BR>
56          A compatability space is not assumed to be owned by a single thread.
57      
58  
59  
60          @param compatabilitySpace object defining compatability space (by value)
61          @param group handle of group, must be private to a thread.
62          @param ref reference to object to be locked
63          @param qualifier A qualification of the request.
64          @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
65  
66          @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock
67          could not be granted.
68  
69          @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
70          @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).
71          @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
72          it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
73          (message id will be LockFactory.InterruptedExceptionId)
74          @exception StandardException Standard Cloudscape error policy.
75  
76      */
77      public boolean lockObject(Object   compatabilitySpace, Object   group, Lockable ref, Object   qualifier, int timeout)
78          throws StandardException;
79  
80      /**
81          Lock an object within a compatability space
82          and associate the lock with a group object,
83          waits forever the object to become unlocked.
84          <P>
85          A compatibility space in an space where lock requests are assumed to be
86          compatabile and granted by the lock manager if the trio
87          {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
88          for qualifier, equals() method
89          for compatabilitySpace and ref ). A typical reference to use for the compatability
90          space is a reference to an object representing a transaction.
91          Granted by the lock manager means that the Lockable object may or may 
92          not be queried to see if the request is compatible.
93          <BR>
94          A compatability space is not assumed to be owned by a single thread.
95      
96  
97  
98          @param compatabilitySpace object defining compatability space (by value)
99          @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     /**
114         Lock an object within a compatability space
115         and associate the lock with a group object,
116         In addition a held latch is passed in. If the lock
117         cannot be granted immediately, the latch will be released
118         and relatched after the lock is obtained. If the lock can be granted
119         immediately the latch is not released.
120         <BR>
121         The compatability space of the request is defined by the compatability
122         space of the latch.
123         <P>
124         @param group handle of group, must be private to a compatability space.
125         @param ref reference to object to be locked
126         @param qualifier A qualification of the request.
127         @param timeout amount of time to wait, <B>NO_WAIT is not supported</B>
128         @param latch latch to be atomically released/re-latched in a wait.
129 
130         @return true if the latch was released, false otherwise.
131 
132         @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
133         @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
134         it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
135         (message id will be LockFactory.InterruptedExceptionId)
136         @exception StandardException Standard Cloudscape error policy.
137 
138     */
139     public boolean lockObject(Object   group, Lockable ref, 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, Lockable ref, Object   qualifier);
154 
155     /**
156         Unlock all locks in a group. 
157 
158         @param group handle of group that objects were locked with.
159     */
160     public void unlockGroup(Object   compatabilitySpace, Object   group);
161 
162     /**
163         Unlock all locks on a group that match the passed in value.
164     */
165     public void unlockGroup(Object   compatabilitySpace, Object   group, Matchable key);
166 
167     /**
168         Transfer a set of locks from one group to another.
169     */
170     public void transfer(Object   compatabilitySpace, Object   oldGroup, Object   newGroup);
171 
172     /**
173         Returns true if locks held by anyone are blocking anyone else
174     */
175     public boolean anyoneBlocked();
176 
177     /**
178         Return true if locks are held in this compatability space and
179          this group.
180 
181         @param group handle of group that objects were locked with.
182 
183     */
184     public boolean areLocksHeld(Object   compatabilitySpace, Object   group);
185 
186     /**
187         Return true if locks are held in this compatability space.
188     */
189     public boolean areLocksHeld(Object   compatabilitySpace);
190 
191 
192     /**
193         Latch an object. A latch is a lock without a group.
194         This means that it must be released explicitly by the owner.
195         A latch is not released by any unlock methods, it must be
196         released by the unlatch method. A latch is assumed to only
197         be held by one locker at a time.
198 <BR>
199         The first argument passed to lockEvent() is the Latch that
200         is to be used in the unlatch() call.
201         The firstArgument passed to unlockEvent() should be ignored.
202 
203         @return true if the latch was obtained,
204         false if timeout is equal to LockFactory.NO_WAIT and the lock could not be granted.
205 
206 
207         @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
208         @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
209         it was waiting for the latch. This will be a StandardException with a nested java.lang.InterruptedException exception,
210         (message id will be LockFactory.InterruptedExceptionId)
211         @exception StandardException Standard Cloudscape error policy.
212     */
213     public boolean latchObject(Object   compatabilitySpace, Lockable ref, Object   qualifier, int timeout)
214         throws StandardException;
215 
216     /**
217         Unlatch an object.
218     */
219     public void unlatch(Latch heldLatch);
220 
221     
222     /**
223         Lock an object with zero duration within a compatability space,
224         waits up to timeout milli-seconds for the object to become unlocked. A 
225         timeout of 0 means do not wait for the lock to be unlocked.
226         Note the actual time waited is approximate.
227         <P>
228         Zero duration means the lock is released as soon as it is obtained.
229         <P>
230         A compatibility space in an space where lock requests are assumed to be
231         compatabile and granted by the lock manager if the trio
232         {compatabilitySpace, ref, qualifier} are equal (i.e. reference equality
233         for qualifier, equals() method
234         for compatabilitySpace and ref ). A typical reference to use for the compatability
235         space is a reference to an object representing a transaction.
236         Granted by the lock manager means that the Lockable object may or may 
237         not be queried to see if the request is compatible.
238         <BR>
239         A compatability space is not assumed to be owned by a single thread.
240     
241 
242 
243         @param compatabilitySpace object defining compatability space (by value)
244         @param ref reference to object to be locked
245         @param qualifier A qualification of the request.
246         @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.
247 
248         @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock
249         could not be granted.
250 
251         @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)
252         @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).
253         @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while
254         it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,
255         (message id will be LockFactory.InterruptedExceptionId)
256         @exception StandardException Standard Cloudscape error policy.
257 
258     */
259     public boolean zeroDurationlockObject(Object   compatabilitySpace, Lockable ref, Object   qualifier, int timeout)
260         throws StandardException;
261 
262     /**
263         Check to see if a specific lock is held.
264     */
265     public boolean isLockHeld(Object   compatabilitySpace, Object   group, Lockable ref, Object   qualifier);
266 
267     /**
268         Install a limit that is called when the size of the group exceeds
269         the required limit.
270         <BR>
271         It is not guaranteed that the callback method (Limit.reached) is
272         called as soon as the group size exceeds the given limit.
273         If the callback method does not result in a decrease in the
274         number of locks held then the lock factory implementation
275         may delay calling the method again. E.g. with a limit
276         of 500 and a reached() method that does nothing, may result
277         in the call back method only being called when the group size reaches
278         550.
279         <BR>
280         Only one limit may be in place for a group at any time.
281         @see Limit
282     */
283     public void setLimit(Object   compatabilitySpace, Object   group, int limit, Limit callback);
284 
285     /**
286         Clear a limit set by setLimit.
287     */
288     public void clearLimit(Object   compatabilitySpace, Object   group); 
289 
290     /**
291         Make a virtual lock table for diagnostics.
292      */
293     public Enumeration   makeVirtualLockTable();
294 
295 }
296 
297 
298
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags