ScanController


1   /*
2   
3      Derby - Class org.apache.derby.iapi.store.access.ScanController
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.iapi.store.access;
23  
24  import org.apache.derby.iapi.services.io.Storable;
25  
26  import org.apache.derby.iapi.error.StandardException;
27  
28  import org.apache.derby.iapi.types.DataValueDescriptor;
29  
30  import org.apache.derby.iapi.types.RowLocation;
31  
32  import org.apache.derby.iapi.services.io.FormatableBitSet;
33  
34  /**
35  
36    A scan is the mechanism for iterating over the rows in a conglomerate,
37    the scan controller is the interface through which access clients
38    control the underlying scan.  An instance of a scan controller can 
39    be thought of as an open scan.
40    <p>
41    Scans are opened from a TransactionController.
42    <P>
43    A ScanController can handle partial rows. Partial rows
44    are described in RowUtil.
45    <BR>
46    A scan controller is opened with a FormatableBitSet that describes the
47    columns that need to be returned on a fetch call. This FormatableBitSet
48    need not include any columns referenced in the qualifers, start
49    and/or stop keys.
50  
51    @see TransactionController#openScan
52    @see GenericScanController
53    @see RowCountable
54    @see RowUtil
55  
56  **/
57  
58  public interface ScanController extends GenericScanController
59  {
60      /**
61  
62      GE is used to position a scan at values greater than or or equal to the
63      given key in the scan.  This positioning argument refers to the order 
64      within the scan (not necessarily actual compare calls on the datatypes).  
65      "greater" than is interpreted in terms of the 
66      current conglomerate and scan.  For instance, a btree may be ordered
67      ascending on an int, in that case a 2 is "greater" than 1 in a forward
68      scan on that index, and 1 is "greater" than 2 in a backward scan.
69      If the btree was ordered descending on an int then 1 is "greater" than
70      2 in a forward scan on that index, and 2 is "greater" than 1 in a backward
71      scan.
72  
73      @see TransactionController#openScan
74      */
75  
76      /* The value of this must be the same value returned by the Orderable
77       * interface when a key is > than another key.
78       */
79      public static final int GE = 1;
80  
81      /**
82      GT is used to position a scan at values greater than the given key.
83      This positioning argument refers to the order 
84      within the scan (not necessarily actual compare calls on the datatypes).  
85      "greater" than is interpreted in terms of the 
86      current conglomerate and scan.  For instance, a btree may be ordered
87      ascending on an int, in that case a 2 is "greater" than 1 in a forward
88      scan on that index, and 1 is "greater" than 2 in a backward scan.
89      If the btree was ordered descending on an int then 1 is "greater" than
90      2 in a forward scan on that index, and 2 is "greater" than 1 in a backward
91      scan.
92  
93      @see TransactionController#openScan
94      */
95      /* The value of this must be the same value returned by the Orderable
96       * interface when a key is < than another key.
97       */
98      public static final int GT = -1;
99  
100     /**
101     NA - argument is unused in call.  For some scans the key is set to null
102     to indicate no start or stop position, in those cases the position 
103     operator is ignored.
104 
105     @see TransactionController#openScan
106     */
107     /* The value of this must be the same value returned by the Orderable
108      * interface when a key is < than another key.
109      */
110     public static final int NA = 0;
111 
112     /**
113     Delete the row at the current position of the scan.
114 
115     @return true if the delete was successful,
116     false if the current position is no longer valid (ie. if it was already
117     deleted).
118 
119     @exception StandardException Standard exception policy.
120     **/
121     boolean delete()
122         throws StandardException;
123 
124     /**
125      * A call to allow client to indicate that current row does not qualify.
126      * <p>
127      * Indicates to the ScanController that the current row does not
128      * qualify for the scan.  If the isolation level of the scan allows, 
129      * this may result in the scan releasing the lock on this row.
130      * <p>
131      * Note that some scan implimentations may not support releasing locks on 
132      * non-qualifying rows, or may delay releasing the lock until sometime
133      * later in the scan (ie. it may be necessary to keep the lock until 
134      * either the scan is repositioned on the next row or page).
135      * <p>
136      * This call should only be made while the scan is positioned on a current
137      * valid row.
138      *
139      * @exception  StandardException  Standard exception policy.
140      **/
141     void didNotQualify() throws StandardException;
142 
143     /**
144     Returns true if the current position of the scan still qualifies
145     under the set of qualifiers passed to the openScan().  When called
146     this routine will reapply all qualifiers against the row currently
147     positioned and return true if the row still qualifies.  If the row
148     has been deleted or no longer passes the qualifiers then this routine
149     will return false.
150     
151     This case can come about if the current scan
152     or another scan on the same table in the same transaction 
153     deleted the row or changed columns referenced by the qualifier after 
154     the next() call which positioned the scan at this row.  
155 
156     Note that for comglomerates which don't support update, like btree's, 
157     there is no need to recheck the qualifiers.
158 
159     The results of a fetch() performed on a scan positioned on 
160     a deleted row are undefined, note that this can happen even if next()
161     has returned true (for instance the client can delete the row, or if
162     using read uncommitted another thread can delete the row after the
163     next() call but before the fetch).
164 
165     @exception StandardException Standard exception policy.
166     **/
167     boolean doesCurrentPositionQualify()
168         throws StandardException;
169 
170     /**
171     Fetch the (partial) row at the current position of the Scan.
172     The value in the destRow storable row is replaced
173     with the value of the row at the current scan
174     position.  The columns of the destRow row must
175     be of the same type as the actual columns in the
176     underlying conglomerate. The number of elements in
177     fetch must be compatible with the number of scan columns
178     requested at the openScan call time.
179     <BR>
180     A fetch can return a sub-set of the scan columns reqested
181     at scan open time by supplying a destRow will less elements
182     than the number of requested columns. In this case the N leftmost
183     of the requested columns are fetched, where N = destRow.length.
184     In the case where all columns are rested and N = 2 then columns 0 and 1
185     are returned. In the case where the openScan FormatableBitSet requested columns
186     1, 4 and 7, then columns 1 and 4 would be fetched when N = 2.
187     <BR>
188 
189     The results of a fetch() performed on a scan after next() has returned
190     false are undefined.
191 
192     A fetch() performed on a scan positioned on 
193     a deleted row will throw a StandardException with 
194     state = SQLState.AM_RECORD_NOT_FOUND.  Note that this can happen even if 
195     next() has returned true (for instance the client can delete the row, or if
196     using read uncommitted another thread can delete the row after the
197     next() call but before the fetch).
198 
199     @param destRow The row into which the value of the current 
200     position in the scan is to be stored.
201 
202     @exception StandardException Standard exception policy.
203     @see RowUtil
204     **/
205     void fetch(DataValueDescriptor[] destRow)
206         throws StandardException;
207 
208     /**
209      The same as fetch, except that the qualifiers passed to the openScan()
210      will not be applied. destRow will contain the current row even if it
211      has been changed and no longer qualifies.
212 
213      @param destRow The row into which the value of the current 
214      position in the scan is to be stored.
215 
216      @exception StandardException Standard exception policy.
217      */
218     void fetchWithoutQualify(DataValueDescriptor[] destRow)
219         throws StandardException;
220 
221     /**
222     Fetch the (partial) row at the next position of the Scan.
223 
224     If there is a valid next position in the scan then
225     the value in the destRow storable row is replaced
226     with the value of the row at the current scan
227     position.  The columns of the destRow row must
228     be of the same type as the actual columns in the
229     underlying conglomerate.
230 
231     The resulting contents of destRow after a fetchNext() 
232     which returns false is undefined.
233 
234     The result of calling fetchNext(row) is exactly logically
235     equivalent to making a next() call followed by a fetch(row)
236     call.  This interface allows implementations to optimize 
237     the 2 calls if possible.
238 
239     @param destRow The destRow row into which the value
240     of the next position in the scan is to be stored.
241 
242     @return True if there is a next position in the scan,
243     false if there isn't.
244 
245     @exception StandardException Standard exception policy.
246     @see ScanController#fetch
247     @see RowUtil
248     **/
249     boolean fetchNext(DataValueDescriptor[] destRow)
250         throws StandardException;
251 
252     /**
253     Fetch the location of the current position in the scan.
254     The destination location is replaced with the location
255     corresponding to the current position in the scan.
256     The destination location must be of the correct actual
257     type to accept a location from the underlying conglomerate
258     location.
259 
260     The results of a fetchLocation() performed on a scan after next() has 
261     returned false are undefined.
262 
263     The results of a fetchLocation() performed on a scan positioned on 
264     a deleted row are undefined, note that this can happen even if next()
265     has returned true (for instance the client can delete the row, or if
266     using read uncommitted another thread can delete the row after the
267     next() call but before the fetchLocation).
268 
269     @exception StandardException Standard exception policy.
270     **/
271     void fetchLocation(RowLocation destRowLocation)
272         throws StandardException;
273 
274     /**
275     Returns true if the current position of the scan is at a 
276     deleted row.  This case can come about if the current scan
277     or another scan on the same table in the same transaction 
278     deleted the row after the next() call which positioned the
279     scan at this row.  
280 
281     The results of a fetch() performed on a scan positioned on 
282     a deleted row are undefined.
283 
284     @exception StandardException Standard exception policy.
285     **/
286     boolean isCurrentPositionDeleted()
287         throws StandardException;
288 
289     /**
290     Move to the next position in the scan.  If this is the first
291     call to next(), the position is set to the first row.
292     Returns false if there is not a next row to move to.
293     It is possible, but not guaranteed, that this method could return 
294     true again, after returning false, if some other operation in the same 
295     transaction appended a row to the underlying conglomerate.
296 
297     @return True if there is a next position in the scan,
298     false if there isn't.
299 
300     @exception StandardException Standard exception policy.
301     **/
302     boolean next()
303         throws StandardException;
304 
305     /**
306      * Positions the scan at row location and locks the row. 
307      * If the scan is not opened, it will be reopened if this is a holdable 
308      * scan and there has not been any operations which causes RowLocations 
309      * to be invalidated.
310      * @param rl RowLocation for the new position for the scan. The 
311      *           RowLocation submitted should be a RowLocation which has 
312      *           previously been returned by this ScanController.
313      * @return true if the scan has been positioned at the RowLocation.
314      *         false if the scan could not be positioned.
315      * 
316      * @exception StandardException Standard exception policy.
317      *
318      */
319     boolean positionAtRowLocation(RowLocation rl) 
320         throws StandardException;
321 
322 
323     /**
324     Replace the (partial) row at the current position of the scan.
325 
326     @return true if the replace was successful,
327     false if the current position is no longer valid (ie. if it was deleted).
328 
329     @exception StandardException Standard exception policy.
330     @see RowUtil
331     **/
332 
333     boolean replace(DataValueDescriptor[] row, FormatableBitSet validColumns)
334         throws StandardException;
335 
336 }
337
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags