001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.GenericScanController
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.access;
023:
024: import org.apache.derby.iapi.services.io.Storable;
025:
026: import org.apache.derby.iapi.error.StandardException;
027:
028: import org.apache.derby.iapi.types.DataValueDescriptor;
029:
030: import org.apache.derby.iapi.types.RowLocation;
031:
032: import org.apache.derby.iapi.services.io.FormatableBitSet;
033:
034: /**
035:
036: The set of interfaces implemented by all types of ScanControllers.
037: <P>
038: A scan is the mechanism for iterating over the rows in a conglomerate,
039: the scan controller is the interface through which access clients
040: control the underlying scan. An instance of a scan controller can
041: be thought of as an open scan.
042: <p>
043: Scans are opened from a TransactionController.
044: <P>
045: A ScanController can handle partial rows. Partial rows are described in
046: RowUtil.
047: <BR>
048: A scan controller is opened with a FormatableBitSet that describes the
049: columns that need to be returned on a fetch call. This FormatableBitSet
050: need not include any columns referenced in the qualifers, start
051: and/or stop keys.
052:
053: @see TransactionController#openScan
054: @see RowCountable
055: @see RowUtil
056:
057: **/
058:
059: public interface GenericScanController extends RowCountable {
060: /**
061: Close the scan. This method always succeeds, and never throws
062: any exceptions. Callers must not use the scan controller after
063: closing it; they are strongly advised to clear out the scan
064: controller reference after closing.
065:
066: @exception StandardException Standard exception policy.
067: **/
068: void close() throws StandardException;
069:
070: /**
071: * Return ScanInfo object which describes performance of scan.
072: * <p>
073: * Return ScanInfo object which contains information about the current
074: * state of the scan.
075: * <p>
076: * The statistics gathered by the scan are not reset to 0 by a reopenScan(),
077: * rather they continue to accumulate.
078: * <p>
079: *
080: *
081: * @see ScanInfo
082: *
083: * @return The ScanInfo object which contains info about current scan.
084: *
085: * @exception StandardException Standard exception policy.
086: **/
087: ScanInfo getScanInfo() throws StandardException;
088:
089: /**
090: * Return whether this is a keyed conglomerate.
091: * <p>
092: *
093: * @return whether this is a keyed conglomerate.
094: **/
095: boolean isKeyed();
096:
097: /**
098: * Return whether this scan is table locked.
099: * <p>
100: * Implementation of this is not complete. Currently it does not give back
101: * the right information on covering locks or lock escalation. If the
102: * openScan() caller specifies a MODE_TABLE as the lock_level then this
103: * routine will always return true. If the openScan() caller specifies a
104: * MODE_RECORD as the lock_level then this routine will return true iff
105: * the lock level of the system has been overridden either by the
106: * derby.storage.rowLocking=false property, or by a shipped
107: * configuration which disables row locking.
108: * <p>
109: *
110: * @return whether this scan is table locked.
111: **/
112: boolean isTableLocked();
113:
114: /**
115: * Return a row location object to be used in calls to fetchLocation.
116: * <p>
117: * Return a row location object of the correct type to be used in calls to
118: * fetchLocation.
119: * <p>
120: *
121: * @return a row location object to be used in calls to fetchLocation.
122: *
123: * @exception StandardException Standard exception policy.
124: **/
125: RowLocation newRowLocationTemplate() throws StandardException;
126:
127: /**
128: Reposition the current scan. This call is semantically the same as if
129: the current scan had been closed and a openScan() had been called instead.
130: The scan is reopened with against the same conglomerate, and the scan
131: is reopened with the same "scan column list", "hold" and "forUpdate"
132: parameters passed in the original openScan.
133: <p>
134: The statistics gathered by the scan are not reset to 0 by a reopenScan(),
135: rather they continue to accumulate.
136: <p>
137:
138: @param startKeyValue An indexable row which holds a
139: (partial) key value which, in combination with the
140: startSearchOperator, defines the starting position of
141: the scan. If null, the starting position of the scan
142: is the first row of the conglomerate.
143:
144: @param startSearchOperator an operator which defines
145: how the startKeyValue is to be searched for. If
146: startSearchOperator is ScanController.GE, the scan starts on
147: the first row which is greater than or equal to the
148: startKeyValue. If startSearchOperation is ScanController.GT,
149: the scan starts on the first row whose key is greater than
150: startKeyValue. The startSearchOperation parameter is
151: ignored if the startKeyValue parameter is null.
152:
153: @param qualifier An array of qualifiers which, applied
154: to each key, restrict the rows returned by the scan. Rows
155: for which any one of the qualifiers returns false are not
156: returned by the scan. If null, all rows are returned.
157:
158: @param stopKeyValue An indexable row which holds a
159: (partial) key value which, in combination with the
160: stopSearchOperator, defines the ending position of
161: the scan. If null, the ending position of the scan
162: is the last row of the conglomerate.
163:
164: @param stopSearchOperator an operator which defines
165: how the stopKeyValue is used to determine the scan stopping
166: position. If stopSearchOperation is ScanController.GE, the scan
167: stops just before the first row which is greater than or
168: equal to the stopKeyValue. If stopSearchOperation is
169: ScanController.GT, the scan stops just before the first row whose
170: key is greater than startKeyValue. The stopSearchOperation
171: parameter is ignored if the stopKeyValue parameter is null.
172:
173: @exception StandardException Standard exception policy.
174: **/
175: void reopenScan(DataValueDescriptor[] startKeyValue,
176: int startSearchOperator, Qualifier qualifier[][],
177: DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
178: throws StandardException;
179:
180: /**
181: Reposition the current scan. This call is semantically the same as if
182: the current scan had been closed and a openScan() had been called instead.
183: The scan is reopened against the same conglomerate, and the scan
184: is reopened with the same "scan column list", "hold" and "forUpdate"
185: parameters passed in the original openScan.
186: <p>
187: The statistics gathered by the scan are not reset to 0 by a reopenScan(),
188: rather they continue to accumulate.
189: <p>
190: Note that this operation is currently only supported on Heap conglomerates.
191: Also note that order of rows within are heap are not guaranteed, so for
192: instance positioning at a RowLocation in the "middle" of a heap, then
193: inserting more data, then continuing the scan is not guaranteed to see
194: the new rows - they may be put in the "beginning" of the heap.
195:
196: @param startRowLocation An existing RowLocation within the conglomerate,
197: at which to position the start of the scan. The scan will begin at this
198: location and continue forward until the end of the conglomerate.
199: Positioning at a non-existent RowLocation (ie. an invalid one or one that
200: had been deleted), will result in an exception being thrown when the
201: first next operation is attempted.
202:
203: @param qualifier An array of qualifiers which, applied
204: to each key, restrict the rows returned by the scan. Rows
205: for which any one of the qualifiers returns false are not
206: returned by the scan. If null, all rows are returned.
207:
208: @exception StandardException Standard exception policy.
209: **/
210: void reopenScanByRowLocation(RowLocation startRowLocation,
211: Qualifier qualifier[][]) throws StandardException;
212: }
|