1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.transaction.locking;
18
19 import java.util.Set;
20
21 /**
22 * Extended version of a lock manager that also has global knowledge or all locks and should be
23 * used as a delegate for all locking requests. This allows for things like deadlock detection.
24 *
25 * @version $Id: LockManager2.java 493628 2007-01-07 01:42:48Z joerg $
26 * @see MultiLevelLock
27 * @see MultiLevelLock2
28 * @see LockManager
29 * @see GenericLockManager
30 * @see GenericLock
31 * @since 1.1
32 */
33 public interface LockManager2 {
34
35 /**
36 * Determines if a lock is owner by an owner. <br>
37 *
38 * @param ownerId
39 * a unique id identifying the entity that wants to check this
40 * lock
41 * @param resourceId
42 * the resource to get the level for
43 * @param lockLevel
44 * the lock level to check
45 * @return <code>true</code> if the owner has the lock, <code>false</code> otherwise
46 *
47 */
48 public boolean hasLock(Object ownerId, Object resourceId, int lockLevel);
49
50 /**
51 * Determines if a lock <em>could</em> be acquire <em>without</em> actually acquiring it. <br>
52 * <br>
53 * This method does not block, but immediatly returns.
54 *
55 * @param ownerId
56 * a unique id identifying the entity that wants to check this
57 * lock
58 * @param resourceId
59 * the resource to get the level for
60 * @param targetLockLevel
61 * the lock level to check
62 * @param reentrant
63 * <code>true</code> if this request shall not be influenced by
64 * other locks held by the same owner
65 * @return <code>true</code> if the lock could be acquired, <code>false</code> otherwise
66 *
67 */
68 public boolean checkLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
69
70 /**
71 * Tries to acquire a lock on a resource. <br>
72 * <br>
73 * This method does not block, but immediatly returns. If a lock is not
74 * available <code>false</code> will be returned.
75 *
76 * @param ownerId
77 * a unique id identifying the entity that wants to acquire this
78 * lock
79 * @param resourceId
80 * the resource to get the level for
81 * @param targetLockLevel
82 * the lock level to acquire
83 * @param reentrant
84 * <code>true</code> if this request shall not be influenced by
85 * other locks held by the same owner
86 * @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
87 *
88 */
89 public boolean tryLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
90
91 /**
92 * Tries to acquire a lock on a resource. <br>
93 * <br>
94 * This method blocks and waits for the lock in case it is not avaiable. If
95 * there is a timeout or a deadlock or the thread is interrupted a
96 * LockException is thrown.
97 *
98 * @param ownerId
99 * a unique id identifying the entity that wants to acquire this
100 * lock
101 * @param resourceId
102 * the resource to get the level for
103 * @param targetLockLevel
104 * the lock level to acquire
105 * @param reentrant
106 * <code>true</code> if this request shall not be blocked by
107 * other locks held by the same owner
108 * @throws LockException
109 * will be thrown when the lock can not be acquired
110 */
111 public void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)
112 throws LockException;
113
114 /**
115 * Tries to acquire a lock on a resource. <br>
116 * <br>
117 * This method blocks and waits for the lock in case it is not avaiable. If
118 * there is a timeout or a deadlock or the thread is interrupted a
119 * LockException is thrown.
120 *
121 * @param ownerId
122 * a unique id identifying the entity that wants to acquire this
123 * lock
124 * @param resourceId
125 * the resource to get the level for
126 * @param targetLockLevel
127 * the lock level to acquire
128 * @param reentrant
129 * <code>true</code> if this request shall not be blocked by
130 * other locks held by the same owner
131 * @param timeoutMSecs
132 * specifies the maximum wait time in milliseconds
133 * @throws LockException
134 * will be thrown when the lock can not be acquired
135 */
136 public void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant,
137 long timeoutMSecs) throws LockException;
138
139 /**
140 * Most flexible way to acquire a lock on a resource. <br>
141 * <br>
142 * This method blocks and waits for the lock in case it is not avaiable. If
143 * there is a timeout or a deadlock or the thread is interrupted a
144 * LockException is thrown.
145 *
146 * @param ownerId
147 * a unique id identifying the entity that wants to acquire this
148 * lock
149 * @param resourceId
150 * the resource to get the level for
151 * @param targetLockLevel
152 * the lock level to acquire
153 * @param compatibility
154 * {@link GenericLock#COMPATIBILITY_NONE}if no additional compatibility is
155 * desired (same as reentrant set to false) ,
156 * {@link GenericLock#COMPATIBILITY_REENTRANT}if lock level by the same
157 * owner shall not affect compatibility (same as reentrant set to
158 * true), or {@link GenericLock#COMPATIBILITY_SUPPORT}if lock levels that
159 * are the same as the desired shall not affect compatibility, or
160 * finally {@link GenericLock#COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
161 * a combination of reentrant and support
162 * @param preferred
163 * in case this lock request is incompatible with existing ones
164 * and we wait, it shall be granted before other waiting requests
165 * that are not preferred
166 * @param timeoutMSecs
167 * specifies the maximum wait time in milliseconds
168 * @throws LockException
169 * will be thrown when the lock can not be acquired
170 */
171 public void lock(Object ownerId, Object resourceId, int targetLockLevel, int compatibility,
172 boolean preferred, long timeoutMSecs) throws LockException;
173
174 /**
175 * Starts a global timeout for an owner. This is especially usefull, when the owner is a
176 * transaction. After a global timeout occurs all of the owner's lock will be released and
177 * the owner will not be allowed to access any
178 * locks before before calling {@link #releaseAll(Object)}.
179 *
180 * @param ownerId
181 * a unique id identifying the entity that wants to acquire this
182 * lock
183 * @param timeoutMSecs
184 * specifies the global timeout in milliseconds
185 */
186 public void startGlobalTimeout(Object ownerId, long timeoutMSecs);
187
188 /**
189 * Gets the lock level held by certain owner on a certain resource.
190 *
191 * @param ownerId the id of the owner of the lock
192 * @param resourceId the resource to get the level for
193 */
194 public int getLevel(Object ownerId, Object resourceId);
195
196 /**
197 * Releases all locks for a certain resource held by a certain owner.
198 *
199 * @param ownerId the id of the owner of the lock
200 * @param resourceId the resource to releases the lock for
201 * @return <code>true</code> if the lock actually was released, <code>false</code> in case
202 * there was no lock held by the owner
203 */
204 public boolean release(Object ownerId, Object resourceId);
205
206 /**
207 * Releases all locks (partially) held by an owner.
208 *
209 * @param ownerId the id of the owner
210 */
211 public void releaseAll(Object ownerId);
212
213 /**
214 * Gets all locks (partially) held by an owner.
215 *
216 * @param ownerId the id of the owner
217 * @return all locks held by ownerId
218 */
219 public Set getAll(Object ownerId);
220
221
222 /**
223 * Gets an existing lock on the specified resource. If none exists it returns <code>null</code>.
224 *
225 * @param resourceId the resource to get the lock for
226 * @return the lock on the specified resource
227 *
228 */
229 public MultiLevelLock getLock(Object resourceId);
230
231 /**
232 * Removes the specified lock from the associated resource.
233 *
234 * <em>Caution:</em> This does not release the lock, but only moves it out
235 * of the scope of this manager. Use {@link #release(Object, Object)} for that.
236 *
237 * @param lock the lock to be removed
238 */
239 public void removeLock(MultiLevelLock lock);
240
241 }