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  ;
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   ownerId, Object   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   ownerId, Object   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   ownerId, Object   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   ownerId, Object   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   ownerId, Object   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   ownerId, Object   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   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   ownerId, Object   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   ownerId, Object   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   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   getAll(Object   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags