001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.conglomerate.Conglomerate
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.conglomerate;
023:
024: import org.apache.derby.iapi.error.StandardException;
025: import org.apache.derby.iapi.store.access.ConglomerateController;
026: import org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo;
027: import org.apache.derby.iapi.store.access.Qualifier;
028: import org.apache.derby.iapi.store.access.RowLocationRetRowSource;
029: import org.apache.derby.iapi.store.access.StoreCostController;
030: import org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo;
031: import org.apache.derby.iapi.store.access.TransactionController;
032: import org.apache.derby.iapi.store.raw.ContainerKey;
033:
034: import org.apache.derby.iapi.store.raw.LockingPolicy;
035: import org.apache.derby.iapi.store.raw.Transaction;
036:
037: import org.apache.derby.iapi.types.DataValueDescriptor;
038:
039: import org.apache.derby.iapi.services.io.Storable;
040: import org.apache.derby.iapi.services.io.FormatableBitSet;
041:
042: /**
043:
044: A conglomerate is an abstract storage structure (they
045: correspond to access methods). The Conglomerate interface
046: corresponds to a single instance of a conglomerate. In
047: other words, for each conglomerate in the system, there
048: will be one object implementing Conglomerate.
049: <P>
050: The Conglomerate interface is implemented by each access method.
051: The implementation must maintain enough information to properly
052: open the conglomerate and scans, and to drop the conglomerate.
053: This information typically will include the id of the container
054: or containers in which the conglomerate is stored, and my also
055: include property information.
056: <P>
057: Conglomerates are created by a conglomerate factory. The access
058: manager stores them in a directory (which is why they implement
059: Storable).
060:
061: **/
062:
063: public interface Conglomerate extends Storable, DataValueDescriptor {
064:
065: /**
066: * Add a column to the conglomerate.
067: * <p>
068: * This routine update's the in-memory object version of the
069: * Conglomerate to have one more column of the type described by the
070: * input template column.
071: *
072: * Note that not all conglomerates may support this feature.
073: *
074: * @param xact_manager The TransactionController under which this
075: * operation takes place.
076: * @param column_id The column number to add this column at.
077: * @param template_column An instance of the column to be added to table.
078: *
079: * @exception StandardException Standard exception policy.
080: **/
081: public void addColumn(TransactionManager xact_manager,
082: int column_id, Storable template_column)
083: throws StandardException;
084:
085: /**
086: * Drop this conglomerate.
087: *
088: * @exception StandardException Standard exception policy.
089: **/
090: void drop(TransactionManager xact_manager) throws StandardException;
091:
092: /**
093: * Retrieve the maximum value row in an ordered conglomerate.
094: * <p>
095: * Returns true and fetches the rightmost row of an ordered conglomerate
096: * into "fetchRow" if there is at least one row in the conglomerate. If
097: * there are no rows in the conglomerate it returns false.
098: * <p>
099: * Non-ordered conglomerates will not implement this interface, calls
100: * will generate a StandardException.
101: * <p>
102: * RESOLVE - this interface is temporary, long term equivalent (and more)
103: * functionality will be provided by the openBackwardScan() interface.
104: *
105: * @param xact_manager The TransactionController under which this
106: * operation takes place.
107: *
108: * @param rawtran The raw store xact to associate all ops with.
109: *
110: * @param conglomId The identifier of the conglomerate
111: * to open the scan for.
112: *
113: * @param open_mode Specifiy flags to control opening of table.
114: * OPENMODE_FORUPDATE - if set open the table for
115: * update otherwise open table shared.
116: * @param lock_level One of (MODE_TABLE, MODE_RECORD, or MODE_NONE).
117: *
118: * @param locking_policy The LockingPolicy to use to open the conglomerate.
119: *
120: * @param isolation_level The isolation level to lock the conglomerate at.
121: * One of (ISOLATION_READ_COMMITTED,
122: * ISOLATION_REPEATABLE_READ, or
123: * ISOLATION_SERIALIZABLE).
124: *
125: * @param scanColumnList A description of which columns to return from
126: * every fetch in the scan. fetchRow
127: * and scanColumnList work together
128: * to describe the row to be returned by the scan -
129: * see RowUtil for description of how these three
130: * parameters work together to describe a "row".
131: *
132: * @param fetchRow The row to retrieve the maximum value into.
133: *
134: * @return boolean indicating if a row was found and retrieved or not.
135: *
136: * @exception StandardException Standard exception policy.
137: **/
138:
139: boolean fetchMaxOnBTree(TransactionManager xact_manager,
140: Transaction rawtran, long conglomId, int open_mode,
141: int lock_level, LockingPolicy locking_policy,
142: int isolation_level, FormatableBitSet scanColumnList,
143: DataValueDescriptor[] fetchRow) throws StandardException;
144:
145: /**
146: * Get the containerid of conglomerate.
147: * <p>
148: * Will have to change when a conglomerate could have more than one
149: * containerid.
150: *
151: * @return The containerid.
152: *
153: * @exception StandardException Standard exception policy.
154: **/
155: long getContainerid();
156:
157: /**
158: * Get the id of the container of the conglomerate.
159: * <p>
160: * Will have to change when a conglomerate could have more than one
161: * container. The ContainerKey is a combination of the container id
162: * and segment id.
163: *
164: * @return The ContainerKey.
165: *
166: * @exception StandardException Standard exception policy.
167: **/
168: ContainerKey getId();
169:
170: /**
171: * Return static information about the conglomerate to be included in a
172: * a compiled plan.
173: * <p>
174: * The static info would be valid until any ddl was executed on the
175: * conglomid, and would be up to the caller to throw away when that
176: * happened. This ties in with what language already does for other
177: * invalidation of static info. The type of info in this would be
178: * containerid and array of format id's from which templates can be created.
179: * The info in this object is read only and can be shared among as many
180: * threads as necessary.
181: * <p>
182: *
183: * @return The static compiled information.
184: *
185: * @param tc The TransactionController under which this operation
186: * takes place.
187: * @param conglomId The identifier of the conglomerate to open.
188: *
189: * @exception StandardException Standard exception policy.
190: **/
191: public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(
192: TransactionController tc, long conglomId)
193: throws StandardException;
194:
195: /**
196: * Return dynamic information about the conglomerate to be dynamically
197: * reused in repeated execution of a statement.
198: * <p>
199: * The dynamic info is a set of variables to be used in a given
200: * ScanController or ConglomerateController. It can only be used in one
201: * controller at a time. It is up to the caller to insure the correct
202: * thread access to this info. The type of info in this is a scratch
203: * template for btree traversal, other scratch variables for qualifier
204: * evaluation, ...
205: * <p>
206: *
207: * @return The dynamic information.
208: *
209: * @param conglomId The identifier of the conglomerate to open.
210: *
211: * @exception StandardException Standard exception policy.
212: **/
213: public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo(
214: long conglomId) throws StandardException;
215:
216: /**
217: * Is this conglomerate temporary?
218: * <p>
219: *
220: * @return whether conglomerate is temporary or not.
221: **/
222: boolean isTemporary();
223:
224: /**
225: * Bulk load into the conglomerate.
226: * <p>
227: * Individual rows that are loaded into the conglomerate are not
228: * logged. After this operation, the underlying database must be backed up
229: * with a database backup rather than an transaction log backup (when we
230: * have them). This warning is put here for the benefit of future
231: * generation.
232: * <p>
233: * @param xact_manager The TransactionController under which this operation
234: * takes place.
235: *
236: * @param createConglom If true, the conglomerate is being created in the
237: * same operation as the openAndLoadConglomerate.
238: * The enables further optimization as recovery does
239: * not require page allocation to be logged.
240: *
241: * @param rowSource Where the rows come from.
242: *
243: * @return The number of rows loaded.
244: *
245: * @exception StandardException Standard exception policy. If
246: * conglomerage supports uniqueness checks and has been created to
247: * disallow duplicates, and one of the rows being loaded had key columns
248: * which were duplicate of a row already in the conglomerate, then
249: * raise SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION.
250: *
251: **/
252: public long load(TransactionManager xact_manager,
253: boolean createConglom, RowLocationRetRowSource rowSource)
254: throws StandardException;
255:
256: /**
257: * Open a conglomerate controller.
258: * <p>
259: *
260: * @return The open ConglomerateController.
261: *
262: * @param xact_manager The access xact to associate all ops on cc with.
263: * @param rawtran The raw store xact to associate all ops on cc with.
264: * @param open_mode A bit mask of TransactionController.MODE_* bits,
265: * indicating info about the open.
266: * @param lock_level Either TransactionController.MODE_TABLE or
267: * TransactionController.MODE_RECORD, as passed into
268: * the openConglomerate() call.
269: * @param locking_policy The LockingPolicy to use to open the conglomerate.
270: *
271: * @exception StandardException Standard exception policy.
272: *
273: * @see TransactionController
274: **/
275: ConglomerateController open(TransactionManager xact_manager,
276: Transaction rawtran, boolean hold, int open_mode,
277: int lock_level, LockingPolicy locking_policy,
278: StaticCompiledOpenConglomInfo static_info,
279: DynamicCompiledOpenConglomInfo dynamic_info)
280: throws StandardException;
281:
282: /**
283: * Open a scan controller.
284: *
285: * @exception StandardException Standard exception policy.
286: **/
287: ScanManager openScan(TransactionManager xact_manager,
288: Transaction rawtran, boolean hold, int open_mode,
289: int lock_level, LockingPolicy locking_policy,
290: int isolation_level, FormatableBitSet scanColumnList,
291: DataValueDescriptor[] startKeyValue,
292: int startSearchOperator, Qualifier qualifier[][],
293: DataValueDescriptor[] stopKeyValue, int stopSearchOperator,
294: StaticCompiledOpenConglomInfo static_info,
295: DynamicCompiledOpenConglomInfo dynamic_info)
296: throws StandardException;
297:
298: /**
299: * Online compress table.
300: *
301: * Returns a ScanManager which can be used to move rows
302: * around in a table, creating a block of free pages at the end of the
303: * table. The process of executing the scan will move rows from the end
304: * of the table toward the beginning. The GroupFetchScanController will
305: * return the old row location, the new row location, and the actual data
306: * of any row moved. Note that this scan only returns moved rows, not an
307: * entire set of rows, the scan is designed specifically to be
308: * used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE()
309: * procedure, or internal background calls to compress the table.
310: *
311: * The old and new row locations are returned so that the caller can
312: * update any indexes necessary.
313: *
314: * This scan always returns all collumns of the row.
315: *
316: * All inputs work exactly as in openScan(). The return is
317: * a GroupFetchScanController, which only allows fetches of groups
318: * of rows from the conglomerate.
319: * <p>
320: * Note that all Conglomerates may not implement openCompressScan(),
321: * currently only the Heap conglomerate implements this scan.
322: *
323: * @return The GroupFetchScanController to be used to fetch the rows.
324: *
325: * @param hold see openScan()
326: * @param open_mode see openScan()
327: * @param lock_level see openScan()
328: * @param isolation_level see openScan()
329: *
330: * @exception StandardException Standard exception policy.
331: **/
332: ScanManager defragmentConglomerate(TransactionManager xact_manager,
333: Transaction rawtran, boolean hold, int open_mode,
334: int lock_level, LockingPolicy locking_policy,
335: int isolation_level) throws StandardException;
336:
337: void purgeConglomerate(TransactionManager xact_manager,
338: Transaction rawtran) throws StandardException;
339:
340: void compressConglomerate(TransactionManager xact_manager,
341: Transaction rawtran) throws StandardException;
342:
343: /**
344: * Return an open StoreCostController for the conglomerate.
345: * <p>
346: * Return an open StoreCostController which can be used to ask about
347: * the estimated row counts and costs of ScanController and
348: * ConglomerateController operations, on the given conglomerate.
349: * <p>
350: * @param xact_manager The TransactionController under which this
351: * operation takes place.
352: * @param rawtran raw transaction context in which scan is managed.
353: *
354: * @return The open StoreCostController.
355: *
356: * @exception StandardException Standard exception policy.
357: *
358: * @see StoreCostController
359: **/
360: StoreCostController openStoreCost(TransactionManager xact_manager,
361: Transaction rawtran) throws StandardException;
362:
363: }
|