KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > transaction > locking > MultiLevelLock2


1 /*
2  * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//transaction/src/java/org/apache/commons/transaction/locking/MultiLevelLock2.java,v 1.3 2005/01/09 23:56:07 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 /**
27  *
28  * Extended multi level lock. Compared to basic {@link MultiLevelLock} allows for more flexible
29  * locking including preference and more compatibility modes.
30  *
31  * @version $Revision$
32  * @see LockManager2
33  * @see MultiLevelLock
34  * @see GenericLock
35  * @since 1.1
36  */
37 public interface MultiLevelLock2 extends MultiLevelLock {
38
39     /**
40      * Compatibility mode: none reentrant. Lock level by the same owner <em>shall</em>
41      * affect compatibility.
42      */
43     public static final int COMPATIBILITY_NONE = 0;
44
45     /**
46      * Compatibility mode: reentrant. Lock level by the same owner <em>shall not</em>
47      * affect compatibility.
48      */
49     public static final int COMPATIBILITY_REENTRANT = 1;
50     
51     /**
52      * Compatibility mode: supporting. Lock levels that are the same as the
53      * desired <em>shall not</em> affect compatibility, but lock level held by the same
54      * owner <em>shall</em>.
55      */
56     public static final int COMPATIBILITY_SUPPORT = 2;
57
58     /**
59      * Compatibility mode: reentrant and supporting. Lock levels that are the same as the
60      * desired and lock levels held by the same
61      * owner <em>shall not</em> affect compatibility.
62      */
63     public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT = 3;
64     
65     /**
66      * Tests if a certain lock level is owned by an owner.
67      *
68      * @param ownerId
69      * a unique id identifying the entity that wants to check a
70      * certain lock level on this lock
71      * @param lockLevel
72      * the lock level to test
73      * @return <code>true</code> if the lock could be acquired at the time
74      * this method was called
75      */
76     public boolean has(Object JavaDoc ownerId, int lockLevel);
77     
78     /**
79      * Tests if a certain lock level <em>could</em> be acquired. This method
80      * tests only and does <em>not actually acquire</em> the lock.
81      *
82      * @param ownerId
83      * a unique id identifying the entity that wants to test a
84      * certain lock level on this lock
85      * @param targetLockLevel
86      * the lock level to acquire
87      * @param compatibility
88      * {@link #COMPATIBILITY_NONE}if no additional compatibility is
89      * desired (same as reentrant set to false) ,
90      * {@link #COMPATIBILITY_REENTRANT}if lock level by the same
91      * owner shall not affect compatibility (same as reentrant set to
92      * true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
93      * are the same as the desired shall not affect compatibility, or
94      * finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
95      * a combination of reentrant and support
96      * @return <code>true</code> if the lock could be acquired at the time
97      * this method was called
98      */
99     public boolean test(Object JavaDoc ownerId, int targetLockLevel, int compatibility);
100     
101     /**
102      * Tries to acquire a certain lock level on this lock. Does the same as
103      * {@link org.apache.commons.transaction.locking.MultiLevelLock#acquire(java.lang.Object, int, boolean, boolean, long)}
104      * except that it allows for different compatibility settings. There is an
105      * additional compatibility mode {@link #COMPATIBILITY_SUPPORT}that allows
106      * equal lock levels not to interfere with each other. This is like an
107      * additional shared compatibility and useful when you only want to make
108      * sure not to interfer with lowe levels, but are fine with the same.
109      *
110      * @param ownerId a unique id identifying the entity that wants to acquire a certain lock level on this lock
111      * @param targetLockLevel the lock level to acquire
112      * @param wait <code>true</code> if this method shall block when the desired lock level can not be acquired
113      * @param compatibility
114      * {@link #COMPATIBILITY_NONE}if no additional compatibility is
115      * desired (same as reentrant set to false) ,
116      * {@link #COMPATIBILITY_REENTRANT}if lock level by the same
117      * owner shall not affect compatibility (same as reentrant set to
118      * true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
119      * are the same as the desired shall not affect compatibility, or
120      * finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
121      * a combination of reentrant and support
122      *
123      * @param preferred
124      * in case this lock request is incompatible with existing ones
125      * and we wait, it shall be granted before other waiting requests
126      * that are not preferred
127      * @param timeoutMSecs if blocking is enabled by the <code>wait</code> parameter this specifies the maximum wait time in milliseconds
128      * @return <code>true</code> if the lock actually was acquired
129      * @throws InterruptedException when the thread waiting on this method is interrupted
130      *
131      */
132     public boolean acquire(Object JavaDoc ownerId, int targetLockLevel, boolean wait, int compatibility,
133             boolean preferred, long timeoutMSecs) throws InterruptedException JavaDoc;
134
135 }
136
Popular Tags