001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.LockingPolicy
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw;
023:
024: import org.apache.derby.iapi.services.locks.Latch;
025:
026: import org.apache.derby.iapi.error.StandardException;
027:
028: /**
029: Any object that implements this interface can be used as a locking
030: policy for accessing a container.
031: <P>
032: The locking policy must use the defined lock qualifiers
033: (ContainerLock.CIS, RowLock.RS, etc.) and the standard lock manager.
034: (A locking policy that just performs no locking wouldn't need to use
035: these :-)
036: <P>
037: A locking policy must use the object that is an instance of Transaction
038: (originally obtained via startTransaction() in RawStoreFactory) as the
039: compatibilitySpace for the LockFactory calls.
040: <BR>
041: A locking policy must use the passed in transaction as the
042: compatability space and the lock group.
043: This chain (group) of locks has the following defined behaviour
044: <UL>
045: <LI>Locks are released at transaction.commit()
046: <LI>Locks are released at transaction.abort()
047: </UL>
048:
049:
050: <BR>
051: MT - Thread Safe
052:
053: @see ContainerHandle
054: @see RecordHandle
055: @see org.apache.derby.iapi.services.locks.LockFactory
056: @see org.apache.derby.iapi.services.locks.Lockable
057:
058: */
059:
060: public interface LockingPolicy {
061:
062: /**
063: No locking what so ever, isolation parameter will be ignored by
064: getLockingPolicy().
065:
066: @see RawStoreFactory
067: */
068: static final int MODE_NONE = 0;
069:
070: /**
071: Record level locking.
072: */
073: static final int MODE_RECORD = 1;
074:
075: /**
076: ContainerHandle level locking.
077: */
078: static final int MODE_CONTAINER = 2;
079:
080: /**
081: Called when a container is opened.
082:
083: @param t Transaction to associate lock with.
084: @param container Container to lock.
085: @param waitForLock Should lock request wait until granted?
086: @param forUpdate Should container be locked for update, or read?
087:
088: @return true if the lock was obtained, false if it wasn't.
089: False should only be returned if the waitForLock policy was set to
090: "false," and the lock was unavailable.
091:
092: @exception StandardException Standard Cloudscape error policy
093:
094: @see ContainerHandle
095:
096: */
097: public boolean lockContainer(Transaction t,
098: ContainerHandle container, boolean waitForLock,
099: boolean forUpdate) throws StandardException;
100:
101: /**
102: Called when a container is closed.
103:
104: @see ContainerHandle
105: @see ContainerHandle#close
106: */
107: public void unlockContainer(Transaction t, ContainerHandle container);
108:
109: /**
110: Called before a record is fetched.
111:
112: @param t Transaction to associate lock with.
113: @param container Open Container used to get record. Will be used
114: to row locks by the container they belong to.
115: @param record Record to lock.
116: @param waitForLock Should lock request wait until granted?
117: @param forUpdate Should container be locked for update, or read?
118:
119:
120: @exception StandardException Standard Cloudscape error policy
121:
122: @see Page
123:
124: */
125: public boolean lockRecordForRead(Transaction t,
126: ContainerHandle container, RecordHandle record,
127: boolean waitForLock, boolean forUpdate)
128: throws StandardException;
129:
130: /**
131: Lock a record while holding a page latch.
132:
133: @param latch Latch held.
134: @param record Record to lock.
135: @param forUpdate Should container be locked for update, or read?
136:
137:
138: @exception StandardException Standard Cloudscape error policy
139:
140: @see Page
141:
142: */
143: public void lockRecordForRead(Latch latch, RecordHandle record,
144: boolean forUpdate) throws StandardException;
145:
146: /**
147: Request a write lock which will be released immediately upon grant.
148:
149: @param t Transaction to associate lock with.
150: @param record Record to lock.
151: @param lockForPreviousKey Lock is for a previous key of a insert.
152: @param waitForLock Should lock request wait until granted?
153:
154: @return true if the lock was obtained, false if it wasn't.
155: False should only be returned if the waitForLock argument was set to
156: "false," and the lock was unavailable.
157:
158: @exception StandardException Standard Cloudscape error policy
159:
160: @see Page
161: */
162: public boolean zeroDurationLockRecordForWrite(Transaction t,
163: RecordHandle record, boolean lockForPreviousKey,
164: boolean waitForLock) throws StandardException;
165:
166: /**
167: Called before a record is inserted, updated or deleted.
168:
169: If zeroDuration is true then lock is released immediately after it
170: has been granted.
171:
172: @param t Transaction to associate lock with.
173: @param record Record to lock.
174: @param lockForInsert Lock is for an insert.
175: @param waitForLock Should lock request wait until granted?
176:
177: @return true if the lock was obtained, false if it wasn't.
178: False should only be returned if the waitForLock argument was set to
179: "false," and the lock was unavailable.
180:
181: @exception StandardException Standard Cloudscape error policy
182:
183: @see Page
184: */
185: public boolean lockRecordForWrite(Transaction t,
186: RecordHandle record, boolean lockForInsert,
187: boolean waitForLock) throws StandardException;
188:
189: /**
190: Lock a record for write while holding a page latch.
191:
192:
193: @param latch Page latch held.
194: @param record Record to lock.
195:
196: @exception StandardException Standard Cloudscape error policy
197:
198: @see Page
199: */
200: public void lockRecordForWrite(Latch latch, RecordHandle record)
201: throws StandardException;
202:
203: /**
204: Called after a record has been fetched.
205:
206: @exception StandardException Standard Cloudscape error policy
207:
208: @see Page
209:
210: */
211: public void unlockRecordAfterRead(Transaction t,
212: ContainerHandle container, RecordHandle record,
213: boolean forUpdate, boolean row_qualified)
214: throws StandardException;
215:
216: /**
217: Get the mode of this policy
218: */
219: public int getMode();
220: }
|