Source code: org/apache/derby/iapi/store/raw/LockingPolicy.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.raw.LockingPolicy
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.store.raw;
22
23 import org.apache.derby.iapi.services.locks.Latch;
24
25 import org.apache.derby.iapi.error.StandardException;
26
27 /**
28 Any object that implements this interface can be used as a locking
29 policy for accessing a container.
30 <P>
31 The locking policy must use the defined lock qualifiers
32 (ContainerLock.CIS, RowLock.RS, etc.) and the standard lock manager.
33 (A locking policy that just performs no locking wouldn't need to use
34 these :-)
35 <P>
36 A locking policy must use the object that is an instance of Transaction
37 (originally obtained via startTransaction() in RawStoreFactory) as the
38 compatibilitySpace for the LockFactory calls.
39 <BR>
40 A locking policy must use the passed in transaction as the
41 compatability space and the lock group.
42 This chain (group) of locks has the following defined behaviour
43 <UL>
44 <LI>Locks are released at transaction.commit()
45 <LI>Locks are released at transaction.abort()
46 </UL>
47
48
49 <BR>
50 MT - Thread Safe
51
52 @see ContainerHandle
53 @see RecordHandle
54 @see org.apache.derby.iapi.services.locks.LockFactory
55 @see org.apache.derby.iapi.services.locks.Lockable
56
57 */
58
59 public interface LockingPolicy {
60
61 /**
62 No locking what so ever, isolation parameter will be ignored by
63 getLockingPolicy().
64
65 @see RawStoreFactory
66 */
67 static final int MODE_NONE = 0;
68
69 /**
70 Record level locking.
71 */
72 static final int MODE_RECORD = 1;
73
74 /**
75 ContainerHandle level locking.
76 */
77 static final int MODE_CONTAINER = 2;
78
79 /**
80 Called when a container is opened.
81
82 @param t Transaction to associate lock with.
83 @param container Container to lock.
84 @param waitForLock Should lock request wait until granted?
85 @param forUpdate Should container be locked for update, or read?
86
87 @return true if the lock was obtained, false if it wasn't.
88 False should only be returned if the waitForLock policy was set to
89 "false," and the lock was unavailable.
90
91 @exception StandardException Standard Cloudscape error policy
92
93 @see ContainerHandle
94
95 */
96 public boolean lockContainer(
97 Transaction t,
98 ContainerHandle container,
99 boolean waitForLock,
100 boolean forUpdate)
101 throws StandardException;
102
103 /**
104 Called when a container is closed.
105
106 @see ContainerHandle
107 @see ContainerHandle#close
108 */
109 public void unlockContainer(
110 Transaction t,
111 ContainerHandle container);
112
113 /**
114 Called before a record is fetched.
115
116 @param t Transaction to associate lock with.
117 @param container Open Container used to get record. Will be used
118 to row locks by the container they belong to.
119 @param record Record to lock.
120 @param waitForLock Should lock request wait until granted?
121 @param forUpdate Should container be locked for update, or read?
122
123
124 @exception StandardException Standard Cloudscape error policy
125
126 @see Page
127
128 */
129 public boolean lockRecordForRead(
130 Transaction t,
131 ContainerHandle container,
132 RecordHandle record,
133 boolean waitForLock,
134 boolean forUpdate)
135 throws StandardException;
136
137
138 /**
139 Lock a record while holding a page latch.
140
141 @param latch Latch held.
142 @param record Record to lock.
143 @param forUpdate Should container be locked for update, or read?
144
145
146 @exception StandardException Standard Cloudscape error policy
147
148 @see Page
149
150 */
151 public void lockRecordForRead(
152 Latch latch,
153 RecordHandle record,
154 boolean forUpdate)
155 throws StandardException;
156
157 /**
158 Request a write lock which will be released immediately upon grant.
159
160 @param t Transaction to associate lock with.
161 @param record Record to lock.
162 @param lockForPreviousKey Lock is for a previous key of a insert.
163 @param waitForLock Should lock request wait until granted?
164
165 @return true if the lock was obtained, false if it wasn't.
166 False should only be returned if the waitForLock argument was set to
167 "false," and the lock was unavailable.
168
169 @exception StandardException Standard Cloudscape error policy
170
171 @see Page
172 */
173 public boolean zeroDurationLockRecordForWrite(
174 Transaction t,
175 RecordHandle record,
176 boolean lockForPreviousKey,
177 boolean waitForLock)
178 throws StandardException;
179
180 /**
181 Called before a record is inserted, updated or deleted.
182
183 If zeroDuration is true then lock is released immediately after it
184 has been granted.
185
186 @param t Transaction to associate lock with.
187 @param record Record to lock.
188 @param lockForInsert Lock is for an insert.
189 @param waitForLock Should lock request wait until granted?
190
191 @return true if the lock was obtained, false if it wasn't.
192 False should only be returned if the waitForLock argument was set to
193 "false," and the lock was unavailable.
194
195 @exception StandardException Standard Cloudscape error policy
196
197 @see Page
198 */
199 public boolean lockRecordForWrite(
200 Transaction t,
201 RecordHandle record,
202 boolean lockForInsert,
203 boolean waitForLock)
204 throws StandardException;
205
206 /**
207 Lock a record for write while holding a page latch.
208
209
210 @param latch Page latch held.
211 @param record Record to lock.
212
213 @exception StandardException Standard Cloudscape error policy
214
215 @see Page
216 */
217 public void lockRecordForWrite(
218 Latch latch,
219 RecordHandle record)
220 throws StandardException;
221 /**
222 Called after a record has been fetched.
223
224 @exception StandardException Standard Cloudscape error policy
225
226 @see Page
227
228 */
229 public void unlockRecordAfterRead(
230 Transaction t,
231 ContainerHandle container,
232 RecordHandle record,
233 boolean forUpdate,
234 boolean row_qualified)
235 throws StandardException;
236
237
238 /**
239 Get the mode of this policy
240 */
241 public int getMode();
242 }