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,
049: int lockLevel);
050:
051: /**
052: * Determines if a lock <em>could</em> be acquire <em>without</em> actually acquiring it. <br>
053: * <br>
054: * This method does not block, but immediatly returns.
055: *
056: * @param ownerId
057: * a unique id identifying the entity that wants to check this
058: * lock
059: * @param resourceId
060: * the resource to get the level for
061: * @param targetLockLevel
062: * the lock level to check
063: * @param reentrant
064: * <code>true</code> if this request shall not be influenced by
065: * other locks held by the same owner
066: * @return <code>true</code> if the lock could be acquired, <code>false</code> otherwise
067: *
068: */
069: public boolean checkLock(Object ownerId, Object resourceId,
070: int targetLockLevel, boolean reentrant);
071:
072: /**
073: * Tries to acquire a lock on a resource. <br>
074: * <br>
075: * This method does not block, but immediatly returns. If a lock is not
076: * available <code>false</code> will be returned.
077: *
078: * @param ownerId
079: * a unique id identifying the entity that wants to acquire this
080: * lock
081: * @param resourceId
082: * the resource to get the level for
083: * @param targetLockLevel
084: * the lock level to acquire
085: * @param reentrant
086: * <code>true</code> if this request shall not be influenced by
087: * other locks held by the same owner
088: * @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
089: *
090: */
091: public boolean tryLock(Object ownerId, Object resourceId,
092: int targetLockLevel, boolean reentrant);
093:
094: /**
095: * Tries to acquire a lock on a resource. <br>
096: * <br>
097: * This method blocks and waits for the lock in case it is not avaiable. If
098: * there is a timeout or a deadlock or the thread is interrupted a
099: * LockException is thrown.
100: *
101: * @param ownerId
102: * a unique id identifying the entity that wants to acquire this
103: * lock
104: * @param resourceId
105: * the resource to get the level for
106: * @param targetLockLevel
107: * the lock level to acquire
108: * @param reentrant
109: * <code>true</code> if this request shall not be blocked by
110: * other locks held by the same owner
111: * @throws LockException
112: * will be thrown when the lock can not be acquired
113: */
114: public void lock(Object ownerId, Object resourceId,
115: int targetLockLevel, boolean reentrant)
116: throws LockException;
117:
118: /**
119: * Tries to acquire a lock on a resource. <br>
120: * <br>
121: * This method blocks and waits for the lock in case it is not avaiable. If
122: * there is a timeout or a deadlock or the thread is interrupted a
123: * LockException is thrown.
124: *
125: * @param ownerId
126: * a unique id identifying the entity that wants to acquire this
127: * lock
128: * @param resourceId
129: * the resource to get the level for
130: * @param targetLockLevel
131: * the lock level to acquire
132: * @param reentrant
133: * <code>true</code> if this request shall not be blocked by
134: * other locks held by the same owner
135: * @param timeoutMSecs
136: * specifies the maximum wait time in milliseconds
137: * @throws LockException
138: * will be thrown when the lock can not be acquired
139: */
140: public void lock(Object ownerId, Object resourceId,
141: int targetLockLevel, boolean reentrant, long timeoutMSecs)
142: throws LockException;
143:
144: /**
145: * Most flexible way to acquire a lock on a resource. <br>
146: * <br>
147: * This method blocks and waits for the lock in case it is not avaiable. If
148: * there is a timeout or a deadlock or the thread is interrupted a
149: * LockException is thrown.
150: *
151: * @param ownerId
152: * a unique id identifying the entity that wants to acquire this
153: * lock
154: * @param resourceId
155: * the resource to get the level for
156: * @param targetLockLevel
157: * the lock level to acquire
158: * @param compatibility
159: * {@link GenericLock#COMPATIBILITY_NONE}if no additional compatibility is
160: * desired (same as reentrant set to false) ,
161: * {@link GenericLock#COMPATIBILITY_REENTRANT}if lock level by the same
162: * owner shall not affect compatibility (same as reentrant set to
163: * true), or {@link GenericLock#COMPATIBILITY_SUPPORT}if lock levels that
164: * are the same as the desired shall not affect compatibility, or
165: * finally {@link GenericLock#COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
166: * a combination of reentrant and support
167: * @param preferred
168: * in case this lock request is incompatible with existing ones
169: * and we wait, it shall be granted before other waiting requests
170: * that are not preferred
171: * @param timeoutMSecs
172: * specifies the maximum wait time in milliseconds
173: * @throws LockException
174: * will be thrown when the lock can not be acquired
175: */
176: public void lock(Object ownerId, Object resourceId,
177: int targetLockLevel, int compatibility, boolean preferred,
178: long timeoutMSecs) throws LockException;
179:
180: /**
181: * Starts a global timeout for an owner. This is especially usefull, when the owner is a
182: * transaction. After a global timeout occurs all of the owner's lock will be released and
183: * the owner will not be allowed to access any
184: * locks before before calling {@link #releaseAll(Object)}.
185: *
186: * @param ownerId
187: * a unique id identifying the entity that wants to acquire this
188: * lock
189: * @param timeoutMSecs
190: * specifies the global timeout in milliseconds
191: */
192: public void startGlobalTimeout(Object ownerId, long timeoutMSecs);
193:
194: /**
195: * Gets the lock level held by certain owner on a certain resource.
196: *
197: * @param ownerId the id of the owner of the lock
198: * @param resourceId the resource to get the level for
199: */
200: public int getLevel(Object ownerId, Object resourceId);
201:
202: /**
203: * Releases all locks for a certain resource held by a certain owner.
204: *
205: * @param ownerId the id of the owner of the lock
206: * @param resourceId the resource to releases the lock for
207: * @return <code>true</code> if the lock actually was released, <code>false</code> in case
208: * there was no lock held by the owner
209: */
210: public boolean release(Object ownerId, Object resourceId);
211:
212: /**
213: * Releases all locks (partially) held by an owner.
214: *
215: * @param ownerId the id of the owner
216: */
217: public void releaseAll(Object ownerId);
218:
219: /**
220: * Gets all locks (partially) held by an owner.
221: *
222: * @param ownerId the id of the owner
223: * @return all locks held by ownerId
224: */
225: public Set getAll(Object ownerId);
226:
227: /**
228: * Gets an existing lock on the specified resource. If none exists it returns <code>null</code>.
229: *
230: * @param resourceId the resource to get the lock for
231: * @return the lock on the specified resource
232: *
233: */
234: public MultiLevelLock getLock(Object resourceId);
235:
236: /**
237: * Removes the specified lock from the associated resource.
238: *
239: * <em>Caution:</em> This does not release the lock, but only moves it out
240: * of the scope of this manager. Use {@link #release(Object, Object)} for that.
241: *
242: * @param lock the lock to be removed
243: */
244: public void removeLock(MultiLevelLock lock);
245:
246: }
|