Source code: org/apache/derby/iapi/store/access/ConglomerateController.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.ConglomerateController
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.access;
22
23 import org.apache.derby.iapi.store.access.RowUtil;
24
25 import org.apache.derby.iapi.services.io.Storable;
26
27 import org.apache.derby.iapi.types.DataValueDescriptor;
28
29 import org.apache.derby.iapi.types.RowLocation;
30
31 import org.apache.derby.iapi.error.StandardException;
32 import org.apache.derby.iapi.services.io.FormatableBitSet;
33
34 import java.util.Properties;
35
36
37 /**
38
39 A conglomerate is an abstract storage structure (they
40 correspond to access methods). The ConglomerateController interface
41 is the interface that access manager clients can use to manipulate
42 the contents of the underlying conglomerate.
43 <p>
44 Each conglomerate holds a set of rows. Each row has a row location.
45 The conglomerate provides methods for:
46 <ul>
47 <li>
48 Inserting rows,
49 <li>
50 Fetching, deleting, and replacing entire rows by row location, and
51 <li>
52 fetching and updating individual columns of a row identified by row
53 location.
54 </ul>
55 <p>
56 Conglomerates do not provide any mechanism for associative access to
57 rows within the conglomerate; this type of access is provided by scans
58 via the ScanController interface.
59 <p>
60 Although all conglomerates have the same interface, they have different
61 implementations. The implementation of a conglomerate determines some
62 of its user-visible semantics; for example whether the rows are ordered
63 or what the types of the rows' columns must be. The implementation is
64 specified by an implementation id. Currently there are two implementations,
65 "heap", and "btree". The details of their behavior are specified in their
66 implementation documentation. (Currently, only "heap" is implemented).
67 <p>
68 All conglomerate operations are subject to the transactional isolation
69 of the transaction they were opened from. Transaction rollback will
70 close all conglomerates. Transaction commit will close all non-held
71 conglomerates.
72 <p>
73 Scans are opened from a TransactionController.
74 <P>
75 A ConglomerateController can handle partial rows. Partial rows
76 are described in RowUtil.
77
78 @see TransactionController#openConglomerate
79 @see RowUtil
80 */
81
82 public interface ConglomerateController extends ConglomPropertyQueryable
83 {
84 public static final int ROWISDUPLICATE = 1;
85
86 /**
87 * Close the conglomerate controller.
88 * <p>
89 * Close the conglomerate controller. Callers must not use
90 * the conglomerate controller after calling close. It is
91 * strongly recommended that callers clear out the reference
92 * after closing, e.g.,
93 * <p>
94 * <blockquote><pre>
95 * ConglomerateController cc;
96 * cc.close;
97 * cc = null;
98 * </pre></blockquote>
99 *
100 * @exception StandardException Standard exception policy.
101 **/
102 public void close()
103 throws StandardException;
104
105 /**
106 * Close conglomerate controller as part of terminating a transaction.
107 * <p>
108 * Use this call to close the conglomerate controller resources as part of
109 * committing or aborting a transaction. The normal close() routine may
110 * do some cleanup that is either unnecessary, or not correct due to the
111 * unknown condition of the controller following a transaction ending error.
112 * Use this call when closing all controllers as part of an abort of a
113 * transaction.
114 * <p)
115 * This call is meant to only be used internally by the Storage system,
116 * clients of the storage system should use the simple close() interface.
117 * <p>
118 * RESOLVE (mikem) - move this call to ConglomerateManager so it is
119 * obvious that non-access clients should not call this.
120 *
121 * @param closeHeldScan If true, means to close controller even if
122 * it has been opened to be kept opened
123 * across commit. This is
124 * used to close these controllers on abort.
125 *
126 * @return boolean indicating that the close has resulted in a real close
127 * of the controller. A held scan will return false if
128 * called by closeForEndTransaction(false), otherwise it
129 * will return true. A non-held scan will always return
130 * true.
131 *
132 * @exception StandardException Standard exception policy.
133 **/
134 boolean closeForEndTransaction(boolean closeHeldScan)
135 throws StandardException;
136
137 /**
138 Check consistency of a conglomerate.
139
140 Checks the consistency of the data within a given conglomerate, does not
141 check consistency external to the conglomerate (ie. does not check that
142 base table row pointed at by a secondary index actually exists).
143
144 Raises a StandardException on first consistency problem.
145
146 @exception StandardException Standard exception policy.
147 **/
148 void checkConsistency()
149 throws StandardException;
150
151 /**
152 Delete a row from the conglomerate.
153 @return Returns true if delete was successful, false if the record pointed
154 at no longer represents a valid record.
155 @exception StandardException Standard exception policy.
156 **/
157 boolean delete(RowLocation loc)
158 throws StandardException;
159
160 /**
161 * Fetch the (partial) row at the given location.
162 * <p>
163 *
164 * @param loc The "RowLocation" which describes the exact row
165 * to fetch from the table.
166 * @param destRow The row to read the data into.
167 * @param validColumns A description of which columns to return from
168 * row on the page into "destRow." destRow
169 * and validColumns work together to
170 * describe the row to be returned by the fetch -
171 * see RowUtil for description of how these three
172 * parameters work together to describe a fetched
173 * "row".
174 *
175 * @return Returns true if fetch was successful, false if the record
176 * pointed at no longer represents a valid record.
177 *
178 * @exception StandardException Standard exception policy.
179 *
180 * @see RowUtil
181 **/
182 boolean fetch(
183 RowLocation loc,
184 DataValueDescriptor[] destRow,
185 FormatableBitSet validColumns)
186 throws StandardException;
187
188 /**
189 * Fetch the (partial) row at the given location.
190 * <p>
191 *
192 * @param loc The "RowLocation" which describes the exact row
193 * to fetch from the table.
194 * @param destRow The row to read the data into.
195 * @param validColumns A description of which columns to return from
196 * row on the page into "destRow." destRow
197 * and validColumns work together to
198 * describe the row to be returned by the fetch -
199 * see RowUtil for description of how these three
200 * parameters work together to describe a fetched
201 * "row".
202 * @param waitForLock If false, then the call will throw a lock timeout
203 * exception immediately, if the lock can not be
204 * granted without waiting. If true call will
205 * act exactly as fetch() interface with no
206 * waitForLock parameter.
207 *
208 * @return Returns true if fetch was successful, false if the record
209 * pointed at no longer represents a valid record.
210 *
211 * @exception StandardException Standard exception policy.
212 *
213 * @see RowUtil
214 **/
215 boolean fetch(
216 RowLocation loc,
217 DataValueDescriptor[] destRow,
218 FormatableBitSet validColumns,
219 boolean waitForLock)
220 throws StandardException;
221
222 /**
223 * Fetch the (partial) row at the given location.
224 * <p>
225 * RESOLVE - interface NOT SUPPORTED YET!!!!!
226 *
227 * @param loc The "RowLocation" which describes the exact row
228 * to fetch from the table.
229 * @param destRow The row to read the data into.
230 * @param validColumns A description of which columns to return from
231 * row on the page into "destRow." destRow,
232 * and validColumns work together to
233 * describe the row to be returned by the fetch -
234 * see RowUtil for description of how these three
235 * parameters work together to describe a fetched
236 * "row".
237 * @param qualifier An array of qualifiers which,
238 * applied to each key, restrict the rows returned
239 * by the scan. Rows for which any one of the
240 * qualifiers returns false are not returned by
241 * the scan. If null, all rows are returned.
242 * Qualifiers can only reference columns which are
243 * included in the scanColumnList. The column id
244 * that a qualifier returns in the column id the
245 * table, not the column id in the partial row being
246 * returned. See openScan() for description of how
247 * qualifiers are applied.
248 *
249 * @return Returns true if fetch was successful, false if the record
250 * pointed at no longer represents a valid record.
251 *
252 * @exception StandardException Standard exception policy.
253 *
254 * @see RowUtil
255 **/
256 /*
257 boolean fetch(
258 RowLocation loc,
259 DataValueDescriptor[] destRow,
260 FormatableBitSet validColumns,
261 Qualifier[][] qualifier)
262 throws StandardException;
263 */
264
265 /**
266 Insert a row into the conglomerate.
267
268 @param row The row to insert into the conglomerate. The stored
269 representations of the row's columns are copied into a new row
270 somewhere in the conglomerate.
271
272 @return Returns 0 if insert succeeded. Returns
273 ConglomerateController.ROWISDUPLICATE if conglomerate supports uniqueness
274 checks and has been created to disallow duplicates, and the row inserted
275 had key columns which were duplicate of a row already in the table. Other
276 insert failures will raise StandardException's.
277
278 @exception StandardException Standard exception policy.
279 @see RowUtil
280 **/
281 int insert(DataValueDescriptor[] row)
282 throws StandardException;
283
284 /**
285 * insert row and fetch it's row location in one operation.
286 * <p>
287 * Insert a row into the conglomerate, and store its location in
288 * the provided destination row location. The row location must be of the
289 * correct type for this conglomerate (a new row location of the correct
290 * type can be obtained from newRowLocationTemplate()).
291 *
292 * @param row The row to insert into the conglomerate. The
293 * stored representations of the row's columns are
294 * copied into a new row somewhere in the conglomerate.
295 *
296 * @param destRowLocation The rowlocation to read the inserted row location
297 * into.
298 *
299 * @exception StandardException Standard exception policy.
300 *
301 * @see RowUtil
302 **/
303 void insertAndFetchLocation(
304 DataValueDescriptor[] row,
305 RowLocation destRowLocation)
306 throws StandardException;
307
308 /**
309 Return whether this is a keyed conglomerate.
310 **/
311 boolean isKeyed();
312
313
314 public static final int LOCK_READ = (0x00000000);
315 public static final int LOCK_UPD = (0x00000001);
316 public static final int LOCK_INS = (0x00000002);
317 public static final int LOCK_INS_PREVKEY = (0x00000004);
318 public static final int LOCK_UPDATE_LOCKS = (0x00000008);
319
320 /**
321 * Lock the given row location.
322 * <p>
323 * Should only be called by access.
324 * <p>
325 * This call can be made on a ConglomerateController that was opened
326 * for locking only.
327 * <p>
328 * RESOLVE (mikem) - move this call to ConglomerateManager so it is
329 * obvious that non-access clients should not call this.
330 *
331 * @return true if lock was granted, only can be false if wait was false.
332 *
333 * @param loc The "RowLocation" of the exact row to lock.
334 * @param lock_oper For what operation are we requesting the lock, this
335 * should be one of the following 4 options:
336 * LOCK_READ [read lock],
337 * (LOCK_INS | LOCK_UPD) [ lock for insert],
338 * (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for
339 * previous key to insert],
340 * (LOCK_UPD) [lock for delete or replace]
341 * (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for
342 * update, will upgrade lock later if actual update
343 * is take place]
344 * @param wait Should the lock call wait to be granted?
345 * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,
346 * then lock will be released immediately after being
347 * granted.
348 *
349 * @exception StandardException Standard exception policy.
350 **/
351 boolean lockRow(
352 RowLocation loc,
353 int lock_oper,
354 boolean wait,
355 int lock_duration)
356 throws StandardException;
357
358 /**
359 * Lock the given record id/page num pair.
360 * <p>
361 * Should only be called by access, to lock "special" locks formed from
362 * the Recordhandle.* reserved constants for page specific locks.
363 * <p>
364 * This call can be made on a ConglomerateController that was opened
365 * for locking only.
366 * <p>
367 * RESOLVE (mikem) - move this call to ConglomerateManager so it is
368 * obvious that non-access clients should not call this.
369 *
370 * @return true if lock was granted, only can be false if wait was false.
371 *
372 * @param page_num page number of record to lock.
373 * @param record_id record id of record to lock.
374 * @param lock_oper For what operation are we requesting the lock, this
375 * should be one of the following 4 options:
376 * LOCK_READ [read lock],
377 * (LOCK_INS | LOCK_UPD) [ lock for insert],
378 * (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for
379 * previous key to insert],
380 * (LOCK_UPD) [lock for delete or replace]
381 * (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for
382 * update, will upgrade lock later if actual update
383 * is take place]
384 * @param wait Should the lock call wait to be granted?
385 * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,
386 * then lock will be released immediately after being
387 * granted.
388 *
389 * @exception StandardException Standard exception policy.
390 **/
391 boolean lockRow(
392 long page_num,
393 int record_id,
394 int lock_oper,
395 boolean wait,
396 int lock_duration)
397 throws StandardException;
398
399 /**
400 * UnLock the given row location.
401 * <p>
402 * Should only be called by access.
403 * <p>
404 * This call can be made on a ConglomerateController that was opened
405 * for locking only.
406 * <p>
407 * RESOLVE (mikem) - move this call to ConglomerateManager so it is
408 * obvious that non-access clients should not call this.
409 *
410 * @param loc The "RowLocation" which describes the row to unlock.
411 * @param forUpdate Row was locked for read or update.
412 * @param row_qualified Row was qualified and returned to the user.
413 *
414 * @exception StandardException Standard exception policy.
415 **/
416 public void unlockRowAfterRead(
417 RowLocation loc,
418 boolean forUpdate,
419 boolean row_qualified)
420 throws StandardException;
421
422 /**
423 Return a row location object of the correct type to be
424 used in calls to insertAndFetchLocation.
425 @exception StandardException Standard exception policy.
426 **/
427 RowLocation newRowLocationTemplate()
428 throws StandardException;
429
430 /**
431 Replace the (partial) row at the given location.
432 @return true if update was successful, returns false if the update
433 fails because the record pointed at no longer represents a valid record.
434 @exception StandardException Standard exception policy.
435 @see RowUtil
436 **/
437 boolean replace(
438 RowLocation loc,
439 DataValueDescriptor[] row,
440 FormatableBitSet validColumns)
441 throws StandardException;
442
443 /**
444 Get information about space used by the conglomerate.
445 **/
446 SpaceInfo getSpaceInfo()
447 throws StandardException;
448
449 /**
450 * Dump debugging output to error log.
451 * <p>
452 * Dump information about the conglomerate to error log.
453 * This is only for debugging purposes, does nothing in a delivered
454 * system, currently.
455 *
456 * @exception StandardException Standard exception policy.
457 **/
458 void debugConglomerate()
459 throws StandardException;
460 }