KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > conglomerate > Conglomerate


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.conglomerate.Conglomerate
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.conglomerate;
23
24 import org.apache.derby.iapi.error.StandardException;
25 import org.apache.derby.iapi.store.access.ConglomerateController;
26 import org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo;
27 import org.apache.derby.iapi.store.access.Qualifier;
28 import org.apache.derby.iapi.store.access.RowLocationRetRowSource;
29 import org.apache.derby.iapi.store.access.StoreCostController;
30 import org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo;
31 import org.apache.derby.iapi.store.access.TransactionController;
32 import org.apache.derby.iapi.store.raw.ContainerKey;
33
34 import org.apache.derby.iapi.store.raw.LockingPolicy;
35 import org.apache.derby.iapi.store.raw.Transaction;
36
37 import org.apache.derby.iapi.types.DataValueDescriptor;
38
39 import org.apache.derby.iapi.services.io.Storable;
40 import org.apache.derby.iapi.services.io.FormatableBitSet;
41
42
43 /**
44
45 A conglomerate is an abstract storage structure (they
46 correspond to access methods). The Conglomerate interface
47 corresponds to a single instance of a conglomerate. In
48 other words, for each conglomerate in the system, there
49 will be one object implementing Conglomerate.
50 <P>
51 The Conglomerate interface is implemented by each access method.
52 The implementation must maintain enough information to properly
53 open the conglomerate and scans, and to drop the conglomerate.
54 This information typically will include the id of the container
55 or containers in which the conglomerate is stored, and my also
56 include property information.
57 <P>
58 Conglomerates are created by a conglomerate factory. The access
59 manager stores them in a directory (which is why they implement
60 Storable).
61
62 **/
63
64 public interface Conglomerate extends Storable, DataValueDescriptor
65 {
66
67     /**
68      * Add a column to the conglomerate.
69      * <p>
70      * This routine update's the in-memory object version of the
71      * Conglomerate to have one more column of the type described by the
72      * input template column.
73      *
74      * Note that not all conglomerates may support this feature.
75      *
76      * @param xact_manager The TransactionController under which this
77      * operation takes place.
78      * @param column_id The column number to add this column at.
79      * @param template_column An instance of the column to be added to table.
80      *
81      * @exception StandardException Standard exception policy.
82      **/
83     public void addColumn(
84     TransactionManager xact_manager,
85     int column_id,
86     Storable template_column)
87         throws StandardException;
88
89     /**
90      * Drop this conglomerate.
91      *
92      * @exception StandardException Standard exception policy.
93      **/
94     void drop(TransactionManager xact_manager)
95         throws StandardException;
96
97     /**
98      * Retrieve the maximum value row in an ordered conglomerate.
99      * <p>
100      * Returns true and fetches the rightmost row of an ordered conglomerate
101      * into "fetchRow" if there is at least one row in the conglomerate. If
102      * there are no rows in the conglomerate it returns false.
103      * <p>
104      * Non-ordered conglomerates will not implement this interface, calls
105      * will generate a StandardException.
106      * <p>
107      * RESOLVE - this interface is temporary, long term equivalent (and more)
108      * functionality will be provided by the openBackwardScan() interface.
109      *
110      * @param xact_manager The TransactionController under which this
111      * operation takes place.
112      *
113      * @param rawtran The raw store xact to associate all ops with.
114      *
115      * @param conglomId The identifier of the conglomerate
116      * to open the scan for.
117      *
118      * @param open_mode Specifiy flags to control opening of table.
119      * OPENMODE_FORUPDATE - if set open the table for
120      * update otherwise open table shared.
121      * @param lock_level One of (MODE_TABLE, MODE_RECORD, or MODE_NONE).
122      *
123      * @param locking_policy The LockingPolicy to use to open the conglomerate.
124      *
125      * @param isolation_level The isolation level to lock the conglomerate at.
126      * One of (ISOLATION_READ_COMMITTED,
127      * ISOLATION_REPEATABLE_READ, or
128      * ISOLATION_SERIALIZABLE).
129      *
130      * @param scanColumnList A description of which columns to return from
131      * every fetch in the scan. fetchRow
132      * and scanColumnList work together
133      * to describe the row to be returned by the scan -
134      * see RowUtil for description of how these three
135      * parameters work together to describe a "row".
136      *
137      * @param fetchRow The row to retrieve the maximum value into.
138      *
139      * @return boolean indicating if a row was found and retrieved or not.
140      *
141      * @exception StandardException Standard exception policy.
142      **/
143
144     boolean fetchMaxOnBTree(
145     TransactionManager xact_manager,
146     Transaction rawtran,
147     long conglomId,
148     int open_mode,
149     int lock_level,
150     LockingPolicy locking_policy,
151     int isolation_level,
152     FormatableBitSet scanColumnList,
153     DataValueDescriptor[] fetchRow)
154         throws StandardException;
155
156
157     /**
158      * Get the containerid of conglomerate.
159      * <p>
160      * Will have to change when a conglomerate could have more than one
161      * containerid.
162      *
163      * @return The containerid.
164      *
165      * @exception StandardException Standard exception policy.
166      **/
167     long getContainerid();
168
169     /**
170      * Get the id of the container of the conglomerate.
171      * <p>
172      * Will have to change when a conglomerate could have more than one
173      * container. The ContainerKey is a combination of the container id
174      * and segment id.
175      *
176      * @return The ContainerKey.
177      *
178      * @exception StandardException Standard exception policy.
179      **/
180     ContainerKey getId();
181
182     /**
183      * Return static information about the conglomerate to be included in a
184      * a compiled plan.
185      * <p>
186      * The static info would be valid until any ddl was executed on the
187      * conglomid, and would be up to the caller to throw away when that
188      * happened. This ties in with what language already does for other
189      * invalidation of static info. The type of info in this would be
190      * containerid and array of format id's from which templates can be created.
191      * The info in this object is read only and can be shared among as many
192      * threads as necessary.
193      * <p>
194      *
195      * @return The static compiled information.
196      *
197      * @param tc The TransactionController under which this operation
198      * takes place.
199      * @param conglomId The identifier of the conglomerate to open.
200      *
201      * @exception StandardException Standard exception policy.
202      **/
203     public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(
204     TransactionController tc,
205     long conglomId)
206         throws StandardException;
207
208     /**
209      * Return dynamic information about the conglomerate to be dynamically
210      * reused in repeated execution of a statement.
211      * <p>
212      * The dynamic info is a set of variables to be used in a given
213      * ScanController or ConglomerateController. It can only be used in one
214      * controller at a time. It is up to the caller to insure the correct
215      * thread access to this info. The type of info in this is a scratch
216      * template for btree traversal, other scratch variables for qualifier
217      * evaluation, ...
218      * <p>
219      *
220      * @return The dynamic information.
221      *
222      * @param conglomId The identifier of the conglomerate to open.
223      *
224      * @exception StandardException Standard exception policy.
225      **/
226     public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo(
227     long conglomId)
228         throws StandardException;
229
230     /**
231      * Is this conglomerate temporary?
232      * <p>
233      *
234      * @return whether conglomerate is temporary or not.
235      **/
236     boolean isTemporary();
237
238     /**
239      * Bulk load into the conglomerate.
240      * <p>
241      * Individual rows that are loaded into the conglomerate are not
242      * logged. After this operation, the underlying database must be backed up
243      * with a database backup rather than an transaction log backup (when we
244      * have them). This warning is put here for the benefit of future
245      * generation.
246      * <p>
247      * @param xact_manager The TransactionController under which this operation
248      * takes place.
249      *
250      * @param createConglom If true, the conglomerate is being created in the
251      * same operation as the openAndLoadConglomerate.
252      * The enables further optimization as recovery does
253      * not require page allocation to be logged.
254      *
255      * @param rowSource Where the rows come from.
256      *
257      * @return The number of rows loaded.
258      *
259      * @exception StandardException Standard exception policy. If
260      * conglomerage supports uniqueness checks and has been created to
261      * disallow duplicates, and one of the rows being loaded had key columns
262      * which were duplicate of a row already in the conglomerate, then
263      * raise SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION.
264      *
265      **/
266     public long load(
267     TransactionManager xact_manager,
268     boolean createConglom,
269     RowLocationRetRowSource rowSource)
270          throws StandardException;
271
272
273     /**
274      * Open a conglomerate controller.
275      * <p>
276      *
277      * @return The open ConglomerateController.
278      *
279      * @param xact_manager The access xact to associate all ops on cc with.
280      * @param rawtran The raw store xact to associate all ops on cc with.
281      * @param open_mode A bit mask of TransactionController.MODE_* bits,
282      * indicating info about the open.
283      * @param lock_level Either TransactionController.MODE_TABLE or
284      * TransactionController.MODE_RECORD, as passed into
285      * the openConglomerate() call.
286      * @param locking_policy The LockingPolicy to use to open the conglomerate.
287      *
288      * @exception StandardException Standard exception policy.
289      *
290      * @see TransactionController
291      **/
292     ConglomerateController open(
293     TransactionManager xact_manager,
294     Transaction rawtran,
295     boolean hold,
296     int open_mode,
297     int lock_level,
298     LockingPolicy locking_policy,
299     StaticCompiledOpenConglomInfo static_info,
300     DynamicCompiledOpenConglomInfo dynamic_info)
301         throws StandardException;
302
303     /**
304      * Open a scan controller.
305      *
306      * @exception StandardException Standard exception policy.
307      **/
308     ScanManager openScan(
309     TransactionManager xact_manager,
310     Transaction rawtran,
311     boolean hold,
312     int open_mode,
313     int lock_level,
314     LockingPolicy locking_policy,
315     int isolation_level,
316     FormatableBitSet scanColumnList,
317     DataValueDescriptor[] startKeyValue,
318     int startSearchOperator,
319     Qualifier qualifier[][],
320     DataValueDescriptor[] stopKeyValue,
321     int stopSearchOperator,
322     StaticCompiledOpenConglomInfo static_info,
323     DynamicCompiledOpenConglomInfo dynamic_info)
324         throws StandardException;
325
326     /**
327      * Online compress table.
328      *
329      * Returns a ScanManager which can be used to move rows
330      * around in a table, creating a block of free pages at the end of the
331      * table. The process of executing the scan will move rows from the end
332      * of the table toward the beginning. The GroupFetchScanController will
333      * return the old row location, the new row location, and the actual data
334      * of any row moved. Note that this scan only returns moved rows, not an
335      * entire set of rows, the scan is designed specifically to be
336      * used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE()
337      * procedure, or internal background calls to compress the table.
338      *
339      * The old and new row locations are returned so that the caller can
340      * update any indexes necessary.
341      *
342      * This scan always returns all collumns of the row.
343      *
344      * All inputs work exactly as in openScan(). The return is
345      * a GroupFetchScanController, which only allows fetches of groups
346      * of rows from the conglomerate.
347      * <p>
348      * Note that all Conglomerates may not implement openCompressScan(),
349      * currently only the Heap conglomerate implements this scan.
350      *
351      * @return The GroupFetchScanController to be used to fetch the rows.
352      *
353      * @param hold see openScan()
354      * @param open_mode see openScan()
355      * @param lock_level see openScan()
356      * @param isolation_level see openScan()
357      *
358      * @exception StandardException Standard exception policy.
359      **/
360     ScanManager defragmentConglomerate(
361     TransactionManager xact_manager,
362     Transaction rawtran,
363     boolean hold,
364     int open_mode,
365     int lock_level,
366     LockingPolicy locking_policy,
367     int isolation_level)
368         throws StandardException;
369
370     void purgeConglomerate(
371     TransactionManager xact_manager,
372     Transaction rawtran)
373         throws StandardException;
374
375     void compressConglomerate(
376     TransactionManager xact_manager,
377     Transaction rawtran)
378         throws StandardException;
379
380     /**
381      * Return an open StoreCostController for the conglomerate.
382      * <p>
383      * Return an open StoreCostController which can be used to ask about
384      * the estimated row counts and costs of ScanController and
385      * ConglomerateController operations, on the given conglomerate.
386      * <p>
387      * @param xact_manager The TransactionController under which this
388      * operation takes place.
389      * @param rawtran raw transaction context in which scan is managed.
390      *
391      * @return The open StoreCostController.
392      *
393      * @exception StandardException Standard exception policy.
394      *
395      * @see StoreCostController
396      **/
397     StoreCostController openStoreCost(
398     TransactionManager xact_manager,
399     Transaction rawtran)
400         throws StandardException;
401
402 }
403
Popular Tags