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