001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.transaction.locking;
018
019 import java.util.Set;
020
021 /**
022 * Extended version of a lock manager that also has global knowledge or all locks and should be
023 * used as a delegate for all locking requests. This allows for things like deadlock detection.
024 *
025 * @version $Id: LockManager2.java 493628 2007-01-07 01:42:48Z joerg $
026 * @see MultiLevelLock
027 * @see MultiLevelLock2
028 * @see LockManager
029 * @see GenericLockManager
030 * @see GenericLock
031 * @since 1.1
032 */
033 public interface LockManager2 {
034
035 /**
036 * Determines if a lock is owner by an owner. <br>
037 *
038 * @param ownerId
039 * a unique id identifying the entity that wants to check this
040 * lock
041 * @param resourceId
042 * the resource to get the level for
043 * @param lockLevel
044 * the lock level to check
045 * @return <code>true</code> if the owner has the lock, <code>false</code> otherwise
046 *
047 */
048 public boolean hasLock(Object ownerId, Object resourceId, int lockLevel);
049
050 /**
051 * Determines if a lock <em>could</em> be acquire <em>without</em> actually acquiring it. <br>
052 * <br>
053 * This method does not block, but immediatly returns.
054 *
055 * @param ownerId
056 * a unique id identifying the entity that wants to check this
057 * lock
058 * @param resourceId
059 * the resource to get the level for
060 * @param targetLockLevel
061 * the lock level to check
062 * @param reentrant
063 * <code>true</code> if this request shall not be influenced by
064 * other locks held by the same owner
065 * @return <code>true</code> if the lock could be acquired, <code>false</code> otherwise
066 *
067 */
068 public boolean checkLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
069
070 /**
071 * Tries to acquire a lock on a resource. <br>
072 * <br>
073 * This method does not block, but immediatly returns. If a lock is not
074 * available <code>false</code> will be returned.
075 *
076 * @param ownerId
077 * a unique id identifying the entity that wants to acquire this
078 * lock
079 * @param resourceId
080 * the resource to get the level for
081 * @param targetLockLevel
082 * the lock level to acquire
083 * @param reentrant
084 * <code>true</code> if this request shall not be influenced by
085 * other locks held by the same owner
086 * @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
087 *
088 */
089 public boolean tryLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
090
091 /**
092 * Tries to acquire a lock on a resource. <br>
093 * <br>
094 * This method blocks and waits for the lock in case it is not avaiable. If
095 * there is a timeout or a deadlock or the thread is interrupted a
096 * LockException is thrown.
097 *
098 * @param ownerId
099 * 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 }