--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.GenericScanController\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.services.io.Storable;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\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.services.io.FormatableBitSet;\r
+\r
+/**\r
+\r
+ The set of interfaces implemented by all types of ScanControllers.\r
+ <P>\r
+ A scan is the mechanism for iterating over the rows in a conglomerate,\r
+ the scan controller is the interface through which access clients\r
+ control the underlying scan. An instance of a scan controller can \r
+ be thought of as an open scan.\r
+ <p>\r
+ Scans are opened from a TransactionController.\r
+ <P>\r
+ A ScanController can handle partial rows. Partial rows are described in \r
+ RowUtil.\r
+ <BR>\r
+ A scan controller is opened with a FormatableBitSet that describes the\r
+ columns that need to be returned on a fetch call. This FormatableBitSet\r
+ need not include any columns referenced in the qualifers, start\r
+ and/or stop keys.\r
+\r
+ @see TransactionController#openScan\r
+ @see RowCountable\r
+ @see RowUtil\r
+\r
+**/\r
+\r
+public interface GenericScanController extends RowCountable\r
+{\r
+ /**\r
+ Close the scan. This method always succeeds, and never throws\r
+ any exceptions. Callers must not use the scan controller after\r
+ closing it; they are strongly advised to clear out the scan\r
+ controller reference after closing.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ void close()\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Return ScanInfo object which describes performance of scan.\r
+ * <p>\r
+ * Return ScanInfo object which contains information about the current\r
+ * state of the scan.\r
+ * <p>\r
+ * The statistics gathered by the scan are not reset to 0 by a reopenScan(),\r
+ * rather they continue to accumulate.\r
+ * <p>\r
+ *\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
+ ScanInfo getScanInfo()\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Return whether this is a keyed conglomerate.\r
+ * <p>\r
+ *\r
+ * @return whether this is a keyed conglomerate.\r
+ **/\r
+ boolean isKeyed();\r
+\r
+ /**\r
+ * Return whether this scan is table locked.\r
+ * <p>\r
+ * Implementation of this is not complete. Currently it does not give back\r
+ * the right information on covering locks or lock escalation. If the\r
+ * openScan() caller specifies a MODE_TABLE as the lock_level then this\r
+ * routine will always return true. If the openScan() caller specifies a\r
+ * MODE_RECORD as the lock_level then this routine will return true iff\r
+ * the lock level of the system has been overridden either by the\r
+ * derby.storage.rowLocking=false property, or by a shipped \r
+ * configuration which disables row locking.\r
+ * <p>\r
+ *\r
+ * @return whether this scan is table locked.\r
+ **/\r
+ boolean isTableLocked();\r
+\r
+ /**\r
+ * Return a row location object to be used in calls to fetchLocation.\r
+ * <p>\r
+ * Return a row location object of the correct type to be used in calls to\r
+ * fetchLocation.\r
+ * <p>\r
+ *\r
+ * @return a row location object to be used in calls to fetchLocation.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ RowLocation newRowLocationTemplate()\r
+ throws StandardException;\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 with 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
+ <p>\r
+ The statistics gathered by the scan are not reset to 0 by a reopenScan(),\r
+ rather they continue to accumulate.\r
+ <p>\r
+\r
+ @param startKeyValue An indexable row which holds a \r
+ (partial) key value which, in combination with the\r
+ startSearchOperator, defines the starting position of\r
+ the scan. If null, the starting position of the scan\r
+ is the first row of the conglomerate.\r
+ \r
+ @param startSearchOperator an operator which defines\r
+ how the startKeyValue is to be searched for. If \r
+ startSearchOperator is ScanController.GE, the scan starts on\r
+ the first row which is greater than or equal to the \r
+ startKeyValue. If startSearchOperation is ScanController.GT,\r
+ the scan starts on the first row whose key is greater than\r
+ startKeyValue. The startSearchOperation parameter is \r
+ ignored if the startKeyValue parameter is null.\r
+\r
+ @param qualifier An array of qualifiers which, applied\r
+ to each key, restrict the rows returned by the scan. Rows\r
+ for which any one of the qualifiers returns false are not\r
+ returned by the scan. If null, all rows are returned.\r
+\r
+ @param stopKeyValue An indexable row which holds a \r
+ (partial) key value which, in combination with the\r
+ stopSearchOperator, defines the ending position of\r
+ the scan. If null, the ending position of the scan\r
+ is the last row of the conglomerate.\r
+ \r
+ @param stopSearchOperator an operator which defines\r
+ how the stopKeyValue is used to determine the scan stopping\r
+ position. If stopSearchOperation is ScanController.GE, the scan \r
+ stops just before the first row which is greater than or\r
+ equal to the stopKeyValue. If stopSearchOperation is\r
+ ScanController.GT, the scan stops just before the first row whose\r
+ key is greater than startKeyValue. The stopSearchOperation\r
+ parameter is ignored if the stopKeyValue parameter is null.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ void reopenScan(\r
+ DataValueDescriptor[] startKeyValue,\r
+ int startSearchOperator,\r
+ Qualifier qualifier[][],\r
+ DataValueDescriptor[] stopKeyValue,\r
+ int stopSearchOperator)\r
+ throws StandardException;\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
+ <p>\r
+ The statistics gathered by the scan are not reset to 0 by a reopenScan(),\r
+ rather they continue to accumulate.\r
+ <p>\r
+ Note that this operation is currently only supported on Heap conglomerates.\r
+ Also note that order of rows within are heap are not guaranteed, so for\r
+ instance positioning at a RowLocation in the "middle" of a heap, then\r
+ inserting more data, then continuing the scan is not guaranteed to see\r
+ the new rows - they may be put in the "beginning" of the heap.\r
+\r
+ @param startRowLocation An existing RowLocation within the conglomerate,\r
+ at which to position the start of the scan. The scan will begin at this\r
+ location and continue forward until the end of the conglomerate. \r
+ Positioning at a non-existent RowLocation (ie. an invalid one or one that\r
+ had been deleted), will result in an exception being thrown when the \r
+ first next operation is attempted.\r
+\r
+ @param qualifier An array of qualifiers which, applied\r
+ to each key, restrict the rows returned by the scan. Rows\r
+ for which any one of the qualifiers returns false are not\r
+ returned by the scan. If null, all rows are returned.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ void reopenScanByRowLocation(\r
+ RowLocation startRowLocation,\r
+ Qualifier qualifier[][])\r
+ throws StandardException;\r
+}\r