001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.ScanController
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: A scan is the mechanism for iterating over the rows in a conglomerate,
037: the scan controller is the interface through which access clients
038: control the underlying scan. An instance of a scan controller can
039: be thought of as an open scan.
040: <p>
041: Scans are opened from a TransactionController.
042: <P>
043: A ScanController can handle partial rows. Partial rows
044: are described in RowUtil.
045: <BR>
046: A scan controller is opened with a FormatableBitSet that describes the
047: columns that need to be returned on a fetch call. This FormatableBitSet
048: need not include any columns referenced in the qualifers, start
049: and/or stop keys.
050:
051: @see TransactionController#openScan
052: @see GenericScanController
053: @see RowCountable
054: @see RowUtil
055:
056: **/
057:
058: public interface ScanController extends GenericScanController {
059: /**
060:
061: GE is used to position a scan at values greater than or or equal to the
062: given key in the scan. This positioning argument refers to the order
063: within the scan (not necessarily actual compare calls on the datatypes).
064: "greater" than is interpreted in terms of the
065: current conglomerate and scan. For instance, a btree may be ordered
066: ascending on an int, in that case a 2 is "greater" than 1 in a forward
067: scan on that index, and 1 is "greater" than 2 in a backward scan.
068: If the btree was ordered descending on an int then 1 is "greater" than
069: 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward
070: scan.
071:
072: @see TransactionController#openScan
073: */
074:
075: /* The value of this must be the same value returned by the Orderable
076: * interface when a key is > than another key.
077: */
078: public static final int GE = 1;
079:
080: /**
081: GT is used to position a scan at values greater than the given key.
082: This positioning argument refers to the order
083: within the scan (not necessarily actual compare calls on the datatypes).
084: "greater" than is interpreted in terms of the
085: current conglomerate and scan. For instance, a btree may be ordered
086: ascending on an int, in that case a 2 is "greater" than 1 in a forward
087: scan on that index, and 1 is "greater" than 2 in a backward scan.
088: If the btree was ordered descending on an int then 1 is "greater" than
089: 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward
090: scan.
091:
092: @see TransactionController#openScan
093: */
094: /* The value of this must be the same value returned by the Orderable
095: * interface when a key is < than another key.
096: */
097: public static final int GT = -1;
098:
099: /**
100: NA - argument is unused in call. For some scans the key is set to null
101: to indicate no start or stop position, in those cases the position
102: operator is ignored.
103:
104: @see TransactionController#openScan
105: */
106: /* The value of this must be the same value returned by the Orderable
107: * interface when a key is < than another key.
108: */
109: public static final int NA = 0;
110:
111: /**
112: Delete the row at the current position of the scan.
113:
114: @return true if the delete was successful,
115: false if the current position is no longer valid (ie. if it was already
116: deleted).
117:
118: @exception StandardException Standard exception policy.
119: **/
120: boolean delete() throws StandardException;
121:
122: /**
123: * A call to allow client to indicate that current row does not qualify.
124: * <p>
125: * Indicates to the ScanController that the current row does not
126: * qualify for the scan. If the isolation level of the scan allows,
127: * this may result in the scan releasing the lock on this row.
128: * <p>
129: * Note that some scan implimentations may not support releasing locks on
130: * non-qualifying rows, or may delay releasing the lock until sometime
131: * later in the scan (ie. it may be necessary to keep the lock until
132: * either the scan is repositioned on the next row or page).
133: * <p>
134: * This call should only be made while the scan is positioned on a current
135: * valid row.
136: *
137: * @exception StandardException Standard exception policy.
138: **/
139: void didNotQualify() throws StandardException;
140:
141: /**
142: Returns true if the current position of the scan still qualifies
143: under the set of qualifiers passed to the openScan(). When called
144: this routine will reapply all qualifiers against the row currently
145: positioned and return true if the row still qualifies. If the row
146: has been deleted or no longer passes the qualifiers then this routine
147: will return false.
148:
149: This case can come about if the current scan
150: or another scan on the same table in the same transaction
151: deleted the row or changed columns referenced by the qualifier after
152: the next() call which positioned the scan at this row.
153:
154: Note that for comglomerates which don't support update, like btree's,
155: there is no need to recheck the qualifiers.
156:
157: The results of a fetch() performed on a scan positioned on
158: a deleted row are undefined, note that this can happen even if next()
159: has returned true (for instance the client can delete the row, or if
160: using read uncommitted another thread can delete the row after the
161: next() call but before the fetch).
162:
163: @exception StandardException Standard exception policy.
164: **/
165: boolean doesCurrentPositionQualify() throws StandardException;
166:
167: /**
168: Fetch the (partial) row at the current position of the Scan.
169: The value in the destRow storable row is replaced
170: with the value of the row at the current scan
171: position. The columns of the destRow row must
172: be of the same type as the actual columns in the
173: underlying conglomerate. The number of elements in
174: fetch must be compatible with the number of scan columns
175: requested at the openScan call time.
176: <BR>
177: A fetch can return a sub-set of the scan columns reqested
178: at scan open time by supplying a destRow will less elements
179: than the number of requested columns. In this case the N leftmost
180: of the requested columns are fetched, where N = destRow.length.
181: In the case where all columns are rested and N = 2 then columns 0 and 1
182: are returned. In the case where the openScan FormatableBitSet requested columns
183: 1, 4 and 7, then columns 1 and 4 would be fetched when N = 2.
184: <BR>
185:
186: The results of a fetch() performed on a scan after next() has returned
187: false are undefined.
188:
189: A fetch() performed on a scan positioned on
190: a deleted row will throw a StandardException with
191: state = SQLState.AM_RECORD_NOT_FOUND. Note that this can happen even if
192: next() has returned true (for instance the client can delete the row, or if
193: using read uncommitted another thread can delete the row after the
194: next() call but before the fetch).
195:
196: @param destRow The row into which the value of the current
197: position in the scan is to be stored.
198:
199: @exception StandardException Standard exception policy.
200: @see RowUtil
201: **/
202: void fetch(DataValueDescriptor[] destRow) throws StandardException;
203:
204: /**
205: The same as fetch, except that the qualifiers passed to the openScan()
206: will not be applied. destRow will contain the current row even if it
207: has been changed and no longer qualifies.
208:
209: @param destRow The row into which the value of the current
210: position in the scan is to be stored.
211:
212: @exception StandardException Standard exception policy.
213: */
214: void fetchWithoutQualify(DataValueDescriptor[] destRow)
215: throws StandardException;
216:
217: /**
218: Fetch the (partial) row at the next position of the Scan.
219:
220: If there is a valid next position in the scan then
221: the value in the destRow storable row is replaced
222: with the value of the row at the current scan
223: position. The columns of the destRow row must
224: be of the same type as the actual columns in the
225: underlying conglomerate.
226:
227: The resulting contents of destRow after a fetchNext()
228: which returns false is undefined.
229:
230: The result of calling fetchNext(row) is exactly logically
231: equivalent to making a next() call followed by a fetch(row)
232: call. This interface allows implementations to optimize
233: the 2 calls if possible.
234:
235: @param destRow The destRow row into which the value
236: of the next position in the scan is to be stored.
237:
238: @return True if there is a next position in the scan,
239: false if there isn't.
240:
241: @exception StandardException Standard exception policy.
242: @see ScanController#fetch
243: @see RowUtil
244: **/
245: boolean fetchNext(DataValueDescriptor[] destRow)
246: throws StandardException;
247:
248: /**
249: Fetch the location of the current position in the scan.
250: The destination location is replaced with the location
251: corresponding to the current position in the scan.
252: The destination location must be of the correct actual
253: type to accept a location from the underlying conglomerate
254: location.
255:
256: The results of a fetchLocation() performed on a scan after next() has
257: returned false are undefined.
258:
259: The results of a fetchLocation() performed on a scan positioned on
260: a deleted row are undefined, note that this can happen even if next()
261: has returned true (for instance the client can delete the row, or if
262: using read uncommitted another thread can delete the row after the
263: next() call but before the fetchLocation).
264:
265: @exception StandardException Standard exception policy.
266: **/
267: void fetchLocation(RowLocation destRowLocation)
268: throws StandardException;
269:
270: /**
271: Returns true if the current position of the scan is at a
272: deleted row. This case can come about if the current scan
273: or another scan on the same table in the same transaction
274: deleted the row after the next() call which positioned the
275: scan at this row.
276:
277: The results of a fetch() performed on a scan positioned on
278: a deleted row are undefined.
279:
280: @exception StandardException Standard exception policy.
281: **/
282: boolean isCurrentPositionDeleted() throws StandardException;
283:
284: /**
285: Move to the next position in the scan. If this is the first
286: call to next(), the position is set to the first row.
287: Returns false if there is not a next row to move to.
288: It is possible, but not guaranteed, that this method could return
289: true again, after returning false, if some other operation in the same
290: transaction appended a row to the underlying conglomerate.
291:
292: @return True if there is a next position in the scan,
293: false if there isn't.
294:
295: @exception StandardException Standard exception policy.
296: **/
297: boolean next() throws StandardException;
298:
299: /**
300: * Positions the scan at row location and locks the row.
301: * If the scan is not opened, it will be reopened if this is a holdable
302: * scan and there has not been any operations which causes RowLocations
303: * to be invalidated.
304: * @param rl RowLocation for the new position for the scan. The
305: * RowLocation submitted should be a RowLocation which has
306: * previously been returned by this ScanController.
307: * @return true if the scan has been positioned at the RowLocation.
308: * false if the scan could not be positioned.
309: *
310: * @exception StandardException Standard exception policy.
311: *
312: */
313: boolean positionAtRowLocation(RowLocation rl)
314: throws StandardException;
315:
316: /**
317: Replace the (partial) row at the current position of the scan.
318:
319: @return true if the replace was successful,
320: false if the current position is no longer valid (ie. if it was deleted).
321:
322: @exception StandardException Standard exception policy.
323: @see RowUtil
324: **/
325:
326: boolean replace(DataValueDescriptor[] row,
327: FormatableBitSet validColumns) throws StandardException;
328:
329: }
|