KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > services > locks > Lockable


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