KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > GenericScanController


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.GenericScanController
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   The set of interfaces implemented by all types of ScanControllers.
37   <P>
38   A scan is the mechanism for iterating over the rows in a conglomerate,
39   the scan controller is the interface through which access clients
40   control the underlying scan. An instance of a scan controller can
41   be thought of as an open scan.
42   <p>
43   Scans are opened from a TransactionController.
44   <P>
45   A ScanController can handle partial rows. Partial rows are described in
46   RowUtil.
47   <BR>
48   A scan controller is opened with a FormatableBitSet that describes the
49   columns that need to be returned on a fetch call. This FormatableBitSet
50   need not include any columns referenced in the qualifers, start
51   and/or stop keys.
52
53   @see TransactionController#openScan
54   @see RowCountable
55   @see RowUtil
56
57 **/
58
59 public interface GenericScanController extends RowCountable
60 {
61     /**
62     Close the scan. This method always succeeds, and never throws
63     any exceptions. Callers must not use the scan controller after
64     closing it; they are strongly advised to clear out the scan
65     controller reference after closing.
66
67     @exception StandardException Standard exception policy.
68     **/
69     void close()
70         throws StandardException;
71
72     /**
73      * Return ScanInfo object which describes performance of scan.
74      * <p>
75      * Return ScanInfo object which contains information about the current
76      * state of the scan.
77      * <p>
78      * The statistics gathered by the scan are not reset to 0 by a reopenScan(),
79      * rather they continue to accumulate.
80      * <p>
81      *
82      *
83      * @see ScanInfo
84      *
85      * @return The ScanInfo object which contains info about current scan.
86      *
87      * @exception StandardException Standard exception policy.
88      **/
89     ScanInfo getScanInfo()
90         throws StandardException;
91
92     /**
93      * Return whether this is a keyed conglomerate.
94      * <p>
95      *
96      * @return whether this is a keyed conglomerate.
97      **/
98     boolean isKeyed();
99
100     /**
101      * Return whether this scan is table locked.
102      * <p>
103      * Implementation of this is not complete. Currently it does not give back
104      * the right information on covering locks or lock escalation. If the
105      * openScan() caller specifies a MODE_TABLE as the lock_level then this
106      * routine will always return true. If the openScan() caller specifies a
107      * MODE_RECORD as the lock_level then this routine will return true iff
108      * the lock level of the system has been overridden either by the
109      * derby.storage.rowLocking=false property, or by a shipped
110      * configuration which disables row locking.
111      * <p>
112      *
113      * @return whether this scan is table locked.
114      **/
115     boolean isTableLocked();
116
117     /**
118      * Return a row location object to be used in calls to fetchLocation.
119      * <p>
120      * Return a row location object of the correct type to be used in calls to
121      * fetchLocation.
122      * <p>
123      *
124      * @return a row location object to be used in calls to fetchLocation.
125      *
126      * @exception StandardException Standard exception policy.
127      **/
128     RowLocation newRowLocationTemplate()
129         throws StandardException;
130
131     /**
132     Reposition the current scan. This call is semantically the same as if
133     the current scan had been closed and a openScan() had been called instead.
134     The scan is reopened with against the same conglomerate, and the scan
135     is reopened with the same "scan column list", "hold" and "forUpdate"
136     parameters passed in the original openScan.
137     <p>
138     The statistics gathered by the scan are not reset to 0 by a reopenScan(),
139     rather they continue to accumulate.
140     <p>
141
142     @param startKeyValue An indexable row which holds a
143     (partial) key value which, in combination with the
144     startSearchOperator, defines the starting position of
145     the scan. If null, the starting position of the scan
146     is the first row of the conglomerate.
147     
148     @param startSearchOperator an operator which defines
149     how the startKeyValue is to be searched for. If
150     startSearchOperator is ScanController.GE, the scan starts on
151     the first row which is greater than or equal to the
152     startKeyValue. If startSearchOperation is ScanController.GT,
153     the scan starts on the first row whose key is greater than
154     startKeyValue. The startSearchOperation parameter is
155     ignored if the startKeyValue parameter is null.
156
157     @param qualifier An array of qualifiers which, applied
158     to each key, restrict the rows returned by the scan. Rows
159     for which any one of the qualifiers returns false are not
160     returned by the scan. If null, all rows are returned.
161
162     @param stopKeyValue An indexable row which holds a
163     (partial) key value which, in combination with the
164     stopSearchOperator, defines the ending position of
165     the scan. If null, the ending position of the scan
166     is the last row of the conglomerate.
167     
168     @param stopSearchOperator an operator which defines
169     how the stopKeyValue is used to determine the scan stopping
170     position. If stopSearchOperation is ScanController.GE, the scan
171     stops just before the first row which is greater than or
172     equal to the stopKeyValue. If stopSearchOperation is
173     ScanController.GT, the scan stops just before the first row whose
174     key is greater than startKeyValue. The stopSearchOperation
175     parameter is ignored if the stopKeyValue parameter is null.
176
177     @exception StandardException Standard exception policy.
178     **/
179     void reopenScan(
180     DataValueDescriptor[] startKeyValue,
181     int startSearchOperator,
182     Qualifier qualifier[][],
183     DataValueDescriptor[] stopKeyValue,
184     int stopSearchOperator)
185         throws StandardException;
186
187     /**
188     Reposition the current scan. This call is semantically the same as if
189     the current scan had been closed and a openScan() had been called instead.
190     The scan is reopened against the same conglomerate, and the scan
191     is reopened with the same "scan column list", "hold" and "forUpdate"
192     parameters passed in the original openScan.
193     <p>
194     The statistics gathered by the scan are not reset to 0 by a reopenScan(),
195     rather they continue to accumulate.
196     <p>
197     Note that this operation is currently only supported on Heap conglomerates.
198     Also note that order of rows within are heap are not guaranteed, so for
199     instance positioning at a RowLocation in the "middle" of a heap, then
200     inserting more data, then continuing the scan is not guaranteed to see
201     the new rows - they may be put in the "beginning" of the heap.
202
203     @param startRowLocation An existing RowLocation within the conglomerate,
204     at which to position the start of the scan. The scan will begin at this
205     location and continue forward until the end of the conglomerate.
206     Positioning at a non-existent RowLocation (ie. an invalid one or one that
207     had been deleted), will result in an exception being thrown when the
208     first next operation is attempted.
209
210     @param qualifier An array of qualifiers which, applied
211     to each key, restrict the rows returned by the scan. Rows
212     for which any one of the qualifiers returns false are not
213     returned by the scan. If null, all rows are returned.
214
215     @exception StandardException Standard exception policy.
216     **/
217     void reopenScanByRowLocation(
218     RowLocation startRowLocation,
219     Qualifier qualifier[][])
220         throws StandardException;
221 }
222
Popular Tags