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