--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.ScanController\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
+ 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\r
+ are described in 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 GenericScanController\r
+ @see RowCountable\r
+ @see RowUtil\r
+\r
+**/\r
+\r
+public interface ScanController extends GenericScanController\r
+{\r
+ /**\r
+\r
+ GE is used to position a scan at values greater than or or equal to the\r
+ given key in the scan. This positioning argument refers to the order \r
+ within the scan (not necessarily actual compare calls on the datatypes). \r
+ "greater" than is interpreted in terms of the \r
+ current conglomerate and scan. For instance, a btree may be ordered\r
+ ascending on an int, in that case a 2 is "greater" than 1 in a forward\r
+ scan on that index, and 1 is "greater" than 2 in a backward scan.\r
+ If the btree was ordered descending on an int then 1 is "greater" than\r
+ 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward\r
+ scan.\r
+\r
+ @see TransactionController#openScan\r
+ */\r
+\r
+ /* The value of this must be the same value returned by the Orderable\r
+ * interface when a key is > than another key.\r
+ */\r
+ public static final int GE = 1;\r
+\r
+ /**\r
+ GT is used to position a scan at values greater than the given key.\r
+ This positioning argument refers to the order \r
+ within the scan (not necessarily actual compare calls on the datatypes). \r
+ "greater" than is interpreted in terms of the \r
+ current conglomerate and scan. For instance, a btree may be ordered\r
+ ascending on an int, in that case a 2 is "greater" than 1 in a forward\r
+ scan on that index, and 1 is "greater" than 2 in a backward scan.\r
+ If the btree was ordered descending on an int then 1 is "greater" than\r
+ 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward\r
+ scan.\r
+\r
+ @see TransactionController#openScan\r
+ */\r
+ /* The value of this must be the same value returned by the Orderable\r
+ * interface when a key is < than another key.\r
+ */\r
+ public static final int GT = -1;\r
+\r
+ /**\r
+ NA - argument is unused in call. For some scans the key is set to null\r
+ to indicate no start or stop position, in those cases the position \r
+ operator is ignored.\r
+\r
+ @see TransactionController#openScan\r
+ */\r
+ /* The value of this must be the same value returned by the Orderable\r
+ * interface when a key is < than another key.\r
+ */\r
+ public static final int NA = 0;\r
+\r
+ /**\r
+ Delete the row at the current position of the scan.\r
+\r
+ @return true if the delete was successful,\r
+ false if the current position is no longer valid (ie. if it was already\r
+ deleted).\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean delete()\r
+ throws StandardException;\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
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ void didNotQualify() throws StandardException;\r
+\r
+ /**\r
+ Returns true if the current position of the scan still qualifies\r
+ under the set of qualifiers passed to the openScan(). When called\r
+ this routine will reapply all qualifiers against the row currently\r
+ positioned and return true if the row still qualifies. If the row\r
+ has been deleted or no longer passes the qualifiers then this routine\r
+ will return false.\r
+ \r
+ This case can come about if the current scan\r
+ or another scan on the same table in the same transaction \r
+ deleted the row or changed columns referenced by the qualifier after \r
+ the next() call which positioned the scan at this row. \r
+\r
+ Note that for comglomerates which don't support update, like btree's, \r
+ there is no need to recheck the qualifiers.\r
+\r
+ The results of a fetch() performed on a scan positioned on \r
+ a deleted row are undefined, note that this can happen even if next()\r
+ has returned true (for instance the client can delete the row, or if\r
+ using read uncommitted another thread can delete the row after the\r
+ next() call but before the fetch).\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean doesCurrentPositionQualify()\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Return true is the scan has been closed after a commit, but was\r
+ * opened with holdability and can be reopened using\r
+ * positionAtRowLocation.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ * @see ScanController#positionAtRowLocation\r
+ */\r
+ boolean isHeldAfterCommit() throws StandardException;\r
+\r
+ /**\r
+ Fetch the (partial) row at the current position of the Scan.\r
+ The value in the destRow storable row is replaced\r
+ with the value of the row at the current scan\r
+ position. The columns of the destRow row must\r
+ be of the same type as the actual columns in the\r
+ underlying conglomerate. The number of elements in\r
+ fetch must be compatible with the number of scan columns\r
+ requested at the openScan call time.\r
+ <BR>\r
+ A fetch can return a sub-set of the scan columns reqested\r
+ at scan open time by supplying a destRow will less elements\r
+ than the number of requested columns. In this case the N leftmost\r
+ of the requested columns are fetched, where N = destRow.length.\r
+ In the case where all columns are rested and N = 2 then columns 0 and 1\r
+ are returned. In the case where the openScan FormatableBitSet requested columns\r
+ 1, 4 and 7, then columns 1 and 4 would be fetched when N = 2.\r
+ <BR>\r
+\r
+ The results of a fetch() performed on a scan after next() has returned\r
+ false are undefined.\r
+\r
+ A fetch() performed on a scan positioned on \r
+ a deleted row will throw a StandardException with \r
+ state = SQLState.AM_RECORD_NOT_FOUND. Note that this can happen even if \r
+ next() has returned true (for instance the client can delete the row, or if\r
+ using read uncommitted another thread can delete the row after the\r
+ next() call but before the fetch).\r
+\r
+ @param destRow The row into which the value of the current \r
+ position in the scan is to be stored.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ @see RowUtil\r
+ **/\r
+ void fetch(DataValueDescriptor[] destRow)\r
+ throws StandardException;\r
+\r
+ /**\r
+ The same as fetch, except that the qualifiers passed to the openScan()\r
+ will not be applied. destRow will contain the current row even if it\r
+ has been changed and no longer qualifies.\r
+\r
+ @param destRow The row into which the value of the current \r
+ position in the scan is to be stored.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ */\r
+ void fetchWithoutQualify(DataValueDescriptor[] destRow)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Fetch the (partial) row at the next position of the Scan.\r
+\r
+ If there is a valid next position in the scan then\r
+ the value in the destRow storable row is replaced\r
+ with the value of the row at the current scan\r
+ position. The columns of the destRow row must\r
+ be of the same type as the actual columns in the\r
+ underlying conglomerate.\r
+\r
+ The resulting contents of destRow after a fetchNext() \r
+ which returns false is undefined.\r
+\r
+ The result of calling fetchNext(row) is exactly logically\r
+ equivalent to making a next() call followed by a fetch(row)\r
+ call. This interface allows implementations to optimize \r
+ the 2 calls if possible.\r
+\r
+ @param destRow The destRow row into which the value\r
+ of the next position in the scan is to be stored.\r
+\r
+ @return True if there is a next position in the scan,\r
+ false if there isn't.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ @see ScanController#fetch\r
+ @see RowUtil\r
+ **/\r
+ boolean fetchNext(DataValueDescriptor[] destRow)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Fetch the location of the current position in the scan.\r
+ The destination location is replaced with the location\r
+ corresponding to the current position in the scan.\r
+ The destination location must be of the correct actual\r
+ type to accept a location from the underlying conglomerate\r
+ location.\r
+\r
+ The results of a fetchLocation() performed on a scan after next() has \r
+ returned false are undefined.\r
+\r
+ The results of a fetchLocation() performed on a scan positioned on \r
+ a deleted row are undefined, note that this can happen even if next()\r
+ has returned true (for instance the client can delete the row, or if\r
+ using read uncommitted another thread can delete the row after the\r
+ next() call but before the fetchLocation).\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ void fetchLocation(RowLocation destRowLocation)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Returns true if the current position of the scan is at a \r
+ deleted row. This case can come about if the current scan\r
+ or another scan on the same table in the same transaction \r
+ deleted the row after the next() call which positioned the\r
+ scan at this row. \r
+\r
+ The results of a fetch() performed on a scan positioned on \r
+ a deleted row are undefined.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean isCurrentPositionDeleted()\r
+ throws StandardException;\r
+\r
+ /**\r
+ Move to the next position in the scan. If this is the first\r
+ call to next(), the position is set to the first row.\r
+ Returns false if there is not a next row to move to.\r
+ It is possible, but not guaranteed, that this method could return \r
+ true again, after returning false, if some other operation in the same \r
+ transaction appended a row to the underlying conglomerate.\r
+\r
+ @return True if there is a next position in the scan,\r
+ false if there isn't.\r
+\r
+ @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean next()\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Positions the scan at row location and locks the row. \r
+ * If the scan is not opened, it will be reopened if this is a holdable \r
+ * scan and there has not been any operations which causes RowLocations \r
+ * to be invalidated.\r
+ * @param rl RowLocation for the new position for the scan. The \r
+ * RowLocation submitted should be a RowLocation which has \r
+ * previously been returned by this ScanController.\r
+ * @return true if the scan has been positioned at the RowLocation.\r
+ * false if the scan could not be positioned.\r
+ * \r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ */\r
+ boolean positionAtRowLocation(RowLocation rl) \r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Replace the (partial) row at the current position of the scan.\r
+\r
+ @return true if the replace was successful,\r
+ false if the current position is no longer valid (ie. if it was deleted).\r
+\r
+ @exception StandardException Standard exception policy.\r
+ @see RowUtil\r
+ **/\r
+\r
+ boolean replace(DataValueDescriptor[] row, FormatableBitSet validColumns)\r
+ throws StandardException;\r
+\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff