Source code: org/apache/derby/iapi/services/locks/Lockable.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.services.locks.Lockable
4
5 Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.services.locks;
22
23 import java.util.Hashtable;
24
25 /**
26 Any object that needs to be locked must implement Lockable.
27 This allows a generic lock manager that can have locking policies
28 defined on a per-object basis.
29
30 A request to lock the object takes a qualifier, this qualifier may be
31 used the object to implement a complex locking policy, e.g. traditional
32 database shared, update and exclusive locks.
33 <P>
34 The lock manager uses this ordered protocol to determine if a lock request on a
35 Lockable <TT> L </TT> with qualifier <TT> Q1 </TT> in compatiblity space
36 <TT> CS1 </TT> can be granted:
37 <OL>
38 <LI>If no locks are held on <TT> L </TT> in any compatability space then the
39 request is granted.
40 <LI>If <TT>L.requestCompatible(Q1)</TT> returns true then the lock is granted.
41 <LI>Otherwise the request is granted if the following expression evaluates
42 to true for every other lock <TT>{ CSn, Qn}</TT> held on <TT> L </TT>
43 <UL>
44 <LI> <PRE> ( ( CSn == CS1 ) && L.lockerAlwaysCompatible() ) </PRE>
45 <LI> <PRE> || (L.reqestCompatible(Q1, Qn)) </PRE>
46 </UL>
47 </OL>
48 <BR>
49 If the request is granted then a call is made to <TT> L.lockEvent(CS1, Q1) </TT>.
50 <BR>
51 When the lock is released a call is made to <TT> L.unlockEvent(CS1, Q1) </TT>.
52 <P>
53 The lock manager uses equals() and hashCode() to identify unique Lockables.
54 <BR>
55 If the class implementing Lockable requires that each instance of class
56 correspond to a different locked object then the equals() method must test
57 equality via the reference equality test (==), this is the default behaviour
58 for equality.
59 <BR>
60 If the class implementing Lockable require that each instance of the class
61 that has the same value (as defined by the class) corresponds to a locked
62 object then its equals() method must reflect that, e.g. by testing equality
63 of its fields. In this case the first Lockable to be locked will be kept
64 by lock manager as the key for the lock. Thus even after the first caller
65 unlocks the obejct, its reference will still be kept by the lock manager.
66 Thus Lockable's that per value equality must be designed so that they
67 are never re-used for different lockable concepts.
68 <BR>
69 In either case the equals() method must accept a reference to an object of
70 a different type.
71 <BR>
72 As per standard hashtable rules the value returned by hashCode() must be in sync
73 with the equals() method.
74
75 <BR>
76 MT - Mutable - : single thread required, synchronization is provided by the lock manager.
77 If the class implementing Lockable uses value equality then it must have an immutable identity.
78 */
79
80 public interface Lockable {
81
82 /**
83 Note the fact the object is locked. Performs required actions
84 to ensure that unlockEvent() work correctly.
85 This method does not actually perform any locking of the
86 object, the locking mechanism is provided by the lock manager.
87 <P>
88 If the class supports multiple lockers of the object then this method
89 will be called once per locker, each with their own qualifier.
90 <P>
91 Must only be called by the lock manager. Synchronization will be handled
92 by the lock manager.
93 */
94 public void lockEvent(Latch lockInfo);
95
96 /**
97 Return true if the requested qualifier is compatible with the already granted
98 qualifier.
99 */
100 public boolean requestCompatible(Object requestedQualifier, Object grantedQualifier);
101
102 /**
103 Returns true if any lock request on a Lockable L in a compatibility space CS1 is compatible
104 with any other lock held on L in CS1.
105
106 */
107 public boolean lockerAlwaysCompatible();
108
109 /**
110 Note that the object has been unlocked
111 <P>
112 Must only be called by the lock manager. Synchronization will be handled
113 by the lock manager.
114 */
115 public void unlockEvent(Latch lockInfo);
116
117 /**
118 If this lockable object wants to participate in a diagnostic virtual
119 lock table, then put any relavent attributes of this lock into the
120 attributes list (the attribute must be an immutable object). The list
121 of attributes of interest to the virtual lock table can be found in
122 VirtualLockTable. The toString method will be called by the VirtualTable
123 on the attribute value for display.
124 <P>
125 @param flag use the bits in this int to decide if the user is
126 interested in this kind of lockable object. The bits are defined in
127 VirtualLockTable. For instance, the user may only ask
128 for TABLE_AND_ROWLOCK and if this is not a table or row lock, then
129 don't paritipate.
130 @param attributes if this decides to participate, put all relavent
131 attributes into the Hashtable. The complete list of interesting
132 attributes is listed in VirtualLockTable.
133 The following attributes must be present for all participating
134 lockables:
135 VirtualLockTable.LOCKNAME,
136 VirtualLockTable.LOCKTYPE,
137 either VirtualLockTable.CONTAINERID or VirtualLockTable.CONGLOMID,
138 <P>
139 MT - this routine must be MP safe, caller will not be single threading
140 the lock manager.
141 <P>
142 @return true if this object has diagnostic information to add to the
143 virtual lock table. If this object either does not want to participate
144 in the diagnostic virtual lock table or none of the attributes
145 requested are attributes of this lock, returns false.
146
147 @see VirtualLockTable
148 */
149 public boolean lockAttributes(int flag, Hashtable attributes);
150 }