ConglomerateController


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