KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > transaction > locking > LockManager2


1 /*
2  * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//transaction/src/java/org/apache/commons/transaction/locking/LockManager2.java,v 1.5 2005/01/10 00:04:27 ozeigermann Exp $
3  * $Revision$
4  * $Date: 2005-02-26 14:16:14 +0100 (Sa, 26 Feb 2005) $
5  *
6  * ====================================================================
7  *
8  * Copyright 1999-2004 The Apache Software Foundation
9  *
10  * Licensed under the Apache License, Version 2.0 (the "License");
11  * you may not use this file except in compliance with the License.
12  * You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing, software
17  * distributed under the License is distributed on an "AS IS" BASIS,
18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  * See the License for the specific language governing permissions and
20  * limitations under the License.
21  *
22  */

23
24 package org.apache.commons.transaction.locking;
25
26 import java.util.Set JavaDoc;
27
28 /**
29  * Extended version of a lock manager that also has global knowledge or all locks and should be
30  * used as a delegate for all locking requests. This allows for things like deadlock detection.
31  *
32  * @version $Revision$
33  * @see MultiLevelLock
34  * @see MultiLevelLock2
35  * @see LockManager
36  * @see GenericLockManager
37  * @see GenericLock
38  * @since 1.1
39  */

40 public interface LockManager2 {
41
42     /**
43      * Determines if a lock is owner by an owner. <br>
44      *
45      * @param ownerId
46      * a unique id identifying the entity that wants to check this
47      * lock
48      * @param resourceId
49      * the resource to get the level for
50      * @param lockLevel
51      * the lock level to check
52      * @return <code>true</code> if the owner has the lock, <code>false</code> otherwise
53      *
54      */

55     public boolean hasLock(Object JavaDoc ownerId, Object JavaDoc resourceId, int lockLevel);
56
57     /**
58      * Determines if a lock <em>could</em> be acquire <em>without</em> actually acquiring it. <br>
59      * <br>
60      * This method does not block, but immediatly returns.
61      *
62      * @param ownerId
63      * a unique id identifying the entity that wants to check this
64      * lock
65      * @param resourceId
66      * the resource to get the level for
67      * @param targetLockLevel
68      * the lock level to check
69      * @param reentrant
70      * <code>true</code> if this request shall not be influenced by
71      * other locks held by the same owner
72      * @return <code>true</code> if the lock could be acquired, <code>false</code> otherwise
73      *
74      */

75     public boolean checkLock(Object JavaDoc ownerId, Object JavaDoc resourceId, int targetLockLevel, boolean reentrant);
76
77     /**
78      * Tries to acquire a lock on a resource. <br>
79      * <br>
80      * This method does not block, but immediatly returns. If a lock is not
81      * available <code>false</code> will be returned.
82      *
83      * @param ownerId
84      * a unique id identifying the entity that wants to acquire this
85      * lock
86      * @param resourceId
87      * the resource to get the level for
88      * @param targetLockLevel
89      * the lock level to acquire
90      * @param reentrant
91      * <code>true</code> if this request shall not be influenced by
92      * other locks held by the same owner
93      * @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
94      *
95      */

96     public boolean tryLock(Object JavaDoc ownerId, Object JavaDoc resourceId, int targetLockLevel, boolean reentrant);
97
98     /**
99      * Tries to acquire a lock on a resource. <br>
100      * <br>
101      * This method blocks and waits for the lock in case it is not avaiable. If
102      * there is a timeout or a deadlock or the thread is interrupted a
103      * LockException is thrown.
104      *
105      * @param ownerId
106      * a unique id identifying the entity that wants to acquire this
107      * lock
108      * @param resourceId
109      * the resource to get the level for
110      * @param targetLockLevel
111      * the lock level to acquire
112      * @param reentrant
113      * <code>true</code> if this request shall not be blocked by
114      * other locks held by the same owner
115      * @throws LockException
116      * will be thrown when the lock can not be acquired
117      */

118     public void lock(Object JavaDoc ownerId, Object JavaDoc resourceId, int targetLockLevel, boolean reentrant)
119             throws LockException;
120
121     /**
122      * Tries to acquire a lock on a resource. <br>
123      * <br>
124      * This method blocks and waits for the lock in case it is not avaiable. If
125      * there is a timeout or a deadlock or the thread is interrupted a
126      * LockException is thrown.
127      *
128      * @param ownerId
129      * a unique id identifying the entity that wants to acquire this
130      * lock
131      * @param resourceId
132      * the resource to get the level for
133      * @param targetLockLevel
134      * the lock level to acquire
135      * @param reentrant
136      * <code>true</code> if this request shall not be blocked by
137      * other locks held by the same owner
138      * @param timeoutMSecs
139      * specifies the maximum wait time in milliseconds
140      * @throws LockException
141      * will be thrown when the lock can not be acquired
142      */

143     public void lock(Object JavaDoc ownerId, Object JavaDoc resourceId, int targetLockLevel, boolean reentrant,
144             long timeoutMSecs) throws LockException;
145
146     /**
147      * Most flexible way to acquire a lock on a resource. <br>
148      * <br>
149      * This method blocks and waits for the lock in case it is not avaiable. If
150      * there is a timeout or a deadlock or the thread is interrupted a
151      * LockException is thrown.
152      *
153      * @param ownerId
154      * a unique id identifying the entity that wants to acquire this
155      * lock
156      * @param resourceId
157      * the resource to get the level for
158      * @param targetLockLevel
159      * the lock level to acquire
160      * @param compatibility
161      * {@link GenericLock#COMPATIBILITY_NONE}if no additional compatibility is
162      * desired (same as reentrant set to false) ,
163      * {@link GenericLock#COMPATIBILITY_REENTRANT}if lock level by the same
164      * owner shall not affect compatibility (same as reentrant set to
165      * true), or {@link GenericLock#COMPATIBILITY_SUPPORT}if lock levels that
166      * are the same as the desired shall not affect compatibility, or
167      * finally {@link GenericLock#COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
168      * a combination of reentrant and support
169      * @param preferred
170      * in case this lock request is incompatible with existing ones
171      * and we wait, it shall be granted before other waiting requests
172      * that are not preferred
173      * @param timeoutMSecs
174      * specifies the maximum wait time in milliseconds
175      * @throws LockException
176      * will be thrown when the lock can not be acquired
177      */

178     public void lock(Object JavaDoc ownerId, Object JavaDoc resourceId, int targetLockLevel, int compatibility,
179             boolean preferred, long timeoutMSecs) throws LockException;
180
181     /**
182      * Starts a global timeout for an owner. This is especially usefull, when the owner is a
183      * transaction. After a global timeout occurs all of the owner's lock will be released and
184      * the owner will not be allowed to access any
185      * locks before before calling {@link #releaseAll(Object)}.
186      *
187      * @param ownerId
188      * a unique id identifying the entity that wants to acquire this
189      * lock
190      * @param timeoutMSecs
191      * specifies the global timeout in milliseconds
192      */

193     public void startGlobalTimeout(Object JavaDoc ownerId, long timeoutMSecs);
194     
195     /**
196      * Gets the lock level held by certain owner on a certain resource.
197      *
198      * @param ownerId the id of the owner of the lock
199      * @param resourceId the resource to get the level for
200      */

201     public int getLevel(Object JavaDoc ownerId, Object JavaDoc resourceId);
202
203     /**
204      * Releases all locks for a certain resource held by a certain owner.
205      *
206      * @param ownerId the id of the owner of the lock
207      * @param resourceId the resource to releases the lock for
208      * @return <code>true</code> if the lock actually was released, <code>false</code> in case
209      * there was no lock held by the owner
210      */

211     public boolean release(Object JavaDoc ownerId, Object JavaDoc resourceId);
212
213     /**
214      * Releases all locks (partially) held by an owner.
215      *
216      * @param ownerId the id of the owner
217      */

218     public void releaseAll(Object JavaDoc ownerId);
219     
220     /**
221      * Gets all locks (partially) held by an owner.
222      *
223      * @param ownerId the id of the owner
224      * @return all locks held by ownerId
225      */

226     public Set JavaDoc getAll(Object JavaDoc ownerId);
227
228     
229     /**
230      * Gets an existing lock on the specified resource. If none exists it returns <code>null</code>.
231      *
232      * @param resourceId the resource to get the lock for
233      * @return the lock on the specified resource
234      *
235      */

236     public MultiLevelLock getLock(Object JavaDoc resourceId);
237
238     /**
239      * Removes the specified lock from the associated resource.
240      *
241      * <em>Caution:</em> This does not release the lock, but only moves it out
242      * of the scope of this manager. Use {@link #release(Object, Object)} for that.
243      *
244      * @param lock the lock to be removed
245      */

246     public void removeLock(MultiLevelLock lock);
247
248 }
249
Popular Tags