ResultSet


1   /*
2   
3      Derby - Class org.apache.derby.iapi.sql.ResultSet
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.sql;
23  
24  import org.apache.derby.iapi.error.StandardException;
25  
26  import org.apache.derby.iapi.sql.execute.ExecRow;
27  import org.apache.derby.iapi.sql.execute.NoPutResultSet;
28  import org.apache.derby.iapi.sql.Row;
29  
30  import java.sql.Timestamp  ;
31  import java.sql.SQLWarning  ;
32  
33  /**
34   * The ResultSet interface provides a method to tell whether a statement
35   * returns rows, and if so, a method to get the rows. It also provides a
36   * method to get metadata about the contents of the rows. It also provide
37   * a method to accept rows as input.
38   * <p>
39   * There is no single implementation of the ResultSet interface. Instead,
40   * the various support operations involved in executing statements
41   * implement this interface.
42   * <p>
43   * Although ExecRow is used on the interface, it is not available to
44   * users of the API. They should use Row, the exposed super-interface
45   * of ExecRow.  <<I couldn't find another way to perform this mapping...>>
46   * <p>
47   * Valid transitions: <ul>
48   * <li> open->close</li>
49   * <li> close->open</li>
50   * <li> close->finished</li>
51   * <li> finished->open</li>
52   * </ul>
53   *
54   * @author Jeff Lichtman
55   */
56  
57  public interface ResultSet
58  {
59      /* Get time only spent in this ResultSet */
60      public static final int CURRENT_RESULTSET_ONLY = 0;
61      /* Get time spent in this ResultSet and below */
62      public static final int ENTIRE_RESULTSET_TREE = 1;
63  
64      // cursor check positioning
65      public static final int ISBEFOREFIRST = 101;
66      public static final int ISFIRST = 102;
67      public static final int ISLAST = 103;
68      public static final int ISAFTERLAST = 104;
69  
70      /**
71       * Returns TRUE if the statement returns rows (i.e. is a SELECT
72       * or FETCH statement), FALSE if it returns no rows.
73       *
74       * @return  TRUE if the statement returns rows, FALSE if not.
75       */
76       boolean    returnsRows();
77  
78      /**
79       * Returns the number of rows affected by the statement.
80         Only valid of returnsRows() returns false.
81       * For other DML statements, it returns the number of rows
82       * modified by the statement. For statements that do not affect rows
83       * (like DDL statements), it returns zero.
84       *
85       * @return  The number of rows affect by the statement, so far.
86       */
87      int modifiedRowCount();
88  
89      /**
90       * Returns a ResultDescription object, which describes the results
91       * of the statement this ResultSet is in. This will *not* be a
92       * description of this particular ResultSet, if this is not the
93       * outermost ResultSet.
94       *
95       * @return  A ResultDescription describing the results of the
96       *      statement.
97       */
98      ResultDescription   getResultDescription();
99      
100     Activation getActivation();
101 
102     /**
103      * Needs to be called before the result set will do anything.
104      * Need to call before getNextRow(), or for a result set
105      * that doesn't return rows, this is the call that will
106      * cause all the work to be done.
107      *
108      * @exception StandardException     Thrown on failure
109      */
110     void    open() throws StandardException;
111 
112     /**
113      * Returns the row at the absolute position from the query, 
114      * and returns NULL when there is no such position.
115      * (Negative position means from the end of the result set.)
116      * Moving the cursor to an invalid position leaves the cursor
117      * positioned either before the first row (negative position)
118      * or after the last row (positive position).
119      * NOTE: An exception will be thrown on 0.
120      *
121      * @param row   The position.
122      * @return  The row at the absolute position, or NULL if no such position.
123      *
124      * @exception StandardException     Thrown on failure
125      * @see Row
126      */
127     ExecRow getAbsoluteRow(int row) throws StandardException;
128 
129     /**
130      * Returns the row at the relative position from the current
131      * cursor position, and returns NULL when there is no such position.
132      * (Negative position means toward the beginning of the result set.)
133      * Moving the cursor to an invalid position leaves the cursor
134      * positioned either before the first row (negative position)
135      * or after the last row (positive position).
136      * NOTE: 0 is valid.
137      * NOTE: An exception is thrown if the cursor is not currently
138      * positioned on a row.
139      *
140      * @param row   The position.
141      * @return  The row at the relative position, or NULL if no such position.
142      *
143      * @exception StandardException     Thrown on failure
144      * @see Row
145      */
146     ExecRow getRelativeRow(int row) throws StandardException;
147 
148     /**
149      * Sets the current position to before the first row and returns NULL
150      * because there is no current row.
151      *
152      * @return  NULL.
153      *
154      * @exception StandardException     Thrown on failure
155      * @see Row
156      */
157     ExecRow setBeforeFirstRow() throws StandardException;
158 
159     /**
160      * Returns the first row from the query, and returns NULL when there
161      * are no rows.
162      *
163      * @return  The first row, or NULL if no rows.
164      *
165      * @exception StandardException     Thrown on failure
166      * @see Row
167      */
168     ExecRow getFirstRow() throws StandardException;
169 
170     /**
171      * Returns the next row from the query, and returns NULL when there
172      * are no more rows.
173      *
174      * @return  The next row, or NULL if no more rows.
175      *
176      * @exception StandardException     Thrown on failure
177      * @see Row
178      */
179     ExecRow getNextRow() throws StandardException;
180 
181     /**
182      * Returns the previous row from the query, and returns NULL when there
183      * are no more previous rows.
184      *
185      * @return  The previous row, or NULL if no more previous rows.
186      *
187      * @exception StandardException     Thrown on failure
188      * @see Row
189      */
190     ExecRow getPreviousRow() throws StandardException;
191 
192     /**
193      * Returns the last row from the query, and returns NULL when there
194      * are no rows.
195      *
196      * @return  The last row, or NULL if no rows.
197      *
198      * @exception StandardException     Thrown on failure
199      * @see Row
200      */
201     ExecRow getLastRow() throws StandardException;
202 
203     /**
204      * Sets the current position to after the last row and returns NULL
205      * because there is no current row.
206      *
207      * @return  NULL.
208      *
209      * @exception StandardException     Thrown on failure
210      * @see Row
211      */
212     ExecRow setAfterLastRow() throws StandardException;
213 
214     /**
215      * Clear the current row. The cursor keeps it current position,
216      * however it cannot be used for positioned updates or deletes
217      * until a fetch is done.
218      * This is done after a commit on holdable
219      * result sets.
220      * A fetch is achieved by calling one of the positioning 
221      * methods: getLastRow(), getNextRow(), getPreviousRow(), 
222      * getFirstRow(), getRelativeRow(..) or getAbsoluteRow(..).
223      */
224     void clearCurrentRow();
225      
226     /**
227         Determine if the result set is at one of the positions
228         according to the constants above (ISBEFOREFIRST etc).
229         Only valid and called for scrollable cursors.
230      * @return true if at the requested position.
231      * @exception StandardException Thrown on error.
232      */
233     public boolean checkRowPosition(int isType) throws StandardException;
234 
235     /**
236      * Returns the row number of the current row.  Row
237      * numbers start from 1 and go to 'n'.  Corresponds
238      * to row numbering used to position current row
239      * in the result set (as per JDBC).
240 
241         Only valid and called for scrollable cursors.
242      * @return  the row number, or 0 if not on a row
243      *
244      */
245     int getRowNumber();
246 
247     /**
248      * Tells the system that there will be no more calls to getNextRow()
249      * (until the next open() call), so it can free up the resources
250      * associated with the ResultSet.
251      *
252      * @exception StandardException     Thrown on error.
253      */
254     void    close() throws StandardException;
255 
256     /**
257      * Tells the system to clean up on an error.
258      *
259      * @exception StandardException     Thrown on error.
260      */
261     void    cleanUp() throws StandardException;
262 
263     /**
264         Find out if the ResultSet is closed or not.
265         Will report true for result sets that do not return rows.
266 
267         @return true if the ResultSet has been closed.
268      */
269     boolean isClosed();
270 
271     /**
272      * Tells the system that there will be no more access
273      * to any database information via this result set;
274      * in particular, no more calls to open().
275      * Will close the result set if it is not already closed.
276      *
277      * @exception StandardException on error
278      */
279     void    finish() throws StandardException;
280 
281     /**
282      * Get the execution time in milliseconds.
283      *
284      * @return long     The execution time in milliseconds.
285      */
286     public long getExecuteTime();
287 
288     /**
289      * Get the Timestamp for the beginning of execution.
290      *
291      * @return Timestamp        The Timestamp for the beginning of execution.
292      */
293     public Timestamp   getBeginExecutionTimestamp();
294 
295     /**
296      * Get the Timestamp for the end of execution.
297      *
298      * @return Timestamp        The Timestamp for the end of execution.
299      */
300     public Timestamp   getEndExecutionTimestamp();
301 
302     /**
303      * Return the total amount of time spent in this ResultSet
304      *
305      * @param type  CURRENT_RESULTSET_ONLY - time spent only in this ResultSet
306      *              ENTIRE_RESULTSET_TREE  - time spent in this ResultSet and below.
307      *
308      * @return long     The total amount of time spent (in milliseconds).
309      */
310     public long getTimeSpent(int type); 
311 
312     /**
313      * Get the subquery ResultSet tracking array from the top ResultSet.
314      * (Used for tracking open subqueries when closing down on an error.)
315      *
316      * @param numSubqueries     The size of the array (For allocation on demand.)
317      *
318      * @return NoPutResultSet[] Array of NoPutResultSets for subqueries.
319      */
320     public NoPutResultSet[] getSubqueryTrackingArray(int numSubqueries);
321 
322     /**
323      * ResultSet for rows inserted into the table (contains auto-generated keys columns only)
324      *
325      * @return NoPutResultSet   NoPutResultSets for rows inserted into the table.
326      */
327     public ResultSet getAutoGeneratedKeysResultset();
328 
329     /**
330      * Returns the name of the cursor, if this is cursor statement of some
331      * type (declare, open, fetch, positioned update, positioned delete,
332      * close).
333      *
334      * @return  A String with the name of the cursor, if any. Returns
335      *      NULL if this is not a cursor statement.
336      */
337     public String     getCursorName();
338 
339     /**
340         Return the set of warnings generated during the execution of
341         this result set. The warnings are cleared once this call returns.
342     */
343     public SQLWarning   getWarnings();
344 }
345
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags