001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.ResultSet
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.sql;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.sql.execute.ExecRow;
027: import org.apache.derby.iapi.sql.execute.NoPutResultSet;
028: import org.apache.derby.iapi.sql.Row;
029:
030: import java.sql.Timestamp;
031: import java.sql.SQLWarning;
032:
033: /**
034: * The ResultSet interface provides a method to tell whether a statement
035: * returns rows, and if so, a method to get the rows. It also provides a
036: * method to get metadata about the contents of the rows. It also provide
037: * a method to accept rows as input.
038: * <p>
039: * There is no single implementation of the ResultSet interface. Instead,
040: * the various support operations involved in executing statements
041: * implement this interface.
042: * <p>
043: * Although ExecRow is used on the interface, it is not available to
044: * users of the API. They should use Row, the exposed super-interface
045: * of ExecRow. <<I couldn't find another way to perform this mapping...>>
046: * <p>
047: * Valid transitions: <ul>
048: * <li> open->close</li>
049: * <li> close->open</li>
050: * <li> close->finished</li>
051: * <li> finished->open</li>
052: * </ul>
053: *
054: * @author Jeff Lichtman
055: */
056:
057: public interface ResultSet {
058: /* Get time only spent in this ResultSet */
059: public static final int CURRENT_RESULTSET_ONLY = 0;
060: /* Get time spent in this ResultSet and below */
061: public static final int ENTIRE_RESULTSET_TREE = 1;
062:
063: // cursor check positioning
064: public static final int ISBEFOREFIRST = 101;
065: public static final int ISFIRST = 102;
066: public static final int ISLAST = 103;
067: public static final int ISAFTERLAST = 104;
068:
069: /**
070: * Returns TRUE if the statement returns rows (i.e. is a SELECT
071: * or FETCH statement), FALSE if it returns no rows.
072: *
073: * @return TRUE if the statement returns rows, FALSE if not.
074: */
075: boolean returnsRows();
076:
077: /**
078: * Returns the number of rows affected by the statement.
079: Only valid of returnsRows() returns false.
080: * For other DML statements, it returns the number of rows
081: * modified by the statement. For statements that do not affect rows
082: * (like DDL statements), it returns zero.
083: *
084: * @return The number of rows affect by the statement, so far.
085: */
086: int modifiedRowCount();
087:
088: /**
089: * Returns a ResultDescription object, which describes the results
090: * of the statement this ResultSet is in. This will *not* be a
091: * description of this particular ResultSet, if this is not the
092: * outermost ResultSet.
093: *
094: * @return A ResultDescription describing the results of the
095: * statement.
096: */
097: ResultDescription getResultDescription();
098:
099: Activation getActivation();
100:
101: /**
102: * Needs to be called before the result set will do anything.
103: * Need to call before getNextRow(), or for a result set
104: * that doesn't return rows, this is the call that will
105: * cause all the work to be done.
106: *
107: * @exception StandardException Thrown on failure
108: */
109: void open() throws StandardException;
110:
111: /**
112: * Returns the row at the absolute position from the query,
113: * and returns NULL when there is no such position.
114: * (Negative position means from the end of the result set.)
115: * Moving the cursor to an invalid position leaves the cursor
116: * positioned either before the first row (negative position)
117: * or after the last row (positive position).
118: * NOTE: An exception will be thrown on 0.
119: *
120: * @param row The position.
121: * @return The row at the absolute position, or NULL if no such position.
122: *
123: * @exception StandardException Thrown on failure
124: * @see Row
125: */
126: ExecRow getAbsoluteRow(int row) throws StandardException;
127:
128: /**
129: * Returns the row at the relative position from the current
130: * cursor position, and returns NULL when there is no such position.
131: * (Negative position means toward the beginning of the result set.)
132: * Moving the cursor to an invalid position leaves the cursor
133: * positioned either before the first row (negative position)
134: * or after the last row (positive position).
135: * NOTE: 0 is valid.
136: * NOTE: An exception is thrown if the cursor is not currently
137: * positioned on a row.
138: *
139: * @param row The position.
140: * @return The row at the relative position, or NULL if no such position.
141: *
142: * @exception StandardException Thrown on failure
143: * @see Row
144: */
145: ExecRow getRelativeRow(int row) throws StandardException;
146:
147: /**
148: * Sets the current position to before the first row and returns NULL
149: * because there is no current row.
150: *
151: * @return NULL.
152: *
153: * @exception StandardException Thrown on failure
154: * @see Row
155: */
156: ExecRow setBeforeFirstRow() throws StandardException;
157:
158: /**
159: * Returns the first row from the query, and returns NULL when there
160: * are no rows.
161: *
162: * @return The first row, or NULL if no rows.
163: *
164: * @exception StandardException Thrown on failure
165: * @see Row
166: */
167: ExecRow getFirstRow() throws StandardException;
168:
169: /**
170: * Returns the next row from the query, and returns NULL when there
171: * are no more rows.
172: *
173: * @return The next row, or NULL if no more rows.
174: *
175: * @exception StandardException Thrown on failure
176: * @see Row
177: */
178: ExecRow getNextRow() throws StandardException;
179:
180: /**
181: * Returns the previous row from the query, and returns NULL when there
182: * are no more previous rows.
183: *
184: * @return The previous row, or NULL if no more previous rows.
185: *
186: * @exception StandardException Thrown on failure
187: * @see Row
188: */
189: ExecRow getPreviousRow() throws StandardException;
190:
191: /**
192: * Returns the last row from the query, and returns NULL when there
193: * are no rows.
194: *
195: * @return The last row, or NULL if no rows.
196: *
197: * @exception StandardException Thrown on failure
198: * @see Row
199: */
200: ExecRow getLastRow() throws StandardException;
201:
202: /**
203: * Sets the current position to after the last row and returns NULL
204: * because there is no current row.
205: *
206: * @return NULL.
207: *
208: * @exception StandardException Thrown on failure
209: * @see Row
210: */
211: ExecRow setAfterLastRow() throws StandardException;
212:
213: /**
214: * Clear the current row. The cursor keeps it current position,
215: * however it cannot be used for positioned updates or deletes
216: * until a fetch is done.
217: * This is done after a commit on holdable
218: * result sets.
219: * A fetch is achieved by calling one of the positioning
220: * methods: getLastRow(), getNextRow(), getPreviousRow(),
221: * getFirstRow(), getRelativeRow(..) or getAbsoluteRow(..).
222: */
223: void clearCurrentRow();
224:
225: /**
226: Determine if the result set is at one of the positions
227: according to the constants above (ISBEFOREFIRST etc).
228: Only valid and called for scrollable cursors.
229: * @return true if at the requested position.
230: * @exception StandardException Thrown on error.
231: */
232: public boolean checkRowPosition(int isType)
233: 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: }
|