KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > impl > sql > execute > TemporaryRowHolderResultSet


1 /*
2
3    Derby - Class org.apache.derby.impl.sql.execute.TemporaryRowHolderResultSet
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.sql.execute;
23
24 import org.apache.derby.iapi.services.sanity.SanityManager;
25 import org.apache.derby.iapi.error.StandardException;
26
27 import org.apache.derby.iapi.store.access.ConglomerateController;
28 import org.apache.derby.iapi.store.access.ScanController;
29 import org.apache.derby.iapi.store.access.TransactionController;
30
31 import org.apache.derby.iapi.reference.SQLState;
32
33 import org.apache.derby.iapi.sql.execute.CursorResultSet;
34 import org.apache.derby.iapi.sql.execute.ExecRow;
35 import org.apache.derby.iapi.sql.execute.ExecutionContext;
36 import org.apache.derby.iapi.sql.execute.NoPutResultSet;
37 import org.apache.derby.iapi.sql.execute.ExecutionFactory;
38 import org.apache.derby.iapi.sql.execute.TargetResultSet;
39
40 import org.apache.derby.iapi.sql.Activation;
41 import org.apache.derby.iapi.sql.ResultDescription;
42 import org.apache.derby.iapi.sql.ResultSet;
43 import org.apache.derby.iapi.sql.Row;
44
45 import org.apache.derby.iapi.types.DataValueDescriptor;
46 import org.apache.derby.iapi.types.RowLocation;
47 import org.apache.derby.iapi.sql.execute.ExecIndexRow;
48 import org.apache.derby.iapi.types.SQLLongint;
49
50 import org.apache.derby.iapi.services.io.FormatableBitSet;
51 import java.sql.Timestamp JavaDoc;
52
53
54 /**
55  * A result set to scan temporary row holders. Ultimately, this
56  * may be returned to users, hence the extra junk from the ResultSet
57  * interface.
58  *
59  * @author jamie
60  */
61 class TemporaryRowHolderResultSet implements CursorResultSet, NoPutResultSet, Cloneable JavaDoc
62 {
63     private ExecRow[] rowArray;
64     private int numRowsOut;
65     private ScanController scan;
66     private TransactionController tc;
67     private boolean isOpen;
68     private boolean finished;
69     private ExecRow currentRow;
70     private ResultDescription resultDescription;
71     private ExecutionFactory ef;
72     private boolean isAppendable = false;
73     private long positionIndexConglomId;
74     private boolean isVirtualMemHeap;
75     private boolean currRowFromMem;
76     private TemporaryRowHolderImpl holder;
77
78     // the following is used by position based scan, as well as virtual memory style heap
79 ConglomerateController heapCC;
80     private RowLocation baseRowLocation;
81
82     /**
83      * Constructor
84      *
85      * @param tc the xact controller
86      * @param rowArray the row array
87      * @param resultDescription value returned by getResultDescription()
88      */
89     public TemporaryRowHolderResultSet
90     (
91         TransactionController tc,
92         ExecRow[] rowArray,
93         ResultDescription resultDescription,
94         boolean isVirtualMemHeap,
95         TemporaryRowHolderImpl holder
96     )
97     {
98
99         this(tc, rowArray, resultDescription, isVirtualMemHeap, false, 0, holder);
100
101
102     }
103
104     /**
105      * Constructor
106      *
107      * @param tc the xact controller
108      * @param rowArray the row array
109      * @param resultDescription value returned by getResultDescription()
110      * @param isAppendable true,if we can insert rows after this result is created
111      * @param positionIndexConglomId conglomId of the index which has order rows
112      * are inserted and their row location
113      */
114     public TemporaryRowHolderResultSet
115     (
116         TransactionController tc,
117         ExecRow[] rowArray,
118         ResultDescription resultDescription,
119         boolean isVirtualMemHeap,
120         boolean isAppendable,
121         long positionIndexConglomId,
122         TemporaryRowHolderImpl holder
123     )
124     {
125         this.tc = tc;
126         this.rowArray = rowArray;
127         this.resultDescription = resultDescription;
128         this.numRowsOut = 0;
129         isOpen = false;
130         finished = false;
131         this.isVirtualMemHeap = isVirtualMemHeap;
132         this.isAppendable = isAppendable;
133         this.positionIndexConglomId = positionIndexConglomId;
134
135         if (SanityManager.DEBUG)
136         {
137             SanityManager.ASSERT(rowArray != null, "rowArray is null");
138             SanityManager.ASSERT(rowArray.length > 0, "rowArray has no elements, need at least one");
139         }
140
141         this.holder = holder;
142     }
143
144     /**
145      * Reset the exec row array and reinitialize
146      *
147      * @param rowArray the row array
148      */
149     public void reset(ExecRow[] rowArray)
150     {
151         this.rowArray = rowArray;
152         this.numRowsOut = 0;
153         isOpen = false;
154         finished = false;
155
156         if (SanityManager.DEBUG)
157         {
158             SanityManager.ASSERT(rowArray != null, "rowArray is null");
159             SanityManager.ASSERT(rowArray.length > 0, "rowArray has no elements, need at least one");
160         }
161     }
162
163
164     /**
165      * postion scan to start from after where we stopped earlier
166      */
167     public void reStartScan(long currentConglomId, long pconglomId) throws StandardException
168     {
169         if(isAppendable)
170         {
171             holder.CID = currentConglomId;
172             positionIndexConglomId = pconglomId;
173             setupPositionBasedScan(numRowsOut);
174         }else
175         {
176             numRowsOut--;
177         }
178     }
179
180
181     /**
182      * Whip up a new Temp ResultSet that has a single
183      * row, the current row of this result set.
184      *
185      * @param activation the activation
186      * @param rs the result set
187      *
188      * @return a single row result set
189      *
190      * @exception StandardException on error
191      */
192     public static TemporaryRowHolderResultSet getNewRSOnCurrentRow
193     (
194         Activation activation,
195         CursorResultSet rs
196     ) throws StandardException
197     {
198         TemporaryRowHolderImpl singleRow =
199             new TemporaryRowHolderImpl(activation, null,
200                                        rs.getResultDescription());
201         singleRow.insert(rs.getCurrentRow());
202         return (TemporaryRowHolderResultSet) singleRow.getResultSet();
203     }
204
205     /////////////////////////////////////////////////////////
206 //
207 // NoPutResultSet
208 //
209 /////////////////////////////////////////////////////////
210 /**
211      * Mark the ResultSet as the topmost one in the ResultSet tree.
212      * Useful for closing down the ResultSet on an error.
213      */
214     public void markAsTopResultSet()
215     { }
216
217     /**
218      * Open the scan and evaluate qualifiers and the like.
219      * For us, there are no qualifiers, this is really a
220      * noop.
221      */
222     public void openCore() throws StandardException
223     {
224         this.numRowsOut = 0;
225         isOpen = true;
226         currentRow = null;
227
228         if(isAppendable)
229             setupPositionBasedScan(numRowsOut);
230     }
231
232     /**
233      * Reopen the scan. Typically faster than open()/close()
234      *
235      * @exception StandardException on error
236      */
237     public void reopenCore() throws StandardException
238     {
239         numRowsOut = 0;
240         isOpen = true;
241         currentRow = null;
242
243         if(isAppendable)
244         {
245             setupPositionBasedScan(numRowsOut);
246             return;
247         }
248
249         if (scan != null)
250         {
251             scan.reopenScan(
252                 (DataValueDescriptor[]) null, // start key value
253 0, // start operator
254 null, // qualifier
255 (DataValueDescriptor[]) null, // stop key value
256 0); // stop operator
257 }
258     }
259
260     /**
261      * Get the next row.
262      *
263      * @return the next row, or null if none
264      *
265      * @exception StandardException on error
266      */
267     public ExecRow getNextRowCore()
268         throws StandardException
269     {
270
271         if (!isOpen)
272         {
273             return (ExecRow)null;
274         }
275             
276         if(isAppendable)
277         {
278             return getNextAppendedRow() ;
279         }
280
281         if (isVirtualMemHeap && holder.lastArraySlot >= 0)
282         {
283             numRowsOut++;
284             currentRow = rowArray[holder.lastArraySlot];
285             currRowFromMem = true;
286             return currentRow;
287         }
288         else if (numRowsOut++ <= holder.lastArraySlot)
289         {
290             currentRow = rowArray[numRowsOut-1];
291             return currentRow;
292         }
293
294         if (holder.CID == 0)
295         {
296             return (ExecRow)null;
297         }
298             
299         /*
300         ** Advance in the temporary conglomerate
301         */
302         if (scan == null)
303         {
304             scan =
305                 tc.openScan(
306                     holder.CID,
307                     false, // hold
308 0, // open read only
309 TransactionController.MODE_TABLE,
310                     TransactionController.ISOLATION_SERIALIZABLE,
311                     (FormatableBitSet) null,
312                     (DataValueDescriptor[]) null, // start key value
313 0, // start operator
314 null, // qualifier
315 (DataValueDescriptor[]) null, // stop key value
316 0); // stop operator
317 }
318         else if (isVirtualMemHeap && holder.state == TemporaryRowHolderImpl.STATE_INSERT)
319         {
320             holder.state = TemporaryRowHolderImpl.STATE_DRAIN;
321             scan.reopenScan(
322                 (DataValueDescriptor[]) null, // start key value
323 0, // start operator
324 null, // qualifier
325 (DataValueDescriptor[]) null, // stop key value
326 0); // stop operator
327 }
328
329         if (scan.next())
330         {
331             currentRow = rowArray[0].getNewNullRow();
332             scan.fetch(currentRow.getRowArray());
333             currRowFromMem = false;
334             return currentRow;
335         }
336         return (ExecRow)null;
337     }
338
339     public void deleteCurrentRow()
340         throws StandardException
341     {
342         if (SanityManager.DEBUG)
343         {
344             SanityManager.ASSERT(isVirtualMemHeap, "deleteCurrentRow is not implemented");
345         }
346         if (currRowFromMem)
347         {
348             if (holder.lastArraySlot > 0) // 0 is kept for template
349 rowArray[holder.lastArraySlot] = null; // erase reference
350 holder.lastArraySlot--;
351         }
352         else
353         {
354             if (baseRowLocation == null)
355                 baseRowLocation = scan.newRowLocationTemplate();
356             scan.fetchLocation(baseRowLocation);
357             if(heapCC == null)
358             {
359                 heapCC = tc.openConglomerate( holder.CID,
360                                               false,
361                                               TransactionController.OPENMODE_FORUPDATE,
362                                               TransactionController.MODE_TABLE,
363                                               TransactionController.ISOLATION_SERIALIZABLE);
364             }
365             heapCC.delete(baseRowLocation);
366         }
367     }
368
369
370     //following variables are specific to the position based scans.
371 DataValueDescriptor[] indexRow;
372     ScanController indexsc;
373
374     //open the scan of the temporary heap and the position index
375 private void setupPositionBasedScan(long position) throws StandardException
376     {
377
378         //incase nothing is inserted yet into the temporary row holder
379 if(holder.CID ==0)
380             return;
381         if(heapCC == null)
382         {
383             heapCC = tc.openConglomerate( holder.CID,
384                                           false,
385                                           0,
386                                           TransactionController.MODE_TABLE,
387                                           TransactionController.ISOLATION_SERIALIZABLE);
388
389         }
390
391         currentRow = rowArray[0].getNewNullRow();
392         indexRow = new DataValueDescriptor[2];
393         indexRow[0] = new SQLLongint(position);
394         indexRow[1] = heapCC.newRowLocationTemplate();
395
396         DataValueDescriptor[] searchRow = new DataValueDescriptor[1];
397         searchRow[0] = new SQLLongint(position);
398
399         if(indexsc == null)
400         {
401             indexsc = tc.openScan(positionIndexConglomId,
402                                   false, // don't hold open across commit
403 0, // for read
404 TransactionController.MODE_TABLE,
405                                   TransactionController.ISOLATION_SERIALIZABLE,
406                                   (FormatableBitSet) null, // all fields as objects
407 searchRow, // start position - first row
408 ScanController.GE, // startSearchOperation
409 null, //scanQualifier,
410 null, // stop position - through last row
411 ScanController.GT); // stopSearchOperation
412 }else
413         {
414
415             indexsc.reopenScan(
416                         searchRow, // startKeyValue
417 ScanController.GE, // startSearchOp
418 null, // qualifier
419 null, // stopKeyValue
420 ScanController.GT // stopSearchOp
421 );
422         }
423         
424     }
425
426
427     //get the next row inserted into the temporary holder
428 private ExecRow getNextAppendedRow() throws StandardException
429     {
430         if (indexsc == null) return null;
431         if (!indexsc.fetchNext(indexRow))
432         {
433             return null;
434         }
435         
436         RowLocation baseRowLocation = (RowLocation) indexRow[1];
437         boolean base_row_exists =
438             heapCC.fetch(
439                 baseRowLocation, currentRow.getRowArray(), (FormatableBitSet) null);
440
441         if (SanityManager.DEBUG)
442         {
443             SanityManager.ASSERT(base_row_exists, "base row disappeared.");
444         }
445         numRowsOut++;
446         return currentRow;
447     }
448
449
450
451     /**
452      * Return the point of attachment for this subquery.
453      * (Only meaningful for Any and Once ResultSets, which can and will only
454      * be at the top of a ResultSet for a subquery.)
455      *
456      * @return int Point of attachment (result set number) for this
457      * subquery. (-1 if not a subquery - also Sanity violation)
458      */
459     public int getPointOfAttachment()
460     {
461         return -1;
462     }
463
464     /**
465      * Return the isolation level of the scan in the result set.
466      * Only expected to be called for those ResultSets that
467      * contain a scan.
468      *
469      * @return The isolation level of the scan (in TransactionController constants).
470      */
471     public int getScanIsolationLevel()
472     {
473         return TransactionController.ISOLATION_SERIALIZABLE;
474     }
475
476     /**
477      * Notify a NPRS that it is the source for the specified
478      * TargetResultSet. This is useful when doing bulk insert.
479      *
480      * @param trs The TargetResultSet.
481      */
482     public void setTargetResultSet(TargetResultSet trs)
483     {
484     }
485
486     /**
487      * Set whether or not the NPRS need the row location when acting
488      * as a row source. (The target result set determines this.)
489      *
490      */
491     public void setNeedsRowLocation(boolean needsRowLocation)
492     {
493     }
494
495     /**
496      * Get the estimated row count from this result set.
497      *
498      * @return The estimated row count (as a double) from this result set.
499      */
500     public double getEstimatedRowCount()
501     {
502         return 0d;
503     }
504
505     /**
506      * Get the number of this ResultSet, which is guaranteed to be unique
507      * within a statement.
508      */
509     public int resultSetNumber()
510     {
511         return 0;
512     }
513
514     /**
515      * Set the current row to the row passed in.
516      *
517      * @param row the new current row
518      *
519      */
520     public void setCurrentRow(ExecRow row)
521     {
522         currentRow = row;
523     }
524
525     /**
526      * Clear the current row
527      *
528      */
529     public void clearCurrentRow()
530     {
531         currentRow = null;
532     }
533
534     /**
535      * This result set has its row from the last fetch done.
536      * If the cursor is closed, a null is returned.
537      *
538      * @see CursorResultSet
539      *
540      * @return the last row returned;
541      * @exception StandardException thrown on failure.
542      */
543     public ExecRow getCurrentRow() throws StandardException
544     {
545         if (SanityManager.DEBUG)
546         {
547             SanityManager.ASSERT(isOpen, "resultSet expected to be open");
548         }
549
550         return currentRow;
551     }
552
553     /**
554      * Returns the row location of the current base table row of the cursor.
555      * If this cursor's row is composed of multiple base tables' rows,
556      * i.e. due to a join, then a null is returned. For
557      * a temporary row holder, we always return null.
558      *
559      * @return the row location of the current cursor row.
560      */
561     public RowLocation getRowLocation()
562     {
563         if (SanityManager.DEBUG)
564         {
565             SanityManager.ASSERT(isOpen, "resultSet expected to be open");
566         }
567         return (RowLocation)null;
568     }
569
570
571     /**
572      * Clean up
573      *
574      * @exception StandardException thrown on error
575      */
576     public void close() throws StandardException
577     {
578         isOpen = false;
579         numRowsOut = 0;
580         currentRow = null;
581         if (scan != null)
582         {
583             scan.close();
584             scan = null;
585         }
586     }
587
588
589     //////////////////////////////////////////////////////////////////////////
590 //
591 // MISC FROM RESULT SET
592 //
593 /////////////////////////////////////////////////////////////////////////
594
595     /**
596      * Returns TRUE if the statement returns rows (i.e. is a SELECT
597      * or FETCH statement), FALSE if it returns no rows.
598      *
599      * @return TRUE if the statement returns rows, FALSE if not.
600      */
601     public boolean returnsRows()
602     {
603         return true;
604     }
605
606     public int modifiedRowCount() { return 0;};
607
608     /**
609      * Returns a ResultDescription object, which describes the results
610      * of the statement this ResultSet is in. This will *not* be a
611      * description of this particular ResultSet, if this is not the
612      * outermost ResultSet.
613      *
614      * @return A ResultDescription describing the results of the
615      * statement.
616      */
617     public ResultDescription getResultDescription()
618     {
619         return resultDescription;
620     }
621
622     /**
623      * Tells the system that there will be calls to getNextRow().
624      *
625      * @exception StandardException Thrown on failure
626      */
627     public void open() throws StandardException
628     {
629         openCore();
630     }
631
632     /**
633      * Returns the row at the absolute position from the query,
634      * and returns NULL when there is no such position.
635      * (Negative position means from the end of the result set.)
636      * Moving the cursor to an invalid position leaves the cursor
637      * positioned either before the first row (negative position)
638      * or after the last row (positive position).
639      * NOTE: An exception will be thrown on 0.
640      *
641      * @param row The position.
642      * @return The row at the absolute position, or NULL if no such position.
643      *
644      * @exception StandardException Thrown on failure
645      * @see Row
646      */
647     public ExecRow getAbsoluteRow(int row) throws StandardException
648     {
649         if (SanityManager.DEBUG)
650         {
651             SanityManager.THROWASSERT(
652                 "getAbsoluteRow() not expected to be called yet.");
653         }
654
655         return null;
656     }
657
658     /**
659      * Returns the row at the relative position from the current
660      * cursor position, and returns NULL when there is no such position.
661      * (Negative position means toward the beginning of the result set.)
662      * Moving the cursor to an invalid position leaves the cursor
663      * positioned either before the first row (negative position)
664      * or after the last row (positive position).
665      * NOTE: 0 is valid.
666      * NOTE: An exception is thrown if the cursor is not currently
667      * positioned on a row.
668      *
669      * @param row The position.
670      * @return The row at the relative position, or NULL if no such position.
671      *
672      * @exception StandardException Thrown on failure
673      * @see Row
674      */
675     public ExecRow getRelativeRow(int row) throws StandardException
676     {
677         if (SanityManager.DEBUG)
678         {
679             SanityManager.THROWASSERT(
680                 "getRelativeRow() not expected to be called yet.");
681         }
682
683         return null;
684     }
685
686     /**
687      * Sets the current position to before the first row and returns NULL
688      * because there is no current row.
689      *
690      * @return NULL.
691      *
692      * @exception StandardException Thrown on failure
693      * @see Row
694      */
695     public ExecRow setBeforeFirstRow()
696         throws StandardException
697     {
698         if (SanityManager.DEBUG)
699         {
700             SanityManager.THROWASSERT(
701                 "setBeforeFirstRow() not expected to be called yet.");
702         }
703
704         return null;
705     }
706
707     /**
708      * Returns the first row from the query, and returns NULL when there
709      * are no rows.
710      *
711      * @return The first row, or NULL if no rows.
712      *
713      * @exception StandardException Thrown on failure
714      * @see Row
715      */
716     public ExecRow getFirstRow()
717         throws StandardException
718     {
719         if (SanityManager.DEBUG)
720         {
721             SanityManager.THROWASSERT(
722                 "getFirstRow() not expected to be called yet.");
723         }
724
725         return null;
726     }
727
728     /**
729      * Returns the next row from the query, and returns NULL when there
730      * are no more rows.
731      *
732      * @return The next row, or NULL if no more rows.
733      *
734      * @exception StandardException Thrown on failure
735      * @see Row
736      */
737     public ExecRow getNextRow() throws StandardException
738     {
739         return getNextRowCore();
740     }
741
742     /**
743      * Returns the previous row from the query, and returns NULL when there
744      * are no more previous rows.
745      *
746      * @return The previous row, or NULL if no more previous rows.
747      *
748      * @exception StandardException Thrown on failure
749      * @see Row
750      */
751     public ExecRow getPreviousRow()
752         throws StandardException
753     {
754         if (SanityManager.DEBUG)
755         {
756             SanityManager.THROWASSERT(
757                 "getPreviousRow() not expected to be called yet.");
758         }
759
760         return null;
761     }
762
763     /**
764      * Returns the last row from the query, and returns NULL when there
765      * are no rows.
766      *
767      * @return The last row, or NULL if no rows.
768      *
769      * @exception StandardException Thrown on failure
770      * @see Row
771      */
772     public ExecRow getLastRow()
773         throws StandardException
774     {
775         if (SanityManager.DEBUG)
776         {
777             SanityManager.THROWASSERT(
778                 "getLastRow() not expected to be called yet.");
779         }
780
781         return null;
782     }
783
784     /**
785      * Sets the current position to after the last row and returns NULL
786      * because there is no current row.
787      *
788      * @return NULL.
789      *
790      * @exception StandardException Thrown on failure
791      * @see Row
792      */
793     public ExecRow setAfterLastRow()
794         throws StandardException
795     {
796         if (SanityManager.DEBUG)
797         {
798             SanityManager.THROWASSERT(
799                 "getLastRow() not expected to be called yet.");
800         }
801
802         return null;
803     }
804
805     /**
806      * Determine if the cursor is before the first row in the result
807      * set.
808      *
809      * @return true if before the first row, false otherwise. Returns
810      * false when the result set contains no rows.
811      */
812     public boolean checkRowPosition(int isType)
813     {
814         return false;
815     }
816
817     /**
818      * Returns the row number of the current row. Row
819      * numbers start from 1 and go to 'n'. Corresponds
820      * to row numbering used to position current row
821      * in the result set (as per JDBC).
822      *
823      * @return the row number, or 0 if not on a row
824      *
825      */
826     public int getRowNumber()
827     {
828         return 0;
829     }
830
831     /**
832      * Tells the system to clean up on an error.
833      *
834      * @exception StandardException Thrown on error.
835      */
836     public void cleanUp() throws StandardException
837     {
838         close();
839     }
840
841
842     /**
843         Find out if the ResultSet is closed or not.
844         Will report true for result sets that do not return rows.
845
846         @return true if the ResultSet has been closed.
847      */
848     public boolean isClosed()
849     {
850         return !isOpen;
851     }
852
853     /**
854      * Tells the system that there will be no more access
855      * to any database information via this result set;
856      * in particular, no more calls to open().
857      * Will close the result set if it is not already closed.
858      *
859      * @exception StandardException on error
860      */
861     public void finish() throws StandardException
862     {
863         finished = true;
864         close();
865     }
866
867
868     /**
869      * Get the execution time in milliseconds.
870      *
871      * @return long The execution time in milliseconds.
872      */
873     public long getExecuteTime()
874     {
875         return 0L;
876     }
877
878     /**
879      * @see ResultSet#getAutoGeneratedKeysResultset
880      */
881     public ResultSet getAutoGeneratedKeysResultset()
882     {
883         //A non-null resultset would be returned only for an insert statement
884 return (ResultSet)null;
885     }
886
887     /**
888      * Get the Timestamp for the beginning of execution.
889      *
890      * @return Timestamp The Timestamp for the beginning of execution.
891      */
892     public Timestamp JavaDoc getBeginExecutionTimestamp()
893     {
894         return (Timestamp JavaDoc)null;
895     }
896
897     /**
898      * Get the Timestamp for the end of execution.
899      *
900      * @return Timestamp The Timestamp for the end of execution.
901      */
902     public Timestamp JavaDoc getEndExecutionTimestamp()
903     {
904         return (Timestamp JavaDoc)null;
905     }
906
907     /**
908      * Return the total amount of time spent in this ResultSet
909      *
910      * @param type CURRENT_RESULTSET_ONLY - time spent only in this ResultSet
911      * ENTIRE_RESULTSET_TREE - time spent in this ResultSet and below.
912      *
913      * @return long The total amount of time spent (in milliseconds).
914      */
915     public long getTimeSpent(int type)
916     {
917         return 0L;
918     }
919
920
921     /**
922      * Get the subquery ResultSet tracking array from the top ResultSet.
923      * (Used for tracking open subqueries when closing down on an error.)
924      *
925      * @param numSubqueries The size of the array (For allocation on demand.)
926      *
927      * @return NoPutResultSet[] Array of NoPutResultSets for subqueries.
928      */
929     public NoPutResultSet[] getSubqueryTrackingArray(int numSubqueries)
930     {
931         return (NoPutResultSet[])null;
932     }
933
934     /**
935      * Returns the name of the cursor, if this is cursor statement of some
936      * type (declare, open, fetch, positioned update, positioned delete,
937      * close).
938      *
939      * @return A String with the name of the cursor, if any. Returns
940      * NULL if this is not a cursor statement.
941      */
942     public String JavaDoc getCursorName()
943     {
944         return (String JavaDoc) null;
945     }
946
947     /**
948      * @see NoPutResultSet#requiresRelocking
949      */
950     public boolean requiresRelocking()
951     {
952         if (SanityManager.DEBUG)
953         {
954             SanityManager.THROWASSERT(
955                 "requiresRelocking() not expected to be called for " +
956                 getClass().getName());
957         }
958         return false;
959     }
960
961     /////////////////////////////////////////////////////////
962 //
963 // Access/RowSource -- not implemented
964 //
965 /////////////////////////////////////////////////////////
966 /**
967         Get the next row as an array of column objects. The column objects can
968         be a JBMS Storable or any
969         Serializable/Externalizable/Formattable/Streaming type.
970         <BR>
971         A return of null indicates that the complete set of rows has been read.
972
973         <p>
974         A null column can be specified by leaving the object null, or indicated
975         by returning a non-null getValidColumns. On streaming columns, it can
976         be indicated by returning a non-null get FieldStates.
977
978         <p>
979         If RowSource.needToClone() is true then the returned row (the
980         DataValueDescriptor[]) is guaranteed not to be modified by drainer of
981         the RowSource (except that the input stream will be read, of course)
982         and drainer will keep no reference to it before making the subsequent
983         nextRow call. So it is safe to return the same DataValueDescriptor[]
984         in subsequent nextRow calls if that is desirable for performance
985         reasons.
986         <p>
987         If RowSource.needToClone() is false then the returned row (the
988         DataValueDescriptor[]) may be be modified by drainer of the RowSource,
989         and the drainer may keep a reference to it after making the subsequent
990         nextRow call. In this case the client should severe all references to
991         the row after returning it from getNextRowFromRowSource().
992
993         @exception StandardException Cloudscape Standard Error Policy
994      */
995     public DataValueDescriptor[] getNextRowFromRowSource() throws StandardException
996     {
997         return null;
998     }
999
1000    /**
1001        Does the caller of getNextRowFromRowSource() need to clone the row
1002        in order to keep a reference to the row past the
1003        getNextRowFromRowSource() call which returned the row. This call
1004        must always return the same for all rows in a RowSource (ie. the
1005        caller will call this once per scan from a RowSource and assume the
1006        behavior is true for all rows in the RowSource).
1007
1008     */
1009    public boolean needsToClone()
1010    {
1011        return false;
1012    }
1013
1014
1015    /**
1016      getValidColumns describes the DataValueDescriptor[] returned by all
1017      calls to the getNextRowFromRowSource() call.
1018
1019      If getValidColumns returns null, the number of columns is given by the
1020      DataValueDescriptor.length where DataValueDescriptor[] is returned by the
1021      preceeding getNextRowFromRowSource() call. Column N maps to
1022      DataValueDescriptor[N], where column numbers start at zero.
1023
1024      If getValidColumns return a non null validColumns FormatableBitSet the number of
1025      columns is given by the number of bits set in validColumns. Column N is
1026      not in the partial row if validColumns.get(N) returns false. Column N is
1027      in the partial row if validColumns.get(N) returns true. If column N is
1028      in the partial row then it maps to DataValueDescriptor[M] where M is the
1029      count of calls to validColumns.get(i) that return true where i < N. If
1030      DataValueDescriptor.length is greater than the number of columns
1031      indicated by validColumns the extra entries are ignored.
1032    */
1033    public FormatableBitSet getValidColumns()
1034    {
1035        return null;
1036    }
1037
1038    /**
1039        closeRowSource tells the RowSource that it will no longer need to
1040        return any rows and it can release any resource it may have.
1041        Subsequent call to any method on the RowSource will result in undefined
1042        behavior. A closed rowSource can be closed again.
1043    */
1044    public void closeRowSource()
1045    { }
1046
1047
1048    /////////////////////////////////////////////////////////
1049 //
1050 // Access/RowLocationRetRowSource -- not implemented
1051 //
1052 /////////////////////////////////////////////////////////
1053 /**
1054        needsRowLocation returns true iff this the row source expects the
1055        drainer of the row source to call rowLocation after getting a row from
1056        getNextRowFromRowSource.
1057
1058        @return true iff this row source expects some row location to be
1059        returned
1060        @see #rowLocation
1061     */
1062    public boolean needsRowLocation()
1063    {
1064        return false;
1065    }
1066
1067    /**
1068        rowLocation is a callback for the drainer of the row source to return
1069        the rowLocation of the current row, i.e, the row that is being returned
1070        by getNextRowFromRowSource. This interface is for the purpose of
1071        loading a base table with index. In that case, the indices can be
1072        built at the same time the base table is laid down once the row
1073        location of the base row is known. This is an example pseudo code on
1074        how this call is expected to be used:
1075        
1076        <BR><pre>
1077        boolean needsRL = rowSource.needsRowLocation();
1078        DataValueDescriptor[] row;
1079        while((row = rowSource.getNextRowFromRowSource()) != null)
1080        {
1081            RowLocation rl = heapConglomerate.insertRow(row);
1082            if (needsRL)
1083                rowSource.rowLocation(rl);
1084        }
1085        </pre><BR>
1086
1087        NeedsRowLocation and rowLocation will ONLY be called by a drainer of
1088        the row source which CAN return a row location. Drainer of row source
1089        which cannot return rowLocation will guarentee to not call either
1090        callbacks. Conversely, if NeedsRowLocation is called and it returns
1091        true, then for every row return by getNextRowFromRowSource, a
1092        rowLocation callback must also be issued with the row location of the
1093        row. Implementor of both the source and the drain of the row source
1094        must be aware of this protocol.
1095
1096        <BR>
1097        The RowLocation object is own by the caller of rowLocation, in other
1098        words, the drainer of the RowSource. This is so that we don't need to
1099        new a row location for every row. If the Row Source wants to keep the
1100        row location, it needs to clone it (RowLocation is a ClonableObject).
1101        @exception StandardException on error
1102     */
1103    public void rowLocation(RowLocation rl) throws StandardException
1104    { }
1105
1106    /**
1107     * @see NoPutResultSet#positionScanAtRowLocation
1108     *
1109     * This method is result sets used for scroll insensitive updatable
1110     * result sets for other result set it is a no-op.
1111     */
1112    public void positionScanAtRowLocation(RowLocation rl)
1113        throws StandardException
1114    {
1115        // Only used for Scrollable insensitive result sets otherwise no-op
1116 }
1117
1118    // Class implementation
1119
1120    /**
1121     * Is this ResultSet or it's source result set for update
1122     * This method will be overriden in the inherited Classes
1123     * if it is true
1124     * @return Whether or not the result set is for update.
1125     */
1126    public boolean isForUpdate()
1127    {
1128        return false;
1129    }
1130
1131    /**
1132     * Shallow clone this result set. Used in trigger reference.
1133     * beetle 4373.
1134     */
1135    public Object JavaDoc clone()
1136    {
1137        Object JavaDoc clo = null;
1138        try {
1139            clo = super.clone();
1140        }
1141        catch (CloneNotSupportedException JavaDoc e) {}
1142        return clo;
1143    }
1144    public java.sql.SQLWarning JavaDoc getWarnings() {
1145        return null;
1146    }
1147
1148    /**
1149     * @see NoPutResultSet#updateRow
1150     *
1151     * This method is result sets used for scroll insensitive updatable
1152     * result sets for other result set it is a no-op.
1153     */
1154    public void updateRow(ExecRow row) throws StandardException {
1155        // Only ResultSets of type Scroll Insensitive implement
1156 // detectability, so for other result sets this method
1157 // is a no-op
1158 }
1159 
1160    /**
1161     * @see NoPutResultSet#markRowAsDeleted
1162     *
1163     * This method is result sets used for scroll insensitive updatable
1164     * result sets for other result set it is a no-op.
1165     */
1166    public void markRowAsDeleted() throws StandardException {
1167        // Only ResultSets of type Scroll Insensitive implement
1168 // detectability, so for other result sets this method
1169 // is a no-op
1170 }
1171
1172    /**
1173     * Return the <code>Activation</code> for this result set.
1174     *
1175     * @return activation
1176     */
1177    public final Activation getActivation() {
1178        return holder.activation;
1179    }
1180}
1181
Popular Tags