--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.impl.store.access.sort.Scan\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.impl.store.access.sort;\r
+\r
+import org.apache.derby.iapi.reference.SQLState;\r
+\r
+import org.apache.derby.iapi.store.access.BackingStoreHashtable;\r
+import org.apache.derby.iapi.services.io.FormatableBitSet;\r
+import org.apache.derby.iapi.services.i18n.MessageService;\r
+\r
+import org.apache.derby.iapi.types.RowLocation;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.store.access.conglomerate.Conglomerate;\r
+import org.apache.derby.iapi.store.access.conglomerate.ScanManager;\r
+\r
+import org.apache.derby.iapi.store.access.Qualifier;\r
+import org.apache.derby.iapi.store.access.ScanInfo;\r
+\r
+import org.apache.derby.iapi.store.raw.Page;\r
+\r
+import org.apache.derby.iapi.types.DataValueDescriptor;\r
+\r
+import java.util.Properties;\r
+\r
+// For JavaDoc references (i.e. @see)\r
+import org.apache.derby.iapi.store.access.ScanController;\r
+\r
+/**\r
+\r
+ Abstract base class for all sort classes which return rows from the\r
+ sort. Subclasses must implement fetch, next, and close.\r
+\r
+**/\r
+\r
+public abstract class Scan implements ScanManager, ScanInfo\r
+{\r
+ /*\r
+ * Methods of ScanController\r
+ */\r
+\r
+ /**\r
+ * A call to allow client to indicate that current row does not qualify.\r
+ * <p>\r
+ * Indicates to the ScanController that the current row does not\r
+ * qualify for the scan. If the isolation level of the scan allows, \r
+ * this may result in the scan releasing the lock on this row.\r
+ * <p>\r
+ * Note that some scan implimentations may not support releasing locks on \r
+ * non-qualifying rows, or may delay releasing the lock until sometime\r
+ * later in the scan (ie. it may be necessary to keep the lock until \r
+ * either the scan is repositioned on the next row or page).\r
+ * <p>\r
+ * This call should only be made while the scan is positioned on a current\r
+ * valid row.\r
+ * <p>\r
+ * This call does not make sense for sort scans.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void didNotQualify()\r
+ throws StandardException\r
+ {\r
+ }\r
+\r
+ /**\r
+ * Fetch the next N rows from the table.\r
+ * <p>\r
+ * Currently unimplemented for sorts.\r
+ * <p>\r
+ **/\r
+ public int fetchNextGroup(\r
+ DataValueDescriptor[][] row_array,\r
+ RowLocation[] rowloc_array)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ public int fetchNextGroup(\r
+ DataValueDescriptor[][] row_array,\r
+ RowLocation[] old_rowloc_array,\r
+ RowLocation[] new_rowloc_array)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+\r
+ /**\r
+ * Insert all rows that qualify for the current scan into the input\r
+ * Hash table. \r
+ * <p>\r
+ * Currently unimplemented for sorts.\r
+ * <p>\r
+ **/\r
+ public void fetchSet(\r
+ long max_rowcnt,\r
+ int[] key_column_numbers,\r
+ BackingStoreHashtable hash_table)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Returns true if the current position of the scan still qualifies\r
+ under the set of qualifiers passed to the openScan().\r
+ @see ScanController#doesCurrentPositionQualify\r
+ **/\r
+ public boolean doesCurrentPositionQualify()\r
+ throws StandardException\r
+ {\r
+ return true;\r
+ }\r
+\r
+ /**\r
+ Fetch the location of the current position in the scan.\r
+ @see ScanController#fetchLocation\r
+ **/\r
+ public void fetchLocation(RowLocation templateLocation)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ * Return ScanInfo object which describes performance of scan.\r
+ * <p>\r
+ * Return ScanInfo object which contains information about the current\r
+ * scan.\r
+ * <p>\r
+ * Currently the ScanInfo does not have any performance data.\r
+ *\r
+ * @see ScanInfo\r
+ *\r
+ * @return The ScanInfo object which contains info about current scan.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public ScanInfo getScanInfo()\r
+ throws StandardException\r
+ {\r
+ return(this);\r
+ }\r
+\r
+ /**\r
+ * Get the total estimated number of rows in the container.\r
+ * <p>\r
+ * The number is a rough estimate and may be grossly off. In general\r
+ * the server will cache the row count and then occasionally write\r
+ * the count unlogged to a backing store. If the system happens to \r
+ * shutdown before the store gets a chance to update the row count it\r
+ * may wander from reality.\r
+ * <p>\r
+ * This call is currently only supported on Heap conglomerates, it\r
+ * will throw an exception if called on btree conglomerates.\r
+ *\r
+ * @return The total estimated number of rows in the conglomerate.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public long getEstimatedRowCount()\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ * Set the total estimated number of rows in the container.\r
+ * <p>\r
+ * Often, after a scan, the client of RawStore has a much better estimate\r
+ * of the number of rows in the container than what store has. For \r
+ * instance if we implement some sort of update statistics command, or\r
+ * just after a create index a complete scan will have been done of the\r
+ * table. In this case this interface allows the client to set the\r
+ * estimated row count for the container, and store will use that number\r
+ * for all future references.\r
+ * <p>\r
+ * This call is currently only supported on Heap conglomerates, it\r
+ * will throw an exception if called on btree conglomerates.\r
+ *\r
+ * @param count the estimated number of rows in the container.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void setEstimatedRowCount(long count)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Returns true if the current position of the scan is at a \r
+ deleted row.\r
+ @see ScanController#isCurrentPositionDeleted\r
+ **/\r
+ public boolean isCurrentPositionDeleted()\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ * Return whether this is a keyed conglomerate.\r
+ * <p>\r
+ *\r
+ * @return whether this is a keyed conglomerate.\r
+ **/\r
+ public boolean isKeyed()\r
+ {\r
+ return(false);\r
+ }\r
+\r
+ /**\r
+ * Return whether this scan is table locked.\r
+ *\r
+ * @return whether this is table locked.\r
+ **/\r
+ public boolean isTableLocked()\r
+ {\r
+ return(true);\r
+ }\r
+\r
+ /**\r
+ Delete the row at the current position of the scan.\r
+ @see ScanController#delete\r
+ **/\r
+ public boolean delete()\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Reposition the current scan.\r
+ @see ScanController#reopenScan\r
+ **/\r
+ public void reopenScan(\r
+ DataValueDescriptor[] startKeyValue,\r
+ int startSearchOperator,\r
+ Qualifier qualifier[][],\r
+ DataValueDescriptor[] stopKeyValue,\r
+ int stopSearchOperator)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Reposition the current scan. This call is semantically the same as if\r
+ the current scan had been closed and a openScan() had been called instead.\r
+ The scan is reopened against the same conglomerate, and the scan\r
+ is reopened with the same "scan column list", "hold" and "forUpdate"\r
+ parameters passed in the original openScan. \r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ public void reopenScanByRowLocation(\r
+ RowLocation startRowLocation,\r
+ Qualifier qualifier[][])\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Replace the entire row at the current position of the scan.\r
+ @see ScanController#replace\r
+ **/\r
+ public boolean replace(\r
+ DataValueDescriptor[] val, \r
+ FormatableBitSet validColumns)\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ Return a row location object of the correct type to be\r
+ used in calls to fetchLocation.\r
+ @see ScanController#newRowLocationTemplate\r
+ **/\r
+ public RowLocation newRowLocationTemplate()\r
+ throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /**\r
+ *@see ScanController#positionAtRowLocation\r
+ */\r
+ public boolean positionAtRowLocation(RowLocation rl) \r
+ throws StandardException \r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+ /*\r
+ ** Methods of ScanManager\r
+ */\r
+\r
+ /**\r
+ * Do work necessary to maintain the current position in the scan.\r
+ * <p>\r
+ * The latched page in the conglomerate "congomid" is changing, do\r
+ * whatever is necessary to maintain the current position of the scan.\r
+ * For some conglomerates this may be a no-op.\r
+ * <p>\r
+ *\r
+ * @param conglom Conglomerate object of the conglomerate being changed.\r
+ * @param page Page in the conglomerate being changed.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void savePosition(Conglomerate conglom, Page page)\r
+ throws StandardException\r
+ {\r
+ // RESOLVE (mikem), under the current implementation all scans within\r
+ // a transaction are called rather than just the ones with the right\r
+ // conglomid. For now just have sort scans ignore the call. \r
+ \r
+ return;\r
+ }\r
+\r
+ /*\r
+ * Methods of ScanInfo\r
+ */\r
+ \r
+ /**\r
+ * Return all information gathered about the scan.\r
+ * <p>\r
+ * This routine returns a list of properties which contains all information\r
+ * gathered about the scan. If a Property is passed in, then that property\r
+ * list is appeneded to, otherwise a new property object is created and\r
+ * returned.\r
+ * <p>\r
+ * Currently sort scans doesn't track any information.\r
+ *\r
+ * @param prop Property list to fill in.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public Properties getAllScanInfo(Properties prop)\r
+ throws StandardException\r
+ {\r
+ if (prop == null)\r
+ prop = new Properties();\r
+\r
+ prop.put(\r
+ MessageService.getTextMessage(SQLState.STORE_RTS_SCAN_TYPE),\r
+ MessageService.getTextMessage(SQLState.STORE_RTS_SORT));\r
+\r
+ return(prop);\r
+ }\r
+\r
+ /**\r
+ * @see org.apache.derby.iapi.store.access.ScanController#isHeldAfterCommit\r
+ */\r
+ public boolean isHeldAfterCommit() throws StandardException\r
+ {\r
+ throw StandardException.newException(\r
+ SQLState.SORT_IMPROPER_SCAN_METHOD);\r
+ }\r
+\r
+}\r