Scan


1   /*
2   
3      Derby - Class org.apache.derby.impl.store.access.sort.Scan
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.impl.store.access.sort;
23  
24  import org.apache.derby.iapi.reference.SQLState;
25  
26  import org.apache.derby.iapi.store.access.BackingStoreHashtable;
27  import org.apache.derby.iapi.services.io.FormatableBitSet;
28  import org.apache.derby.iapi.services.i18n.MessageService;
29  
30  import org.apache.derby.iapi.services.io.Storable;
31  
32  import org.apache.derby.iapi.types.Orderable;
33  import org.apache.derby.iapi.types.RowLocation;
34  
35  import org.apache.derby.iapi.error.StandardException;
36  
37  import org.apache.derby.iapi.store.access.conglomerate.Conglomerate;
38  import org.apache.derby.iapi.store.access.conglomerate.ScanManager;
39  
40  import org.apache.derby.iapi.store.access.Qualifier;
41  import org.apache.derby.iapi.store.access.ScanController;
42  import org.apache.derby.iapi.store.access.ScanInfo;
43  
44  import org.apache.derby.iapi.store.raw.Page;
45  
46  import org.apache.derby.iapi.types.DataValueDescriptor;
47  
48  import java.util.Properties  ;
49  
50  /**
51  
52      Abstract base class for all sort classes which return rows from the
53      sort.  Subclasses must implement fetch, next, and close.
54  
55  **/
56  
57  public abstract class Scan implements ScanManager, ScanInfo
58  {
59      /*
60       * Methods of ScanController
61       */
62  
63      /**
64       * A call to allow client to indicate that current row does not qualify.
65       * <p>
66       * Indicates to the ScanController that the current row does not
67       * qualify for the scan.  If the isolation level of the scan allows, 
68       * this may result in the scan releasing the lock on this row.
69       * <p>
70       * Note that some scan implimentations may not support releasing locks on 
71       * non-qualifying rows, or may delay releasing the lock until sometime
72       * later in the scan (ie. it may be necessary to keep the lock until 
73       * either the scan is repositioned on the next row or page).
74       * <p>
75       * This call should only be made while the scan is positioned on a current
76       * valid row.
77       * <p>
78       * This call does not make sense for sort scans.
79       *
80       * @exception  StandardException  Standard exception policy.
81       **/
82      public void didNotQualify()
83          throws StandardException
84      {
85      }
86  
87      /**
88       * Fetch the next N rows from the table.
89       * <p>
90       * Currently unimplemented for sorts.
91       * <p>
92       **/
93      public int fetchNextGroup(
94      DataValueDescriptor[][]     row_array,
95      RowLocation[]               rowloc_array)
96          throws StandardException
97      {
98          throw StandardException.newException(
99                  SQLState.SORT_IMPROPER_SCAN_METHOD);
100     }
101 
102     public int fetchNextGroup(
103     DataValueDescriptor[][]     row_array,
104     RowLocation[]               old_rowloc_array,
105     RowLocation[]               new_rowloc_array)
106         throws StandardException
107     {
108         throw StandardException.newException(
109                 SQLState.SORT_IMPROPER_SCAN_METHOD);
110     }
111 
112 
113     /**
114      * Insert all rows that qualify for the current scan into the input
115      * Hash table.  
116      * <p>
117      * Currently unimplemented for sorts.
118      * <p>
119      **/
120     public void fetchSet(
121     long                    max_rowcnt,
122     int[]                   key_column_numbers,
123     BackingStoreHashtable   hash_table)
124         throws StandardException
125     {
126         throw StandardException.newException(
127                 SQLState.SORT_IMPROPER_SCAN_METHOD);
128     }
129 
130     /**
131     Returns true if the current position of the scan still qualifies
132     under the set of qualifiers passed to the openScan().
133     @see ScanController#doesCurrentPositionQualify
134     **/
135     public boolean doesCurrentPositionQualify()
136         throws StandardException
137     {
138         return true;
139     }
140 
141     /**
142     Fetch the location of the current position in the scan.
143     @see ScanController#fetchLocation
144     **/
145     public void fetchLocation(RowLocation templateLocation)
146         throws StandardException
147     {
148         throw StandardException.newException(
149                 SQLState.SORT_IMPROPER_SCAN_METHOD);
150     }
151 
152     /**
153      * Return ScanInfo object which describes performance of scan.
154      * <p>
155      * Return ScanInfo object which contains information about the current
156      * scan.
157      * <p>
158      * Currently the ScanInfo does not have any performance data.
159      *
160      * @see ScanInfo
161      *
162      * @return The ScanInfo object which contains info about current scan.
163      *
164      * @exception  StandardException  Standard exception policy.
165      **/
166     public ScanInfo getScanInfo()
167         throws StandardException
168     {
169         return(this);
170     }
171 
172     /**
173      * Get the total estimated number of rows in the container.
174      * <p>
175      * The number is a rough estimate and may be grossly off.  In general
176      * the server will cache the row count and then occasionally write
177      * the count unlogged to a backing store.  If the system happens to 
178      * shutdown before the store gets a chance to update the row count it
179      * may wander from reality.
180      * <p>
181      * This call is currently only supported on Heap conglomerates, it
182      * will throw an exception if called on btree conglomerates.
183      *
184      * @return The total estimated number of rows in the conglomerate.
185      *
186      * @exception  StandardException  Standard exception policy.
187      **/
188     public long getEstimatedRowCount()
189         throws StandardException
190     {
191         throw StandardException.newException(
192                 SQLState.SORT_IMPROPER_SCAN_METHOD);
193     }
194 
195     /**
196      * Set the total estimated number of rows in the container.
197      * <p>
198      * Often, after a scan, the client of RawStore has a much better estimate
199      * of the number of rows in the container than what store has.  For 
200      * instance if we implement some sort of update statistics command, or
201      * just after a create index a complete scan will have been done of the
202      * table.  In this case this interface allows the client to set the
203      * estimated row count for the container, and store will use that number
204      * for all future references.
205      * <p>
206      * This call is currently only supported on Heap conglomerates, it
207      * will throw an exception if called on btree conglomerates.
208      *
209      * @param count the estimated number of rows in the container.
210      *
211      * @exception  StandardException  Standard exception policy.
212      **/
213     public void setEstimatedRowCount(long count)
214         throws StandardException
215     {
216         throw StandardException.newException(
217                 SQLState.SORT_IMPROPER_SCAN_METHOD);
218     }
219 
220     /**
221     Returns true if the current position of the scan is at a 
222     deleted row.
223     @see ScanController#isCurrentPositionDeleted
224     **/
225     public boolean isCurrentPositionDeleted()
226         throws StandardException
227     {
228         throw StandardException.newException(
229                 SQLState.SORT_IMPROPER_SCAN_METHOD);
230     }
231 
232     /**
233      * Return whether this is a keyed conglomerate.
234      * <p>
235      *
236      * @return whether this is a keyed conglomerate.
237      **/
238     public boolean isKeyed()
239     {
240         return(false);
241     }
242 
243     /**
244      * Return whether this scan is table locked.
245      *
246      * @return whether this is table locked.
247      **/
248     public boolean isTableLocked()
249     {
250         return(true);
251     }
252 
253     /**
254     Delete the row at the current position of the scan.
255     @see ScanController#delete
256     **/
257     public boolean delete()
258         throws StandardException
259     {
260         throw StandardException.newException(
261                 SQLState.SORT_IMPROPER_SCAN_METHOD);
262     }
263 
264     /**
265     Reposition the current scan.
266     @see ScanController#reopenScan
267     **/
268     public void reopenScan(
269     DataValueDescriptor[]   startKeyValue,
270     int                     startSearchOperator,
271     Qualifier               qualifier[][],
272     DataValueDescriptor[]   stopKeyValue,
273     int                     stopSearchOperator)
274         throws StandardException
275     {
276         throw StandardException.newException(
277                 SQLState.SORT_IMPROPER_SCAN_METHOD);
278     }
279 
280     /**
281     Reposition the current scan.  This call is semantically the same as if
282     the current scan had been closed and a openScan() had been called instead.
283     The scan is reopened against the same conglomerate, and the scan
284     is reopened with the same "scan column list", "hold" and "forUpdate"
285     parameters passed in the original openScan.  
286 
287     @exception StandardException Standard exception policy.
288     **/
289     public void reopenScanByRowLocation(
290     RowLocation startRowLocation,
291     Qualifier qualifier[][])
292         throws StandardException
293     {
294         throw StandardException.newException(
295                 SQLState.SORT_IMPROPER_SCAN_METHOD);
296     }
297 
298     /**
299     Replace the entire row at the current position of the scan.
300     @see ScanController#replace
301     **/
302     public boolean replace(
303     DataValueDescriptor[]   val, 
304     FormatableBitSet                 validColumns)
305         throws StandardException
306     {
307         throw StandardException.newException(
308                 SQLState.SORT_IMPROPER_SCAN_METHOD);
309     }
310 
311     /**
312     Return a row location object of the correct type to be
313     used in calls to fetchLocation.
314     @see ScanController#newRowLocationTemplate
315     **/
316     public RowLocation newRowLocationTemplate()
317         throws StandardException
318     {
319         throw StandardException.newException(
320                 SQLState.SORT_IMPROPER_SCAN_METHOD);
321     }
322 
323     /**
324      *@see ScanController#positionAtRowLocation
325      */
326     public boolean positionAtRowLocation(RowLocation rl) 
327         throws StandardException 
328     {
329         throw StandardException.newException(
330                 SQLState.SORT_IMPROPER_SCAN_METHOD);
331     }
332 
333     /*
334     ** Methods of ScanManager
335     */
336 
337     /**
338      * Do work necessary to maintain the current position in the scan.
339      * <p>
340      * The latched page in the conglomerate "congomid" is changing, do
341      * whatever is necessary to maintain the current position of the scan.
342      * For some conglomerates this may be a no-op.
343      * <p>
344      *
345      * @param conglom   Conglomerate object of the conglomerate being changed.
346      * @param page      Page in the conglomerate being changed.
347      *
348      * @exception  StandardException  Standard exception policy.
349      **/
350     public void savePosition(Conglomerate conglom, Page page)
351         throws StandardException
352     {
353         // RESOLVE (mikem), under the current implementation all scans within
354         // a transaction are called rather than just the ones with the right
355         // conglomid.  For now just have sort scans ignore the call. 
356         
357         return;
358     }
359 
360     /*
361      * Methods of ScanInfo
362      */
363    
364     /**
365      * Return all information gathered about the scan.
366      * <p>
367      * This routine returns a list of properties which contains all information
368      * gathered about the scan.  If a Property is passed in, then that property
369      * list is appeneded to, otherwise a new property object is created and
370      * returned.
371      * <p>
372      * Currently sort scans doesn't track any information.
373      *
374      * @param prop   Property list to fill in.
375      *
376      * @exception  StandardException  Standard exception policy.
377      **/
378     public Properties   getAllScanInfo(Properties   prop)
379         throws StandardException
380     {
381         if (prop == null)
382             prop = new Properties  ();
383 
384         prop.put(
385             MessageService.getTextMessage(SQLState.STORE_RTS_SCAN_TYPE),
386             MessageService.getTextMessage(SQLState.STORE_RTS_SORT));
387 
388         return(prop);
389     }
390 }
391
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags