--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.conglomerate.Conglomerate\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.access.conglomerate;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+import org.apache.derby.iapi.store.access.ConglomerateController;\r
+import org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo;\r
+import org.apache.derby.iapi.store.access.Qualifier;\r
+import org.apache.derby.iapi.store.access.RowLocationRetRowSource;\r
+import org.apache.derby.iapi.store.access.StoreCostController;\r
+import org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo;\r
+import org.apache.derby.iapi.store.access.TransactionController;\r
+import org.apache.derby.iapi.store.raw.ContainerKey;\r
+\r
+import org.apache.derby.iapi.store.raw.LockingPolicy;\r
+import org.apache.derby.iapi.store.raw.Transaction;\r
+\r
+import org.apache.derby.iapi.types.DataValueDescriptor;\r
+\r
+import org.apache.derby.iapi.services.io.Storable;\r
+import org.apache.derby.iapi.services.io.FormatableBitSet;\r
+\r
+\r
+/**\r
+\r
+A conglomerate is an abstract storage structure (they\r
+correspond to access methods). The Conglomerate interface\r
+corresponds to a single instance of a conglomerate. In\r
+other words, for each conglomerate in the system, there\r
+will be one object implementing Conglomerate.\r
+<P>\r
+The Conglomerate interface is implemented by each access method.\r
+The implementation must maintain enough information to properly\r
+open the conglomerate and scans, and to drop the conglomerate.\r
+This information typically will include the id of the container\r
+or containers in which the conglomerate is stored, and my also\r
+include property information.\r
+<P>\r
+Conglomerates are created by a conglomerate factory. The access\r
+manager stores them in a directory (which is why they implement\r
+Storable).\r
+\r
+**/\r
+\r
+public interface Conglomerate extends Storable, DataValueDescriptor\r
+{\r
+\r
+ /**\r
+ * Add a column to the conglomerate.\r
+ * <p>\r
+ * This routine update's the in-memory object version of the \r
+ * Conglomerate to have one more column of the type described by the\r
+ * input template column.\r
+ *\r
+ * Note that not all conglomerates may support this feature.\r
+ * \r
+ * @param xact_manager The TransactionController under which this \r
+ * operation takes place.\r
+ * @param column_id The column number to add this column at.\r
+ * @param template_column An instance of the column to be added to table.\r
+ * @param collation_id Collation id of the added column.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void addColumn(\r
+ TransactionManager xact_manager,\r
+ int column_id,\r
+ Storable template_column,\r
+ int collation_id)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Drop this conglomerate.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ void drop(TransactionManager xact_manager)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Retrieve the maximum value row in an ordered conglomerate.\r
+ * <p>\r
+ * Returns true and fetches the rightmost row of an ordered conglomerate \r
+ * into "fetchRow" if there is at least one row in the conglomerate. If\r
+ * there are no rows in the conglomerate it returns false.\r
+ * <p>\r
+ * Non-ordered conglomerates will not implement this interface, calls\r
+ * will generate a StandardException.\r
+ * <p>\r
+ * RESOLVE - this interface is temporary, long term equivalent (and more) \r
+ * functionality will be provided by the openBackwardScan() interface. \r
+ *\r
+ * @param xact_manager The TransactionController under which this \r
+ * operation takes place.\r
+ *\r
+ * @param rawtran The raw store xact to associate all ops with.\r
+ *\r
+ * @param conglomId The identifier of the conglomerate\r
+ * to open the scan for.\r
+ *\r
+ * @param open_mode Specifiy flags to control opening of table. \r
+ * OPENMODE_FORUPDATE - if set open the table for\r
+ * update otherwise open table shared.\r
+ * @param lock_level One of (MODE_TABLE, MODE_RECORD, or MODE_NONE).\r
+ *\r
+ * @param locking_policy The LockingPolicy to use to open the conglomerate.\r
+ *\r
+ * @param isolation_level The isolation level to lock the conglomerate at.\r
+ * One of (ISOLATION_READ_COMMITTED, \r
+ * ISOLATION_REPEATABLE_READ, or \r
+ * ISOLATION_SERIALIZABLE).\r
+ *\r
+ * @param scanColumnList A description of which columns to return from \r
+ * every fetch in the scan. fetchRow \r
+ * and scanColumnList work together\r
+ * to describe the row to be returned by the scan - \r
+ * see RowUtil for description of how these three \r
+ * parameters work together to describe a "row".\r
+ *\r
+ * @param fetchRow The row to retrieve the maximum value into.\r
+ *\r
+ * @return boolean indicating if a row was found and retrieved or not.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+\r
+ boolean fetchMaxOnBTree(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran,\r
+ long conglomId,\r
+ int open_mode,\r
+ int lock_level,\r
+ LockingPolicy locking_policy,\r
+ int isolation_level,\r
+ FormatableBitSet scanColumnList,\r
+ DataValueDescriptor[] fetchRow)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Get the containerid of conglomerate.\r
+ * <p>\r
+ * Will have to change when a conglomerate could have more than one \r
+ * containerid.\r
+ *\r
+ * @return The containerid.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ long getContainerid();\r
+\r
+ /**\r
+ * Get the id of the container of the conglomerate.\r
+ * <p>\r
+ * Will have to change when a conglomerate could have more than one \r
+ * container. The ContainerKey is a combination of the container id\r
+ * and segment id.\r
+ *\r
+ * @return The ContainerKey.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ ContainerKey getId();\r
+\r
+ /**\r
+ * Return static information about the conglomerate to be included in a\r
+ * a compiled plan.\r
+ * <p>\r
+ * The static info would be valid until any ddl was executed on the \r
+ * conglomid, and would be up to the caller to throw away when that \r
+ * happened. This ties in with what language already does for other \r
+ * invalidation of static info. The type of info in this would be \r
+ * containerid and array of format id's from which templates can be created.\r
+ * The info in this object is read only and can be shared among as many \r
+ * threads as necessary.\r
+ * <p>\r
+ *\r
+ * @return The static compiled information.\r
+ *\r
+ * @param tc The TransactionController under which this operation \r
+ * takes place.\r
+ * @param conglomId The identifier of the conglomerate to open.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(\r
+ TransactionController tc,\r
+ long conglomId)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Return dynamic information about the conglomerate to be dynamically \r
+ * reused in repeated execution of a statement.\r
+ * <p>\r
+ * The dynamic info is a set of variables to be used in a given \r
+ * ScanController or ConglomerateController. It can only be used in one \r
+ * controller at a time. It is up to the caller to insure the correct \r
+ * thread access to this info. The type of info in this is a scratch \r
+ * template for btree traversal, other scratch variables for qualifier \r
+ * evaluation, ...\r
+ * <p>\r
+ *\r
+ * @return The dynamic information.\r
+ *\r
+ * @param conglomId The identifier of the conglomerate to open.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo(\r
+ long conglomId)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Is this conglomerate temporary?\r
+ * <p>\r
+ *\r
+ * @return whether conglomerate is temporary or not.\r
+ **/\r
+ boolean isTemporary();\r
+\r
+ /**\r
+ * Bulk load into the conglomerate.\r
+ * <p>\r
+ * Individual rows that are loaded into the conglomerate are not\r
+ * logged. After this operation, the underlying database must be backed up\r
+ * with a database backup rather than an transaction log backup (when we \r
+ * have them). This warning is put here for the benefit of future \r
+ * generation.\r
+ * <p>\r
+ * @param xact_manager The TransactionController under which this operation\r
+ * takes place.\r
+ *\r
+ * @param createConglom If true, the conglomerate is being created in the \r
+ * same operation as the openAndLoadConglomerate. \r
+ * The enables further optimization as recovery does\r
+ * not require page allocation to be logged. \r
+ *\r
+ * @param rowSource Where the rows come from.\r
+ *\r
+ * @return The number of rows loaded.\r
+ *\r
+ * @exception StandardException Standard exception policy. If \r
+ * conglomerage supports uniqueness checks and has been created to \r
+ * disallow duplicates, and one of the rows being loaded had key columns \r
+ * which were duplicate of a row already in the conglomerate, then \r
+ * raise SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION.\r
+ *\r
+ **/\r
+ public long load(\r
+ TransactionManager xact_manager,\r
+ boolean createConglom,\r
+ RowLocationRetRowSource rowSource)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Open a conglomerate controller.\r
+ * <p>\r
+ *\r
+ * @return The open ConglomerateController.\r
+ *\r
+ * @param xact_manager The access xact to associate all ops on cc with.\r
+ * @param rawtran The raw store xact to associate all ops on cc with.\r
+ * @param open_mode A bit mask of TransactionController.MODE_* bits,\r
+ * indicating info about the open.\r
+ * @param lock_level Either TransactionController.MODE_TABLE or\r
+ * TransactionController.MODE_RECORD, as passed into\r
+ * the openConglomerate() call.\r
+ * @param locking_policy The LockingPolicy to use to open the conglomerate.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see TransactionController\r
+ **/\r
+ ConglomerateController open(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran, \r
+ boolean hold,\r
+ int open_mode,\r
+ int lock_level,\r
+ LockingPolicy locking_policy,\r
+ StaticCompiledOpenConglomInfo static_info,\r
+ DynamicCompiledOpenConglomInfo dynamic_info)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Open a scan controller.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ ScanManager openScan(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran,\r
+ boolean hold,\r
+ int open_mode,\r
+ int lock_level,\r
+ LockingPolicy locking_policy,\r
+ int isolation_level,\r
+ FormatableBitSet scanColumnList,\r
+ DataValueDescriptor[] startKeyValue,\r
+ int startSearchOperator,\r
+ Qualifier qualifier[][],\r
+ DataValueDescriptor[] stopKeyValue,\r
+ int stopSearchOperator,\r
+ StaticCompiledOpenConglomInfo static_info,\r
+ DynamicCompiledOpenConglomInfo dynamic_info)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Online compress table.\r
+ *\r
+ * Returns a ScanManager which can be used to move rows\r
+ * around in a table, creating a block of free pages at the end of the\r
+ * table. The process of executing the scan will move rows from the end \r
+ * of the table toward the beginning. The GroupFetchScanController will\r
+ * return the old row location, the new row location, and the actual data \r
+ * of any row moved. Note that this scan only returns moved rows, not an\r
+ * entire set of rows, the scan is designed specifically to be\r
+ * used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE()\r
+ * procedure, or internal background calls to compress the table.\r
+ *\r
+ * The old and new row locations are returned so that the caller can\r
+ * update any indexes necessary.\r
+ *\r
+ * This scan always returns all collumns of the row.\r
+ * \r
+ * All inputs work exactly as in openScan(). The return is \r
+ * a GroupFetchScanController, which only allows fetches of groups\r
+ * of rows from the conglomerate.\r
+ * <p>\r
+ * Note that all Conglomerates may not implement openCompressScan(), \r
+ * currently only the Heap conglomerate implements this scan.\r
+ *\r
+ * @return The GroupFetchScanController to be used to fetch the rows.\r
+ *\r
+ * @param hold see openScan()\r
+ * @param open_mode see openScan()\r
+ * @param lock_level see openScan()\r
+ * @param isolation_level see openScan()\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ ScanManager defragmentConglomerate(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran,\r
+ boolean hold,\r
+ int open_mode,\r
+ int lock_level,\r
+ LockingPolicy locking_policy,\r
+ int isolation_level)\r
+ throws StandardException;\r
+\r
+ void purgeConglomerate(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran)\r
+ throws StandardException;\r
+\r
+ void compressConglomerate(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Return an open StoreCostController for the conglomerate.\r
+ * <p>\r
+ * Return an open StoreCostController which can be used to ask about \r
+ * the estimated row counts and costs of ScanController and \r
+ * ConglomerateController operations, on the given conglomerate.\r
+ * <p>\r
+ * @param xact_manager The TransactionController under which this \r
+ * operation takes place.\r
+ * @param rawtran raw transaction context in which scan is managed.\r
+ *\r
+ * @return The open StoreCostController.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see StoreCostController\r
+ **/\r
+ StoreCostController openStoreCost(\r
+ TransactionManager xact_manager,\r
+ Transaction rawtran)\r
+ throws StandardException;\r
+\r
+}\r