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