Coverage Report

Coverage Report - org.apache.commons.transaction.locking.LockManager2

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.transaction.locking;
 
 import java.util.Set;
 
 /**
  * Extended version of a lock manager that also has global knowledge or all locks and should be
  * used as a delegate for all locking requests. This allows for things like deadlock detection.
  * 
  * @version $Id: LockManager2.java 493628 2007-01-07 01:42:48Z joerg $
  * @see MultiLevelLock
  * @see MultiLevelLock2
  * @see LockManager
  * @see GenericLockManager
  * @see GenericLock
  * @since 1.1
  */
 public interface LockManager2 {
 
     /**
      * Determines if a lock is owner by an owner. <br>
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to check this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param lockLevel
      *            the lock level to check
      * @return <code>true</code> if the owner has the lock, <code>false</code> otherwise
      *  
      */
     public boolean hasLock(Object ownerId, Object resourceId, int lockLevel);
 
     /**
      * Determines if a lock <em>could</em> be acquire <em>without</em> actually acquiring it. <br>
      * <br>
      * This method does not block, but immediatly returns.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to check this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param targetLockLevel
      *            the lock level to check
      * @param reentrant
      *            <code>true</code> if this request shall not be influenced by
      *            other locks held by the same owner
      * @return <code>true</code> if the lock could be acquired, <code>false</code> otherwise
      *  
      */
     public boolean checkLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
 
     /**
      * Tries to acquire a lock on a resource. <br>
      * <br>
      * This method does not block, but immediatly returns. If a lock is not
      * available <code>false</code> will be returned.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to acquire this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param targetLockLevel
      *            the lock level to acquire
      * @param reentrant
      *            <code>true</code> if this request shall not be influenced by
      *            other locks held by the same owner
      * @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
      *  
      */
     public boolean tryLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant);
 
     /**
      * Tries to acquire a lock on a resource. <br>
      * <br>
      * This method blocks and waits for the lock in case it is not avaiable. If
      * there is a timeout or a deadlock or the thread is interrupted a
      * LockException is thrown.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to acquire this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param targetLockLevel
      *            the lock level to acquire
      * @param reentrant
      *            <code>true</code> if this request shall not be blocked by
      *            other locks held by the same owner
      * @throws LockException
      *             will be thrown when the lock can not be acquired
      */
     public void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)
             throws LockException;
 
     /**
      * Tries to acquire a lock on a resource. <br>
      * <br>
      * This method blocks and waits for the lock in case it is not avaiable. If
      * there is a timeout or a deadlock or the thread is interrupted a
      * LockException is thrown.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to acquire this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param targetLockLevel
      *            the lock level to acquire
      * @param reentrant
      *            <code>true</code> if this request shall not be blocked by
      *            other locks held by the same owner
      * @param timeoutMSecs
      *            specifies the maximum wait time in milliseconds
      * @throws LockException
      *             will be thrown when the lock can not be acquired
      */
     public void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant,
             long timeoutMSecs) throws LockException;
 
     /**
      * Most flexible way to acquire a lock on a resource. <br>
      * <br>
      * This method blocks and waits for the lock in case it is not avaiable. If
      * there is a timeout or a deadlock or the thread is interrupted a
      * LockException is thrown.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to acquire this
      *            lock
      * @param resourceId
      *            the resource to get the level for
      * @param targetLockLevel
      *            the lock level to acquire
      * @param compatibility
      *            {@link GenericLock#COMPATIBILITY_NONE}if no additional compatibility is
      *            desired (same as reentrant set to false) ,
      *            {@link GenericLock#COMPATIBILITY_REENTRANT}if lock level by the same
      *            owner shall not affect compatibility (same as reentrant set to
      *            true), or {@link GenericLock#COMPATIBILITY_SUPPORT}if lock levels that
      *            are the same as the desired shall not affect compatibility, or
      *            finally {@link GenericLock#COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
      *            a combination of reentrant and support
      * @param preferred
      *            in case this lock request is incompatible with existing ones
      *            and we wait, it shall be granted before other waiting requests
      *            that are not preferred
      * @param timeoutMSecs
      *            specifies the maximum wait time in milliseconds
      * @throws LockException
      *             will be thrown when the lock can not be acquired
      */
     public void lock(Object ownerId, Object resourceId, int targetLockLevel, int compatibility,
             boolean preferred, long timeoutMSecs) throws LockException;
 
     /**
      * Starts a global timeout for an owner. This is especially usefull, when the owner is a 
      * transaction. After a global timeout occurs all of the owner's lock will be released and 
      * the owner will not be allowed to access any
      * locks before before calling {@link #releaseAll(Object)}.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to acquire this
      *            lock
      * @param timeoutMSecs
      *            specifies the global timeout in milliseconds
      */
     public void startGlobalTimeout(Object ownerId, long timeoutMSecs);
     
     /**
      * Gets the lock level held by certain owner on a certain resource.
      * 
      * @param ownerId the id of the owner of the lock
      * @param resourceId the resource to get the level for
      */
     public int getLevel(Object ownerId, Object resourceId);
 
     /**
      * Releases all locks for a certain resource held by a certain owner.
      * 
      * @param ownerId the id of the owner of the lock
      * @param resourceId the resource to releases the lock for
      * @return <code>true</code> if the lock actually was released, <code>false</code> in case
      * there was no lock held by the owner
      */
     public boolean release(Object ownerId, Object resourceId);
 
     /**
      * Releases all locks (partially) held by an owner.
      * 
      * @param ownerId the id of the owner
      */
     public void releaseAll(Object ownerId);
     
     /**
      * Gets all locks (partially) held by an owner.
      * 
      * @param ownerId the id of the owner
      * @return all locks held by ownerId
      */
     public Set getAll(Object ownerId);
 
     
     /**
      * Gets an existing lock on the specified resource. If none exists it returns <code>null</code>. 
      * 
      * @param resourceId the resource to get the lock for
      * @return the lock on the specified resource
      * 
      */
     public MultiLevelLock getLock(Object resourceId);
 
     /**
      * Removes the specified lock from the associated resource. 
      * 
      * <em>Caution:</em> This does not release the lock, but only moves it out
      * of the scope of this manager. Use {@link #release(Object, Object)} for that.
      * 
      * @param lock the lock to be removed
      */
     public void removeLock(MultiLevelLock lock);
 
 }

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		}