--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.ConglomerateController\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;\r
+\r
+import org.apache.derby.iapi.store.access.RowUtil;\r
+\r
+import org.apache.derby.iapi.services.io.Storable;\r
+\r
+import org.apache.derby.iapi.types.DataValueDescriptor;\r
+\r
+import org.apache.derby.iapi.types.RowLocation;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+import org.apache.derby.iapi.services.io.FormatableBitSet;\r
+\r
+import java.util.Properties;\r
+\r
+\r
+/**\r
+\r
+A conglomerate is an abstract storage structure (they\r
+correspond to access methods). The ConglomerateController interface\r
+is the interface that access manager clients can use to manipulate\r
+the contents of the underlying conglomerate.\r
+<p>\r
+Each conglomerate holds a set of rows. Each row has a row location.\r
+The conglomerate provides methods for:\r
+<ul>\r
+<li>\r
+Inserting rows,\r
+<li>\r
+Fetching, deleting, and replacing entire rows by row location, and\r
+<li>\r
+fetching and updating individual columns of a row identified by row\r
+location.\r
+</ul>\r
+<p>\r
+Conglomerates do not provide any mechanism for associative access to\r
+rows within the conglomerate; this type of access is provided by scans\r
+via the ScanController interface.\r
+<p>\r
+Although all conglomerates have the same interface, they have different\r
+implementations. The implementation of a conglomerate determines some\r
+of its user-visible semantics; for example whether the rows are ordered\r
+or what the types of the rows' columns must be. The implementation is\r
+specified by an implementation id. Currently there are two implementations,\r
+"heap", and "btree". The details of their behavior are specified in their\r
+implementation documentation. (Currently, only "heap" is implemented).\r
+<p>\r
+All conglomerate operations are subject to the transactional isolation\r
+of the transaction they were opened from. Transaction rollback will\r
+close all conglomerates. Transaction commit will close all non-held\r
+conglomerates.\r
+<p>\r
+Scans are opened from a TransactionController.\r
+<P>\r
+A ConglomerateController can handle partial rows. Partial rows\r
+are described in RowUtil.\r
+\r
+@see TransactionController#openConglomerate\r
+@see RowUtil\r
+*/\r
+\r
+public interface ConglomerateController extends ConglomPropertyQueryable\r
+{\r
+ public static final int ROWISDUPLICATE = 1;\r
+\r
+ /**\r
+ * Close the conglomerate controller.\r
+ * <p>\r
+ * Close the conglomerate controller. Callers must not use\r
+ * the conglomerate controller after calling close. It is\r
+ * strongly recommended that callers clear out the reference\r
+ * after closing, e.g., \r
+ * <p>\r
+ * <blockquote><pre>\r
+ * ConglomerateController cc;\r
+ * cc.close;\r
+ * cc = null;\r
+ * </pre></blockquote>\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void close()\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Close conglomerate controller as part of terminating a transaction.\r
+ * <p>\r
+ * Use this call to close the conglomerate controller resources as part of\r
+ * committing or aborting a transaction. The normal close() routine may \r
+ * do some cleanup that is either unnecessary, or not correct due to the \r
+ * unknown condition of the controller following a transaction ending error.\r
+ * Use this call when closing all controllers as part of an abort of a \r
+ * transaction.\r
+ * <p)\r
+ * This call is meant to only be used internally by the Storage system,\r
+ * clients of the storage system should use the simple close() interface.\r
+ * <p>\r
+ * RESOLVE (mikem) - move this call to ConglomerateManager so it is\r
+ * obvious that non-access clients should not call this.\r
+ *\r
+ * @param closeHeldScan If true, means to close controller even if\r
+ * it has been opened to be kept opened \r
+ * across commit. This is\r
+ * used to close these controllers on abort.\r
+ *\r
+ * @return boolean indicating that the close has resulted in a real close\r
+ * of the controller. A held scan will return false if \r
+ * called by closeForEndTransaction(false), otherwise it \r
+ * will return true. A non-held scan will always return \r
+ * true.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean closeForEndTransaction(boolean closeHeldScan)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Check consistency of a conglomerate.\r
+\r
+ Checks the consistency of the data within a given conglomerate, does not\r
+ check consistency external to the conglomerate (ie. does not check that \r
+ base table row pointed at by a secondary index actually exists).\r
+\r
+ Raises a StandardException on first consistency problem. \r
+ \r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ void checkConsistency()\r
+ throws StandardException;\r
+\r
+ /**\r
+ Delete a row from the conglomerate. \r
+ @return Returns true if delete was successful, false if the record pointed\r
+ at no longer represents a valid record.\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean delete(RowLocation loc)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Fetch the (partial) row at the given location.\r
+ * <p>\r
+ *\r
+ * @param loc The "RowLocation" which describes the exact row\r
+ * to fetch from the table.\r
+ * @param destRow The row to read the data into.\r
+ * @param validColumns A description of which columns to return from\r
+ * row on the page into "destRow." destRow\r
+ * and validColumns work together to\r
+ * describe the row to be returned by the fetch - \r
+ * see RowUtil for description of how these three \r
+ * parameters work together to describe a fetched \r
+ * "row".\r
+ *\r
+ * @return Returns true if fetch was successful, false if the record \r
+ * pointed at no longer represents a valid record.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see RowUtil\r
+ **/\r
+ boolean fetch(\r
+ RowLocation loc, \r
+ DataValueDescriptor[] destRow, \r
+ FormatableBitSet validColumns) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Fetch the (partial) row at the given location.\r
+ * <p>\r
+ *\r
+ * @param loc The "RowLocation" which describes the exact row\r
+ * to fetch from the table.\r
+ * @param destRow The row to read the data into.\r
+ * @param validColumns A description of which columns to return from\r
+ * row on the page into "destRow." destRow\r
+ * and validColumns work together to\r
+ * describe the row to be returned by the fetch - \r
+ * see RowUtil for description of how these three \r
+ * parameters work together to describe a fetched \r
+ * "row".\r
+ * @param waitForLock If false, then the call will throw a lock timeout\r
+ * exception immediately, if the lock can not be\r
+ * granted without waiting. If true call will \r
+ * act exactly as fetch() interface with no \r
+ * waitForLock parameter.\r
+ *\r
+ * @return Returns true if fetch was successful, false if the record \r
+ * pointed at no longer represents a valid record.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see RowUtil\r
+ **/\r
+ boolean fetch(\r
+ RowLocation loc, \r
+ DataValueDescriptor[] destRow, \r
+ FormatableBitSet validColumns,\r
+ boolean waitForLock) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Fetch the (partial) row at the given location.\r
+ * <p>\r
+ * RESOLVE - interface NOT SUPPORTED YET!!!!!\r
+ *\r
+ * @param loc The "RowLocation" which describes the exact row\r
+ * to fetch from the table.\r
+ * @param destRow The row to read the data into.\r
+ * @param validColumns A description of which columns to return from\r
+ * row on the page into "destRow." destRow,\r
+ * and validColumns work together to\r
+ * describe the row to be returned by the fetch - \r
+ * see RowUtil for description of how these three \r
+ * parameters work together to describe a fetched \r
+ * "row".\r
+ * @param qualifier An array of qualifiers which, \r
+ * applied to each key, restrict the rows returned \r
+ * by the scan. Rows for which any one of the \r
+ * qualifiers returns false are not returned by \r
+ * the scan. If null, all rows are returned. \r
+ * Qualifiers can only reference columns which are \r
+ * included in the scanColumnList. The column id \r
+ * that a qualifier returns in the column id the \r
+ * table, not the column id in the partial row being\r
+ * returned. See openScan() for description of how \r
+ * qualifiers are applied.\r
+ *\r
+ * @return Returns true if fetch was successful, false if the record \r
+ * pointed at no longer represents a valid record.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see RowUtil\r
+ **/\r
+ /*\r
+ boolean fetch(\r
+ RowLocation loc, \r
+ DataValueDescriptor[] destRow, \r
+ FormatableBitSet validColumns, \r
+ Qualifier[][] qualifier)\r
+ throws StandardException;\r
+ */\r
+\r
+ /**\r
+ Insert a row into the conglomerate.\r
+\r
+ @param row The row to insert into the conglomerate. The stored\r
+ representations of the row's columns are copied into a new row\r
+ somewhere in the conglomerate.\r
+\r
+ @return Returns 0 if insert succeeded. Returns \r
+ ConglomerateController.ROWISDUPLICATE if conglomerate supports uniqueness\r
+ checks and has been created to disallow duplicates, and the row inserted\r
+ had key columns which were duplicate of a row already in the table. Other\r
+ insert failures will raise StandardException's.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ @see RowUtil\r
+ **/\r
+ int insert(DataValueDescriptor[] row) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * insert row and fetch it's row location in one operation.\r
+ * <p>\r
+ * Insert a row into the conglomerate, and store its location in \r
+ * the provided destination row location. The row location must be of the\r
+ * correct type for this conglomerate (a new row location of the correct \r
+ * type can be obtained from newRowLocationTemplate()).\r
+ *\r
+ * @param row The row to insert into the conglomerate. The \r
+ * stored representations of the row's columns are \r
+ * copied into a new row somewhere in the conglomerate.\r
+ *\r
+ * @param destRowLocation The rowlocation to read the inserted row location\r
+ * into.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see RowUtil\r
+ **/\r
+ void insertAndFetchLocation(\r
+ DataValueDescriptor[] row, \r
+ RowLocation destRowLocation)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Return whether this is a keyed conglomerate.\r
+ **/\r
+ boolean isKeyed();\r
+\r
+\r
+ public static final int LOCK_READ = (0x00000000);\r
+ public static final int LOCK_UPD = (0x00000001);\r
+ public static final int LOCK_INS = (0x00000002);\r
+ public static final int LOCK_INS_PREVKEY = (0x00000004);\r
+ public static final int LOCK_UPDATE_LOCKS = (0x00000008);\r
+\r
+ /**\r
+ * Lock the given row location.\r
+ * <p>\r
+ * Should only be called by access.\r
+ * <p>\r
+ * This call can be made on a ConglomerateController that was opened\r
+ * for locking only.\r
+ * <p>\r
+ * RESOLVE (mikem) - move this call to ConglomerateManager so it is\r
+ * obvious that non-access clients should not call this.\r
+ *\r
+ * @return true if lock was granted, only can be false if wait was false.\r
+ *\r
+ * @param loc The "RowLocation" of the exact row to lock.\r
+ * @param lock_oper For what operation are we requesting the lock, this\r
+ * should be one of the following 4 options:\r
+ * LOCK_READ [read lock], \r
+ * (LOCK_INS | LOCK_UPD) [ lock for insert], \r
+ * (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for \r
+ * previous key to insert],\r
+ * (LOCK_UPD) [lock for delete or replace]\r
+ * (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for \r
+ * update, will upgrade lock later if actual update\r
+ * is take place]\r
+ * @param wait Should the lock call wait to be granted?\r
+ * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,\r
+ * then lock will be released immediately after being\r
+ * granted.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean lockRow(\r
+ RowLocation loc,\r
+ int lock_oper,\r
+ boolean wait,\r
+ int lock_duration)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Lock the given record id/page num pair.\r
+ * <p>\r
+ * Should only be called by access, to lock "special" locks formed from\r
+ * the Recordhandle.* reserved constants for page specific locks.\r
+ * <p>\r
+ * This call can be made on a ConglomerateController that was opened\r
+ * for locking only.\r
+ * <p>\r
+ * RESOLVE (mikem) - move this call to ConglomerateManager so it is\r
+ * obvious that non-access clients should not call this.\r
+ *\r
+ * @return true if lock was granted, only can be false if wait was false.\r
+ *\r
+ * @param page_num page number of record to lock.\r
+ * @param record_id record id of record to lock.\r
+ * @param lock_oper For what operation are we requesting the lock, this\r
+ * should be one of the following 4 options:\r
+ * LOCK_READ [read lock], \r
+ * (LOCK_INS | LOCK_UPD) [ lock for insert], \r
+ * (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for \r
+ * previous key to insert],\r
+ * (LOCK_UPD) [lock for delete or replace]\r
+ * (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for \r
+ * update, will upgrade lock later if actual update\r
+ * is take place]\r
+ * @param wait Should the lock call wait to be granted?\r
+ * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,\r
+ * then lock will be released immediately after being\r
+ * granted.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean lockRow(\r
+ long page_num,\r
+ int record_id,\r
+ int lock_oper,\r
+ boolean wait,\r
+ int lock_duration)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * UnLock the given row location.\r
+ * <p>\r
+ * Should only be called by access.\r
+ * <p>\r
+ * This call can be made on a ConglomerateController that was opened\r
+ * for locking only.\r
+ * <p>\r
+ * RESOLVE (mikem) - move this call to ConglomerateManager so it is\r
+ * obvious that non-access clients should not call this.\r
+ *\r
+ * @param loc The "RowLocation" which describes the row to unlock.\r
+ * @param forUpdate Row was locked for read or update.\r
+ * @param row_qualified Row was qualified and returned to the user.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void unlockRowAfterRead(\r
+ RowLocation loc,\r
+ boolean forUpdate,\r
+ boolean row_qualified)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Return a row location object of the correct type to be\r
+ used in calls to insertAndFetchLocation.\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ RowLocation newRowLocationTemplate()\r
+ throws StandardException;\r
+\r
+ /**\r
+ Replace the (partial) row at the given location. \r
+ @return true if update was successful, returns false if the update \r
+ fails because the record pointed at no longer represents a valid record.\r
+ @exception StandardException Standard exception policy.\r
+ @see RowUtil\r
+ **/\r
+ boolean replace(\r
+ RowLocation loc, \r
+ DataValueDescriptor[] row, \r
+ FormatableBitSet validColumns)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Get information about space used by the conglomerate.\r
+ **/\r
+ SpaceInfo getSpaceInfo()\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Dump debugging output to error log.\r
+ * <p>\r
+ * Dump information about the conglomerate to error log.\r
+ * This is only for debugging purposes, does nothing in a delivered \r
+ * system, currently.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ void debugConglomerate()\r
+ throws StandardException;\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff