--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.sql.ResultSet\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.sql;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.sql.execute.ExecRow;\r
+import org.apache.derby.iapi.sql.execute.NoPutResultSet;\r
+import org.apache.derby.iapi.sql.Row;\r
+\r
+import java.sql.Timestamp;\r
+import java.sql.SQLWarning;\r
+\r
+/**\r
+ * The ResultSet interface provides a method to tell whether a statement\r
+ * returns rows, and if so, a method to get the rows. It also provides a\r
+ * method to get metadata about the contents of the rows. It also provide\r
+ * a method to accept rows as input.\r
+ * <p>\r
+ * There is no single implementation of the ResultSet interface. Instead,\r
+ * the various support operations involved in executing statements\r
+ * implement this interface.\r
+ * <p>\r
+ * Although ExecRow is used on the interface, it is not available to\r
+ * users of the API. They should use Row, the exposed super-interface\r
+ * of ExecRow. <<I couldn't find another way to perform this mapping...>>\r
+ * <p>\r
+ * Valid transitions: <ul>\r
+ * <li> open->close</li>\r
+ * <li> close->open</li>\r
+ * <li> close->finished</li>\r
+ * <li> finished->open</li>\r
+ * </ul>\r
+ *\r
+ */\r
+\r
+public interface ResultSet\r
+{\r
+ /* Get time only spent in this ResultSet */\r
+ public static final int CURRENT_RESULTSET_ONLY = 0;\r
+ /* Get time spent in this ResultSet and below */\r
+ public static final int ENTIRE_RESULTSET_TREE = 1;\r
+\r
+ // cursor check positioning\r
+ public static final int ISBEFOREFIRST = 101;\r
+ public static final int ISFIRST = 102;\r
+ public static final int ISLAST = 103;\r
+ public static final int ISAFTERLAST = 104;\r
+\r
+ /**\r
+ * Returns TRUE if the statement returns rows (i.e. is a SELECT\r
+ * or FETCH statement), FALSE if it returns no rows.\r
+ *\r
+ * @return TRUE if the statement returns rows, FALSE if not.\r
+ */\r
+ boolean returnsRows();\r
+\r
+ /**\r
+ * Returns the number of rows affected by the statement.\r
+ Only valid of returnsRows() returns false.\r
+ * For other DML statements, it returns the number of rows\r
+ * modified by the statement. For statements that do not affect rows\r
+ * (like DDL statements), it returns zero.\r
+ *\r
+ * @return The number of rows affect by the statement, so far.\r
+ */\r
+ int modifiedRowCount();\r
+\r
+ /**\r
+ * Returns a ResultDescription object, which describes the results\r
+ * of the statement this ResultSet is in. This will *not* be a\r
+ * description of this particular ResultSet, if this is not the\r
+ * outermost ResultSet.\r
+ *\r
+ * @return A ResultDescription describing the results of the\r
+ * statement.\r
+ */\r
+ ResultDescription getResultDescription();\r
+ \r
+ Activation getActivation();\r
+\r
+ /**\r
+ * Needs to be called before the result set will do anything.\r
+ * Need to call before getNextRow(), or for a result set\r
+ * that doesn't return rows, this is the call that will\r
+ * cause all the work to be done.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ */\r
+ void open() throws StandardException;\r
+\r
+ /**\r
+ * Returns the row at the absolute position from the query, \r
+ * and returns NULL when there is no such position.\r
+ * (Negative position means from the end of the result set.)\r
+ * Moving the cursor to an invalid position leaves the cursor\r
+ * positioned either before the first row (negative position)\r
+ * or after the last row (positive position).\r
+ * NOTE: An exception will be thrown on 0.\r
+ *\r
+ * @param row The position.\r
+ * @return The row at the absolute position, or NULL if no such position.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getAbsoluteRow(int row) throws StandardException;\r
+\r
+ /**\r
+ * Returns the row at the relative position from the current\r
+ * cursor position, and returns NULL when there is no such position.\r
+ * (Negative position means toward the beginning of the result set.)\r
+ * Moving the cursor to an invalid position leaves the cursor\r
+ * positioned either before the first row (negative position)\r
+ * or after the last row (positive position).\r
+ * NOTE: 0 is valid.\r
+ * NOTE: An exception is thrown if the cursor is not currently\r
+ * positioned on a row.\r
+ *\r
+ * @param row The position.\r
+ * @return The row at the relative position, or NULL if no such position.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getRelativeRow(int row) throws StandardException;\r
+\r
+ /**\r
+ * Sets the current position to before the first row and returns NULL\r
+ * because there is no current row.\r
+ *\r
+ * @return NULL.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow setBeforeFirstRow() throws StandardException;\r
+\r
+ /**\r
+ * Returns the first row from the query, and returns NULL when there\r
+ * are no rows.\r
+ *\r
+ * @return The first row, or NULL if no rows.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getFirstRow() throws StandardException;\r
+\r
+ /**\r
+ * Returns the next row from the query, and returns NULL when there\r
+ * are no more rows.\r
+ *\r
+ * @return The next row, or NULL if no more rows.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getNextRow() throws StandardException;\r
+\r
+ /**\r
+ * Returns the previous row from the query, and returns NULL when there\r
+ * are no more previous rows.\r
+ *\r
+ * @return The previous row, or NULL if no more previous rows.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getPreviousRow() throws StandardException;\r
+\r
+ /**\r
+ * Returns the last row from the query, and returns NULL when there\r
+ * are no rows.\r
+ *\r
+ * @return The last row, or NULL if no rows.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow getLastRow() throws StandardException;\r
+\r
+ /**\r
+ * Sets the current position to after the last row and returns NULL\r
+ * because there is no current row.\r
+ *\r
+ * @return NULL.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ * @see Row\r
+ */\r
+ ExecRow setAfterLastRow() throws StandardException;\r
+\r
+ /**\r
+ * Clear the current row. The cursor keeps it current position,\r
+ * however it cannot be used for positioned updates or deletes\r
+ * until a fetch is done.\r
+ * This is done after a commit on holdable\r
+ * result sets.\r
+ * A fetch is achieved by calling one of the positioning \r
+ * methods: getLastRow(), getNextRow(), getPreviousRow(), \r
+ * getFirstRow(), getRelativeRow(..) or getAbsoluteRow(..).\r
+ */\r
+ void clearCurrentRow();\r
+ \r
+ /**\r
+ Determine if the result set is at one of the positions\r
+ according to the constants above (ISBEFOREFIRST etc).\r
+ Only valid and called for scrollable cursors.\r
+ * @return true if at the requested position.\r
+ * @exception StandardException Thrown on error.\r
+ */\r
+ public boolean checkRowPosition(int isType) throws StandardException;\r
+\r
+ /**\r
+ * Returns the row number of the current row. Row\r
+ * numbers start from 1 and go to 'n'. Corresponds\r
+ * to row numbering used to position current row\r
+ * in the result set (as per JDBC).\r
+\r
+ Only valid and called for scrollable cursors.\r
+ * @return the row number, or 0 if not on a row\r
+ *\r
+ */\r
+ int getRowNumber();\r
+\r
+ /**\r
+ * Tells the system that there will be no more calls to getNextRow()\r
+ * (until the next open() call), so it can free up the resources\r
+ * associated with the ResultSet.\r
+ *\r
+ * @exception StandardException Thrown on error.\r
+ */\r
+ void close() throws StandardException;\r
+\r
+ /**\r
+ * Tells the system to clean up on an error.\r
+ *\r
+ * @exception StandardException Thrown on error.\r
+ */\r
+ void cleanUp() throws StandardException;\r
+\r
+ /**\r
+ Find out if the ResultSet is closed or not.\r
+ Will report true for result sets that do not return rows.\r
+\r
+ @return true if the ResultSet has been closed.\r
+ */\r
+ boolean isClosed();\r
+\r
+ /**\r
+ * Tells the system that there will be no more access\r
+ * to any database information via this result set;\r
+ * in particular, no more calls to open().\r
+ * Will close the result set if it is not already closed.\r
+ *\r
+ * @exception StandardException on error\r
+ */\r
+ void finish() throws StandardException;\r
+\r
+ /**\r
+ * Get the execution time in milliseconds.\r
+ *\r
+ * @return long The execution time in milliseconds.\r
+ */\r
+ public long getExecuteTime();\r
+\r
+ /**\r
+ * Get the Timestamp for the beginning of execution.\r
+ *\r
+ * @return Timestamp The Timestamp for the beginning of execution.\r
+ */\r
+ public Timestamp getBeginExecutionTimestamp();\r
+\r
+ /**\r
+ * Get the Timestamp for the end of execution.\r
+ *\r
+ * @return Timestamp The Timestamp for the end of execution.\r
+ */\r
+ public Timestamp getEndExecutionTimestamp();\r
+\r
+ /**\r
+ * Return the total amount of time spent in this ResultSet\r
+ *\r
+ * @param type CURRENT_RESULTSET_ONLY - time spent only in this ResultSet\r
+ * ENTIRE_RESULTSET_TREE - time spent in this ResultSet and below.\r
+ *\r
+ * @return long The total amount of time spent (in milliseconds).\r
+ */\r
+ public long getTimeSpent(int type); \r
+\r
+ /**\r
+ * Get the subquery ResultSet tracking array from the top ResultSet.\r
+ * (Used for tracking open subqueries when closing down on an error.)\r
+ *\r
+ * @param numSubqueries The size of the array (For allocation on demand.)\r
+ *\r
+ * @return NoPutResultSet[] Array of NoPutResultSets for subqueries.\r
+ */\r
+ public NoPutResultSet[] getSubqueryTrackingArray(int numSubqueries);\r
+\r
+ /**\r
+ * ResultSet for rows inserted into the table (contains auto-generated keys columns only)\r
+ *\r
+ * @return NoPutResultSet NoPutResultSets for rows inserted into the table.\r
+ */\r
+ public ResultSet getAutoGeneratedKeysResultset();\r
+\r
+ /**\r
+ * Returns the name of the cursor, if this is cursor statement of some\r
+ * type (declare, open, fetch, positioned update, positioned delete,\r
+ * close).\r
+ *\r
+ * @return A String with the name of the cursor, if any. Returns\r
+ * NULL if this is not a cursor statement.\r
+ */\r
+ public String getCursorName();\r
+\r
+ /**\r
+ Return the set of warnings generated during the execution of\r
+ this result set. The warnings are cleared once this call returns.\r
+ */\r
+ public SQLWarning getWarnings();\r
+}\r